REST API

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：24分

    • REST (REpresentational State Transfer) は、Web 上のコンピューターシステム間の標準を提供し、相互の通信を容易にするシンプルなステートレスアーキテクチャです。

    Now Platform は、デフォルトで有効になっているさまざまな REST API を提供します。これらの API には、アプリケーション内のさまざまな ServiceNow 機能とやり取りする機能があります。このような機能には、既存のテーブルでの作成、読み取り、更新、削除 (CRUD) 操作 (テーブル API)、MetricBase データベースに対するデータの挿入、情報の取得、変換の実行 (MetricBase 時系列 API)、およびその他多くの機能があります。

    利用可能な REST APIs のリストについては、「REST API リファレンス」を参照してください。

    注:
    受信 API トランザクションはトランザクションログで表示できます。当日のトランザクションを表示するには、次のようなリンクを使用します。

    https://<instancename>.service-now.com/syslog_transaction_list.do?sysparm_query=sys_created_onONToday%40javascript%3Ags.beginningOfToday()%40javascript%3Ags.endOfToday()%5Etype%3Drest

    REST URI 形式と利用可能なパラメーター

    ServiceNow REST API は標準の REST API プロトコルに従います。また、下位互換性を確保するための「カスタム」URI とクエリパラメーターを提供し、結果の長いリストのページネーションなどの追加機能を提供します。以下のセクションで、これらのカスタムパラメーターの背後にある機能について説明します。これらはすべてオプションです。

    REST API バージョニング

    ServiceNow REST API URI には、/api/now/v1/table/{tableName} などのバージョン番号を含めることができます。バージョン番号は、URI がアクセスするエンドポイントのバージョンを識別します。URI にバージョン番号を指定することで、REST API の今後の更新が統合に悪影響を及ぼさないようにすることができます。

    URI にバージョン番号を指定しない URI (/api/now/table/{tableName} など) は、インスタンスバージョンの最新の REST エンドポイントを使用します。

    サポートされている HTTP 要求メソッド

    • GET
    • DELETE
    • HEAD
    • PATCH
    • POST
    • PUT

    これらのメソッドの詳細については、RFC-2616 ハイパーテキスト転送プロトコルのドキュメントを参照してください。

    注:
    • GET メソッドの代わりに HEAD メソッドを使用して、応答本文なしで応答を返すことができます。
    • POST、PUT、および PATCH 操作で複数のレコードを渡すことはできません。これを行うと、最初のレコードのみが処理され、残りは無視されます。
    • データベース ビューは読み取り専用であるため、POST、PUT、および PATCH を使用してデータベースビューにレコードを挿入または更新することはできません。

    データ形式ヘッダー

    REST API には、要求本文または応答本文を含む要求の適切なデータ形式を表す Accept および Content-Type 要求ヘッダーが必要です。POST、PUT、PATCH、および DELETE 操作では、両方のヘッダーを指定する必要があります。GET および HEAD 操作には Accept ヘッダーのみが必要です。必要なヘッダーを指定しないと、「400 要求が正しくありません」エラーが発生します。

    ほとんどの ServiceNow REST API では、これらの要求ヘッダーは次の値をサポートしています。

    • Accept：application/json、application/xml
    • Content-Type：application/json、application/xml

    各エンドポイントでサポートされている特定の値のリストについては、「REST API リファレンス」を参照してください。

    その他のヘッダー

    すべての要求には、認証に使用するユーザー資格情報を指定する認証ヘッダーを含めることができます。

    X-http-method-override ヘッダーを設定して、GET や POST などの HTTP メソッドを上書きすることもできます。

    特別なデータ処理

    以下では、REST API 内のデータ処理の一部について細かい点を説明します。

    • データフィールドをクリアする方法：選択フィールドを除き、パラメーターに空の値を渡してデータベースの値をクリアできます。たとえば、{"簡単な説明":""} を送信すると、指定されたレコードの short_description フィールドがクリアされます。
    • 通貨フィールドの処理方法：返される通貨値は、ユーザーのロケールに基づいて現地通貨に変換されます。データを挿入する場合、変換は実行されません。この動作は、[通貨] または [価格] タイプのフィールドに適用されます。

      たとえば、UK ロケールのユーザーが USD の通貨値でレコードをクエリすると、戻り値は GBP に変換されます。ただし、このユーザーが GBP の通貨フィールド値で新しいレコードを追加すると、値は USD に変換されずに GBP で保存されます。この GBP 値は、US ロケールのユーザーがクエリした場合は USD で表示されます。

    • UI データ表示と REST エンドポイントで渡される値：UI には、操作されたデータであるデータベースの表示値が表示されます。デフォルトでは、REST エンドポイントは実際の値を挿入して更新します。この値は表示値とは異なる場合があります。sysparm_input_display_value 要求パラメーターを true に設定することで、渡された値を REST エンドポイントで表示値として強制的に処理させることができます。

    カスタムクエリパラメーター

    ServiceNow REST API は、利用可能な API の多くで次のクエリパラメーターを使用し、API 全体で一貫した動作を提供します。これらのパラメーターを使用して、大きなレコードセットをページネーションし、結果をフィルタリングし、単一のクエリで返されるレコードの数を制限します。
    sysparm_limit 返されるレコードの最大数。このレコード数を超える要求の場合は、sysparm_offset パラメーターを使用してレコード取得をページネーションします。

    この制限は、ACL 評価の前に適用されます。アクセスできるレコードが含まれているのにレコードが何も返されない場合は、アクセスできるレコードが最初に返されるようにレコードの順序を並べ替えます。

    注:
    異常に大きい sysparm_limit 値はシステムパフォーマンスに影響する可能性があります。

    データタイプ：数値

    デフォルト：10000
    sysparm_fields 応答で返すカンマで区切られたフィールドのリストです。

    データタイプ：文字列
    sysparm_input_display_value 表示値または実際の値を使用してフィールド値を設定するかを示すフラグ。さまざまなフィールドタイプに応じて、エンドポイントは、渡された表示値を処理して適正値をデータベースに格納します。たとえば参照フィールドの表示名を送信すると、エンドポイントはその値の sys_id をデータベースに格納します。日付と時刻のフィールドの場合、このパラメーターが true であると、日付と時刻の値は現在のユーザーのタイムゾーンに合わせて調整されます。false の場合、日付と時刻の値は GMT タイムゾーンを使用して挿入されます。

    有効な値：

    • true：入力値を表示値として扱い、データベースに適切に格納されるように処理します。
    • false：入力値を実際の値として扱い、処理せずにデータベースに格納します。

    データタイプ：ブール

    デフォルト値：false。これは、データ検索 (GET メソッド) 中に返されるデータタイプ (実際の値) と一致します。

    注:
    暗号化されたフィールドの値を設定するには、このパラメーターを true に設定する必要があります。このパラメーターを true に設定しない場合、暗号化されたフィールドに送信される値は保存されません。さらに、要求側ユーザーは、適切な暗号化コンテキストがある状態で要求を送信する必要があります。暗号化されたフィールドは、適切な暗号化コンテキストがないユーザーには表示されません。フィールド暗号化の詳細については、「 Column Level Encryption」を参照してください。
    sysparm_offset レコード取得を開始するレコードのインデックス。この値を使用して、レコード取得をページネーションします。この機能により、レコード数に関係なく、管理しやすい小さなチャンクに分割してすべてのレコードを取得できます。

    たとえば、このエンドポイントを初めて呼び出すときに、sysparm_offset は「0」に設定されます。単に利用可能なすべてのレコードをページングするには、すべてのレコードの終わりに達するまで「sysparm_offset=sysparm_offset+sysparm_limit」を使用します。

    sysparm_offset パラメーターに負の数値を渡さないでください。

    データタイプ：数値

    デフォルト：0
    sysparm_query 結果セットをフィルタリングするために使用されるエンコードされたクエリ。UI フィルターを使用して、適切にエンコードクエリーを取得できます。
    構文：sysparm_query=<col_name><operator><value>。
    • <col_name>：フィルターを適用するテーブル列の名前。
    • <operator>：次の値をサポートします。
      • =：<value> と完全一致します。
      • !=：<value> と一致しません。
      • ^：複数のクエリステートメントの論理 AND。
      • ^OR：複数のクエリステートメントの論理 OR。
      • LIKE：指定された文字列が <col_name> に含まれています。データタイプが文字列である <col_name> フィールドに対してのみ機能します。
      • STARTSWITH：<col_name> は指定された文字列で始まります。データタイプが文字列である <col_name> フィールドに対してのみ機能します。
      • ENDSWITH：<col_name> は指定した文字列で終了します。データタイプが文字列である <col_name> フィールドに対してのみ機能します。
      <value>：照合する値。

    すべてのパラメーターで大文字と小文字が区別されます。クエリには、sysparm_query=<col_name><operator><value>[<operator><col_name><operator><value>] のように、複数のエントリを含めることができます。

    例：

    (sysparm_query=caller_id=javascript:gs.getUserID()^active=true)

    エンコードクエリーは、機能別の順番もサポートしています。特定のフィールドに基づいて回答を並べ替えるには、ORDERBY と ORDERBYDESC の句を sysparm_query で使用します。

    構文：
    • ORDERBY<col_name>
    • ORDERBYDESC<col_name>

    例：sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCcategory

    このクエリは、すべてのアクティブなレコードをフィルタリングし、結果を番号で昇順に並べ替えた後、カテゴリで降順に並べ替えます。

    フィールド名が無効というようにクエリの一部が無効であると、インスタンスは無効な部分を無視します。次に、クエリの有効部分のみを使用して行を返します。この動作は glide.invalid_query.returns_no_rows プロパティを使用してコントロールできます。無効なクエリに行を返さないようにするには、このプロパティを true に設定します。
    注:
    glide.invalid_query.returns_no_rows プロパティは、リスト、スクリプト (GlideRecord.query())、Web サービス API など、インスタンスのすべてのクエリの動作を管理します。

    データタイプ：文字列
    sysparm_view データをレンダリングする UI ビュー。応答で返されるフィールドを指定します。

    有効な値：

    • desktop
    • mobile
    • both

    sysparm_fields パラメーターが優先されます (指定した場合)。

    データタイプ：文字列

    REST API 要求でのドット連結

    ドット連結は、これらのパラメーターをサポートする REST API への要求で sysparm_query または sysparm_fields パラメーターを指定するときに使用できます。

    注:
    インポートセット API はドット連結をサポートしていません。

    sysparm_query でのドット連結

    sysparm_query パラメーターでドット連結を使用すると、関連レコード値を使用してクエリをフィルタリングできます。たとえば、インシデント [会社] に特定の [銘柄記号] 値のあるすべてのインシデントレコードを取得できます。

    https://<instance>.service-now.com/api/now/table/incident?sysparm_query=company.stock_symbol=NYX

    sysparm_fields でのドット連結

    sysparm_fields パラメーターでドット連結を使用すると、複数のテーブルのフィールド値を表示できます。たとえば、特定のロールを持つ各ユーザーの名前、Sys_id、および部門と、ロールの名前を取得できます。

    要求は、ユーザーとロール間の多対多の関係を定義するユーザーロール [sys_user_has_role] テーブルで実行されます。応答には、ユーザー [sys_user] テーブルとロール [sys_user_role] テーブルのフィールド値が含まれます。

    https://<instance>.service-now.com/api/now/table/sys_user_has_role?sysparm_fields=role%2Crole.name%2Cuser%2Cuser.name%2Cuser.sys_id%2Cuser.department&sysparm_query=role%3D3d43716d0f6002003a2d47bce1050e0d%5EORrole%3Dac73b52d0f6002003a2d47bce1050eec&sysparm_display_value=true

    {
"result": [
  {
   "user.name": "Fred Johnson",
   "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
   "role.name": "support",
   "user.department": {
      "display_value": "Accounting",
      "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
    },
   "role": {
      "display_value": "support",
      "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/3d43716d0f6002003a2d47bce1050e0d"
    },
   "user": {
      "display_value": "Fred Johnson",
      "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
    }
  },
  {
   "user.name": "Fred Johnson",
   "user.sys_id": "f5a3716d0f6002003a2d47bce1050ed4",
   "role.name": "asset_mgmt",
      "user.department": {
      "display_value": "Accounting",
      "link": "https://<instance>.service-now.com/api/now/table/cmn_department/5b3b13530f58c2003a2d47bce1050e96"
     },
    "role": {
       "display_value": "asset_mgmt",
       "link": "https://<instance>.service-now.com/api/now/table/sys_user_role/ac73b52d0f6002003a2d47bce1050eec"
      },
    "user": {
       "display_value": "Fred Johnson",
       "link": "https://<instance>.service-now.com/api/now/table/sys_user/f5a3716d0f6002003a2d47bce1050ed4"
       }
    }
  ]
}

    REST API HTTP 応答コード

    REST エンドポイントに対する呼び出しは、HTTP 応答コードを返します。これらの応答コードを使用して、REST API が適切に実行されたことを確認できます。そうでない場合、エンドポイントはエラー応答コードを返します。エラー応答の情報を使用して、呼び出しの形式の問題をトラブルシューティングします。エンドポイントが返す可能性がある標準的な応答コードのリストについては、「REST API HTTP 応答コード」を参照してください。特定の ServiceNow REST API で返される応答コードのリストについては、「REST API リファレンス」を参照してください。

    REST API セキュリティ

    デフォルトでは、ServiceNow REST API は基本認証または OAuth を使用して、REST API/エンドポイントへのユーザーアクセスを許可します。マルチファクター認証を使用して REST API にアクセスするようにインスタンスを設定することもできます。

    REST エンドポイント呼び出しで指定するユーザー ID は、インタラクティブユーザーと同じ方法でアクセス制御されます。各要求には、ユーザー名やパスワードなどの適切な認証情報が必要です。各エンドポイント要求に、エンドポイントにアクセスするための十分な資格情報を持つ認証ヘッダーが含まれていることを確認します。

    ServiceNow REST API は、既存のセッションへのバインディングをアクティブ化する cookie もサポートしています。

    証明書を使用して API を呼び出す方法と相互認証の詳細については、「証明書ベースの認証」を参照してください。

    IP、ロール、グループなどのフィルター基準を持つ REST API アクセスポリシーを使用し、API のスコープを制限するには、REST API Auth Scope を使用できます。REST API アクセスポリシーの詳細については、「REST API アクセスポリシー」を参照してください。

    グローバル REST API レベルでは信頼できるネットワークの外部から REST API アクセスポリシーを使用して、あるいは基本的な REST 認証レベルで、受信要求をブロックする単一のポリシーを作成できます。

    REST API ロール

    ユーザー認証に加えて、各 REST エンドポイントには、エンドポイントへのアクセスに必要なロールに関して異なる要件がある場合があります。admin ロールが必要なものもあれば、API 固有のロールが必要なものもあります。ロール要件は、REST API/エンドポイントに関連付けられたアクセス制御リスト (ACL) で指定されます。各 REST API/エンドポイントの有効なロールの詳細については、「REST API リファレンス」を参照するか、 [System Security] > [アクセス制御 (ACL)] から、インスタンス内の API/エンドポイントに関連する ACL を探してください。

    REST API ACL

    REST API ACL は、必要なロールや、ユーザーが ServiceNow REST API またはエンドポイントにアクセスするために満たす必要がある条件などの基準を定義します。単一の ACL は、テーブル API や添付ファイル API ACL などの REST API 全体に対して、または メトリックベース PUT メソッドにのみ適用される clotho_rest_put ACL などの個々のエンドポイントに対して定義できます。

    次の ServiceNow REST API ACL はベースシステムで使用できますが、デフォルトでは非アクティブ化されています。その他すべての ServiceNow REST API ACL はデフォルトでアクティブです。

    • テーブル API
    • 集計 API
    • インポートセット API
    • 添付ファイル API

    ACL の詳細については、「アクセス制御リストルール」を参照してください。

    重要:
    REST API ACL の名前を変更することはできません。

    REST API テーブルアクセス

    デフォルトでは、ベースシステムテーブル、グローバルテーブル、およびスコープ対象のテーブルを含むすべてのテーブルに Web サービスを介してアクセスできます。Web サービスを介してテーブルにアクセスするには、基本認証や ACL など、Web サービスのセキュリティ要件を満たす必要があります。ACL が原因で呼び出し元エンティティが権限を持たないフィールドは、REST クエリ応答では返されません。

    認証や認可なしでテーブルにアクセスできるようにするには、そのテーブル名をアクティブステータスで公開ページ [sys_public] テーブルに追加します。REST インターフェイスでも、定義された ACL が関連テーブルに適用されます。ACL の適用が望ましい動作でない場合は、テーブルの ACL を非アクティブ化する必要があります。ただし、API を公開にすると、インスタンス内のデータを更新するためのパブリックアクセスが許可されるため、API を公開することはお勧めしません。

    テーブルアプリケーションのアクセス設定の [Web サービスからのアクセス許可] チェックボックスを使用して、テーブルへの直接の Web サービスアクセスを制御することもできます。Web サービスとテーブルのインタラクションをアクティブ化するには、このチェックボックスをオンにする必要があります。

    注:
    [読込可能] や [作成可能] などの CRUD 操作を制御するアプリケーションアクセスフィールドは、Web サービス要求には適用されません。

    受信 REST のマルチファクター認証

    ユーザーアカウントに対してマルチファクター認証が有効になっている場合は、そのユーザーとして REST 要求を行うときに、基本認証資格情報を使用して MFA トークンを送信する必要があります。

    REST 要求で MFA トークンを送信するには、基本認証の username:password 文字列のユーザーのパスワードの末尾にトークンを追加します (joe.employee:password62161147 など)。base64 エンコーディングを使用して MFA トークンを含む完全な文字列をエンコードし、エンコードされた文字列を認証ヘッダーで送信します。

    マルチファクター認証の REST 応答

    MFA 認証要求への応答は、指定された認証情報と MFA トークンの有効性によって異なります。

    表 : 1. 応答
    結果 説明
    基本認証資格情報と MFA トークンが有効です ユーザーが認証され、セッションが作成されます。要求は正常に処理されます。
    基本認証資格情報は有効ですが、MFA トークンが無効であるか、見つかりません 応答はエラー 401 を返します。応答には、値が invalid の X-MFA_TOKEN ヘッダーが含まれています。
    基本認証資格情報が無効です 応答はエラー 401 を返します。X-MFA_TOKEN ヘッダーは応答に含まれません。

    REST API CORS サポート

    REST API は、クロスオリジンリソース共有 (CORS) セキュリティをサポートしています。CORS サポートにより、各 REST API にアクセスできるドメインを定義できます。ドメインの CORS ルールを定義することで、そのドメインからのクロスオリジン要求を許可できます。CORS ルールのないドメインからクロスオリジン要求を作成することはできません。

    注:
    CORS サポートは、スクリプト化された REST Web サービスを含む REST API にのみ適用されます。SOAP API などの他の Web サービス API は CORS をサポートしていません。

    他のドメインから特定の API/エンドポイント、HTTP メソッド、およびヘッダーのみへのアクセスを許可するように CORS を設定できます。たとえば、特定のドメインからのテーブル API への要求を制限して、GET 操作のみを許可することができます。

    インスタンスで定義されている CORS ルールを表示するには、 System Web Services > CORS ルール.

    インスタンスの CORS サポートを非アクティブ化するには、glide.rest.cors.enabled プロパティを [false] に設定します。false の場合、着信 REST 要求で CORS 評価は実行されません。このプロパティはデフォルトで true に設定されています。

    REST API エクスプローラー

    REST API エクスプローラーは、インスタンスからの情報を使用して、REST 要求の構築および送信に使用できるエンドポイント、メソッド、および変数のリストを提供する ServiceNow ツールです。

    要求を構築すると、REST API エクスプローラーは、要求を開始するために使用できる複数のプログラミング言語のコードサンプルと、詳細な要求および応答情報を提供します。

    REST API Explorer にアクセスするには、インスタンスで System Web Services > REST API エクスプローラー. REST API Explorer にアクセスするには、rest_api_explorer ロールが必要です。詳細については、「REST API エクスプローラーの使用」を参照してください。

    警告:
    REST API エクスプローラーは、現在のインスタンスのデータを操作します。本番インスタンスでデータを作成、編集、または削除する要求を処理する場合は注意してください。

    Automated Test Framework のサポート

    Automated Test Framework (ATF) は、受信 REST テストステップをサポートしています。作成したカスタム受信 REST API の自動テストを作成できます。カスタム REST API のテストを作成すると、アップグレードのテストが簡素化され、REST API の変更に下位互換性があることを確認することが可能になります。

    REST クライアントアプリケーションのサンプル

    REST Web サービスを使用した統合のデモには、いくつかの REST クライアントアプリケーションとソースコードのサンプルが用意されています。REST クライアントアプリケーションのサンプルでは、NodeJS や iOS アプリケーションなどの外部アプリケーションで ServiceNow REST API を使用する方法を示しています。

    重要:
    これらのアプリケーションは REST 機能のデモとしてのみ提供されており、正式にはサポートされていません。

    サンプルはオープンソースであり、コミュニティで利用できます。これらのサンプルアプリケーションを使用して、REST 機能に慣れることができます。また、独自の REST クライアントアプリケーションを作成するための出発点として使用することもできます。

    rest_api_explorerロールを持つユーザーは、次の場所に移動して、利用可能なクライアントアプリケーションのリストにアクセスできます。 System Web Services > REST > サンプルクライアントアプリ.

    アプリケーションのリストを表示しているときに、アプリケーションをクリックすると、GitHub でホストされているソースコードと追加のドキュメントが表示されます。

    開発者トレーニング

    ServiceNow® 開発者サイトでは、受信 REST 統合と送信 REST 統合のトレーニングを受けることができます。

    追加情報

    REST API セクションの残りの部分には、ServiceNow REST API を使用した特定の実装について説明する「ハウツー」トピックが含まれ、ServiceNow REST API で使用されるさまざまなデータ要素を説明する参照情報が提供されます。