REST API

  • リリースバージョン: Australia
  • 更新日 2026年03月12日
  • 所要時間：23分

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

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

    使用可能な REST API のリストについては、「 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 に対する今後の更新が統合に悪影響を及ぼさないようにすることができます。

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

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

    • GET
    • 消去
    • 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 Bad Request 」エラーが発生します。

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

    • 承認: application/json、 application/xml
    • コンテンツタイプ: application/json、 application/xml

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

    その他のヘッダー

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

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

    特別なデータ処理

    以下では、REST API 内のデータ処理の微妙な違いについて説明します。

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

      たとえば、英国ロケールのユーザーが米ドルの通貨値を持つレコードをクエリすると、戻り値は GBP に変換されます。ただし、このユーザーが通貨フィールドの値が GBP の新しいレコードを追加した場合、値は USD に変換されることなく GBP で保存されます。この GBP 値は、米国ロケールのユーザーによってクエリーされた場合、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 に設定されていない場合、暗号化フィールドに送信された値は保存されません。さらに、要求元ユーザーは、要求を送信する前に適切な暗号化コンテキストを持っている必要があります。適切な暗号化コンテキストのないユーザーに対しては、暗号化フィールドが非表示になります。フィールド暗号化の詳細については、「 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>:次の値をサポートします。
      • =:<col_name>は<値>と完全に一致します。
      • !=:<col_name> が <value> と一致しません。
      • LIKE:<col_name>には指定された文字列 <value> が含まれています。データタイプが文字列である<col_name>フィールドでのみ機能します。
      • STARTSWITH:<col_name>は、指定された文字列 <value> で始まります。データタイプが文字列である<col_name>フィールドでのみ機能します。
      • ENDSWITH:<col_name>は指定された文字列 <value> で終わります。データタイプが文字列である<col_name>フィールドでのみ機能します。
      • ^:クエリ条件を追加するための AND 演算子。結果セットに含まれるレコードは両方の条件に一致します。
      • ^OR:クエリ条件を追加するための OR 演算子。結果セットに含まれるレコードは、少なくとも 1 つの条件に一致します。
    • <value>:フィルターを適用する値。
    演算子の詳細については、「Operators available for filters and queries」を参照してください。

    クエリには複数の条件を含めることができます。たとえば、次のクエリは、発信者が現在のユーザーであり、レコードがアクティブなレコードを返します。

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

    エンコードクエリでは、昇順および降順による並べ替えの機能もサポートされています。特定のフィールドに基づいて応答をソートするには、sysparm_queryで ORDERBY 句と ORDERBYDESC 句を使用します。

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

    たとえば、次のクエリでは、すべてのアクティブなレコードを取得し、結果を番号の昇順に並べ替え、次にカテゴリ別に降順に並べ替えます。

    sysparm_query=active=true^ORDERBYnumber^ORDERBYDESCカテゴリ

    デフォルトでは、無効なフィールド名など、クエリの一部が無効な場合、インスタンスは無効な部分を無視します。次に、クエリの有効な部分のみを使用して行を返します。プロパティ glide.invalid_query.returns_no_rows を true に設定すると、代わりに無効なクエリに対して行を返さないようにします。
    注:
    glide.invalid_query.returns_no_rows プロパティは、リスト、スクリプト (GlideRecord.query())、Web サービス API など、インスタンス全体のすべてのクエリの動作を制御します。

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

    有効な値：

    • デスクトップ
    • 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 アクセスポリシーと、この REST API Auth Scope使用できる API のスコープの制限。REST API アクセスポリシーの詳細については、「 REST API アクセスポリシー」を参照してください。

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

    REST API ロール

    ユーザー認証に加えて、各 REST エンドポイントには、エンドポイントへのアクセスに必要なロールに関するさまざまな要件があります。admin ロールが必要なものもあれば、API 固有のロールが必要なものもあります。ロール要件は、REST API/エンドポイントに関連付けられたアクセス制御リスト (ACL) で指定されます。各 REST API/エンドポイントの有効なロールの詳細については、 REST API リファレンス を参照するか、 システムセキュリティ > アクセス制御 (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 を公開すると、インスタンス内のデータを更新するためのパブリックアクセスが許可されるため、お勧めしません。

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

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

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

    Yokohama リリース以降、ベーシック認証を使用する REST API 認証では、デフォルトでマルチファクター認証 (MFA) は必要ありません。詳細については、この KB 記事を参照してください。

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

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

    表 : 1. 応答
    結果 説明
    基本認証情報と MFA トークンは有効です ユーザーが認証され、セッションが作成されます。要求は正常に処理されます。
    基本認証情報は有効ですが、MFA トークンが無効であるか、見つかりません 応答はエラー 401 を返します。応答に、値が 無効な 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 ルールを表示するには、次に移動します システム Web サービス > CORS ルール.

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

    REST API エクスプローラー

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

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

    REST API エクスプローラーにアクセスするには、インスタンスで次の場所に移動します システム Web サービス > REST API エクスプローラー. REST API エクスプローラーにアクセスするには、rest_api_explorer ロールが必要です。詳細については、「 REST API エクスプローラーの使用」を参照してください。

    警告:
    REST API エクスプローラーは、現在のインスタンスのデータとやり取りします。本番インスタンスでデータを作成、編集、または削除する要求を処理する場合は注意が必要です。

    自動テストフレームワーク (ATF) のサポート

    自動テストフレームワーク (ATF) は、受信 REST テストステップをサポートしています。作成したカスタム受信 REST API の自動テストを作成できます。カスタム REST API のテストを作成すると、アップグレードテストが簡素化され、REST API への変更に下位互換性があることを検証できます。

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

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

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

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

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

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

    開発者トレーニング

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

    追加情報

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