--- sourceDocument: Xanadu API リファレンス sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/ja-JP/xanadu/api-reference Release : - xanadu ft:locale : - ja-JP ft:publication_title : - Xanadu API リファレンス ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # バッチ API # バッチ API {#ariaid-title1} * リリースバージョン: Xanadu * * 更新日 2024年08月01日 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 所要時間：16分 バッチ API は、複数の REST API 呼び出しを含む単一の要求を送信し、応答ペイロードのストリームを返すためのエンドポイントを提供します。 この REST API を使用すると、インテグレーターは次のことができます。 * API 要求をまとめてバッチ処理することで送信に必要な時間を短縮し、認証、セッションのセットアップ、および往復トラフィックを 1 つのステップに絞り込むことでオーバーヘッドを削減します。 * クライアント側の統合のためにより効率的なコードを作成します。 * バッチアイテムの形式を混在させて、単一のバッチ要求に含めます。たとえば、1 つのバッチに、1 つのエンドポイントに送信する XML 形式の Bases64 エンコード要求と、別のエンドポイントに送信する JSON 形式の Base64 エンコード要求を含めることができます。 * 返される応答ペイロードのストリームを受信します。 * バッチ内の各 API 呼び出しに既存の ACL を適用します。 {#batch-api__ul_i4h_rzk_qlb} バッチ API 呼び出しには、インスタンスで利用可能な任意の API を含めることができます。パフォーマンス上の理由から、実行時間の長い要求や大量のデータを取得する要求は含めないでください。 重要: Batch API のパフォーマンス特性は個々の API 要求と同じですが、複数のクライアント/サーバー要求のオーバーヘッドを回避します。Batch API は並列トランザクション処理を意図しておらず、API 要求の実行時間が長いと、API 要求が最大トランザクション時間を超え、エラーが返される可能性があります。 ## サイズと処理の制限 {#batch-api__section_pxp_l1l_qlb} ペイロードは次のサイズ制限に従います。 * 要求の各アイテム：5 MB。glide.rest.batch.max.inputSize システムプロパティを更新することで、このデフォルトを変更できます。最大値：10 MB。 * 応答の各アイテム：10 MB。glide.rest.batch.max.outputSize システムプロパティを更新するか、X-BATCHREQUEST-MAX-OUTPUT-SIZE ヘッダーを要求に追加することで、このデフォルトを変更できます。X-BATCHREQUEST-MAX-OUTPUT-SIZE ヘッダー値は、システムプロパティの値を超えることはできません。 {#batch-api__ul_t2j_k4l_qlb} 注: 要求が 30 秒より長く実行されると、REST Batch API request timeout トランザクションクォータのルールによってトランザクションが終了します。このトランザクションクォータのルールの値を増やすと、パフォーマンスの問題が発生する可能性があります。 バッチ要求がサイズまたは処理の制限に達すると、システムはトランザクションをキャンセルし、応答のサービスが実行されていない JSON アレイで未処理の要求を返します。 ## バッチ - POST /now/batch {#ariaid-title2} 1 回の呼び出しで複数の REST API 要求を送信します。 バッチ API 呼び出しには、インスタンスで利用可能な任意の API を含めることができます。パフォーマンス上の理由から、実行時間の長い要求や大量のデータを取得する要求は含めないでください。 ### URL 形式 バージョニングされた URL：/api/now/{api_version}/batch ### サポートされている要求パラメーター {#batch-POST__entry__2}{#batch-POST__version-RESTAPI} | 名前 | 説明 | |-|-| | api_version | オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。 データタイプ：文字列 | [表 : 1. パスパラメーター] {#batch-POST__entry__6} | 名前 | 説明 | |-|-| | なし | | [表 : 2. クエリパラメーター] {#batch-POST__entry__10} | 名前 | 説明 | |-|-| | batch_request_id | 要求のバッチを識別する ID。 データタイプ：文字列 | | rest_requests | 必須です。バッチ要求に含める要求オブジェクトのリスト。 データタイプ：アレイ "rest_requests":[ { "body": "String", "exclude_response_headers": Boolean, "headers":[Array], "id": "String", "method": "String", "url": "String" } ] | | rest_requests.body | Base64 でエンコードされた要求の本文。本文を必要とするメソッド (POST など) にのみ適用されます。エンコード前の本文は任意の形式にすることができます。たとえば、XML や JSON などです。 データタイプ：文字列 | | rest_requests.exclude_response_headers | 応答から応答ヘッダーを除外するかどうかを示すフラグ。 有効な値： * true：応答に応答ヘッダーは含まれません。 * false：応答に応答ヘッダーが含まれます。 {#batch-POST__ul_tch_pkm_qlb} データタイプ：ブーリアン デフォルト値：false | | rest_requests.headers | エンドポイントに送信する要求ヘッダーオブジェクトのリスト。 データタイプ：アレイ "headers":[ { "name":"String", "value":"String" } ] | | rest_requests.headers.name | ヘッダーの名前。 データタイプ：文字列 | | rest_requests.headers.value | ヘッダーの値。 データタイプ：文字列 | | rest_requests.id | 必須です。バッチの各アイテムの ID。 データタイプ：文字列 | | rest_requests.method | 必須です。関連付けられたエンドポイントのために呼び出すメソッド。 データタイプ：文字列 | | rest_requests.url | 必須です。要求の送信先のエンドポイントの相対パス。クエリパラメーターが含まれます。 データタイプ：文字列 | [表 : 3. 要求本文パラメーター (JSON)] ### ヘッダー 次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 [サポートされている REST API ヘッダー](https://servicenow-prod.fluidtopics.net/ldF_qFEQnejbeXLBxcUhWg "REST (REpresentational State Transfer) は、Web 上のコンピューターシステム間の標準を提供し、相互の通信を容易にするシンプルなステートレスアーキテクチャです。")」を参照してください。 {#batch-POST__entry__32} | ヘッダー | 説明 | |-|-| | Accept | 応答本文のデータフォーマット。application/json のみをサポートします。 | | Content-Type | 要求本文のデータ形式。application/json のみをサポートします。 | | X-BATCHREQUEST-MAX-OUTPUT-SIZE | バッチ応答内の各アイテムのサイズ制限。glide.rest.batch.max.outputSize システムプロパティで設定されたデフォルトよりも低いサイズ制限を指定するには、このヘッダーを追加します。システムプロパティの値よりも大きい値を設定することはできません。 デフォルト：10 MB | [表 : 4. 要求ヘッダー] {#batch-POST__entry__40} | ヘッダー | 説明 | |-|-| | なし | | [表 : 5. 応答ヘッダー] ### ステータスコード この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 [REST API HTTP 応答コード](https://servicenow-prod.fluidtopics.net/ldF_qFEQnejbeXLBxcUhWg "REST (REpresentational State Transfer) は、Web 上のコンピューターシステム間の標準を提供し、相互の通信を容易にするシンプルなステートレスアーキテクチャです。")」を参照してください。 {#batch-POST__entry__44}{#batch-POST__entry-200-status-code}{#batch-POST__entry-401-status-code}{#batch-POST__entry-500-status-code} | ステータスコード | 説明 | |-|-| | 200 | 成功。要求が正常に処理されました。 | | 401 | 権限がありません。ユーザー資格情報が間違っているか、渡されていません。 | | 500 | 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。 | [表 : 6. ステータスコード] ### 応答本文のパラメーター (JSON) {#batch-POST__entry__52} | 名前 | 説明 | |-|-| | batch_request_id | 要求の batch_request_id パラメーターと一致するバッチの ID。 データタイプ：文字列 | | serviced_request | バッチ要求からの応答オブジェクトのリスト。 データタイプ：アレイ "serviced_requests":[ { "body": "String", "error_message": "String", "execution_time": Number, "headers": [Array], "id": "String", "redirect_url: "String", "status_code": Number, "status_text": "String" } ] | | serviced_requests.body | Base64 でエンコードされた要求の本文。本文の値を取得するには、このパラメーターの内容を Base64 でデコードします。 データタイプ：文字列 | | serviced_requests.error_message | 存在する場合、エラーメッセージ。 データタイプ：文字列 | | serviced_requests.execution_time | バッチアイテム要求の実行にかかった時間。 データタイプ：数値 単位：ミリ秒 | | serviced_requests.headers | バッチアイテムのヘッダー。 データタイプ：アレイ "headers":[ { "name":"String", "value":"String" } ] | | serviced_requests.headers.name | ヘッダーの名前。 データタイプ：文字列 | | serviced_requests.headers.value | ヘッダーの値。 データタイプ：文字列 | | serviced_requests.id | 要求の rest_requests.id パラメーターと一致するバッチアイテムの ID。 データタイプ：文字列 | | serviced_requests.redirect_url | リダイレクト URL (存在する場合)。 データタイプ：文字列 | | serviced_requests.status_code | バッチアイテムのステータスコード。 データタイプ：数値 | | serviced_requests.status_text | バッチアイテムのステータスコードのテキスト。 データタイプ：文字列 | | unserviced_requests | バッチ要求がサイズまたは処理の制限に達したために処理されなかった要求の ID。 データタイプ：アレイ | [ ] ### cURL 要求 このバッチ要求は、インスタンスに 2 つの GET 要求を、またインシデントテーブルに 1 つの POST 要求を送信します。POST 要求の本文は Base64 でエンコードされます。 curl "https://instance.servicenow.com/api/now/v1/batch" \ --request POST \ --header "Accept:application/json" \ --header "Content-Type:application/json" \ --user "username":"password"\ --data "{ \"batch_request_id\":\"1\", \"rest_requests\":[ { \"id\":\"11\", \"headers\":[ { \"name\":\"Content-Type\", \"value\":\"application/xml\" }, { \"name\":\"Accept\", \"value\":\"application/xml\" } ], \"url\":\"/api/global/user_role_inheritance\", \"method\":\"GET\" }, { \"id\":\"12\", \"exclude_response_headers\":true, \"headers\":[ { \"name\":\"Content-Type\", \"value\":\"application/json\" }, { \"name\":\"Accept\", \"value\":\"application/json\" } ], \"url\":\"/api/now/table/incident?sysparm_limit=1\", \"method\":\"GET\" }, { \"id\":\"13\", \"exclude_response_headers\":true, \"headers\":[ { \"name\":\"Content-Type\", \"value\":\"application/json\" }, { \"name\":\"Accept\", \"value\":\"application/json\" } ], \"url\": \"/api/now/table/incident\", \"method\":\"POST\", \"body\": \"eyd1cmdlbmN5JzonMScsICdzaG9ydF9kZXNjcmlwdGlvbic6J015IGNvbXB1dGVyIG Jyb2tlJywgJ2NvbW1lbnRzJzonRWxldmF0aW5nIHVyZ2VuY3ksIHRoaXMgaXMgYSBibG9ja2luZyBpc3N1ZSd9\" } ] }" \ { "batch_request_id": "1", "serviced_requests": [ { "id": "11", "body": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cmVzcG9uc2U+PHJlc3VsdD48dX Nlcl9uYW1lLz48L3Jlc3VsdD48L3Jlc3BvbnNlPg==", "status_code": 200, "status_text": "OK", "headers": [ { "name": "Pragma", "value": "no-store,no-cache" }, { "name": "Expires", "value": "0" }, { "name": "Content-Length", "value": "88" }, { "name": "Content-Type", "value": "application/xml; charset=UTF-8" }, { "name": "Cache-control", "value": "no-cache,no-store,must-revalidate,max-age=-1" } ], "execution_time": 5 }, { "id": "12", "body": "eyJyZXN1bHQiOlt7InBhcmVudCI6IiIsIm1hZGVfc2xhIjoidHJ1ZSIsImNhdXNlZF9 ieSI6IiIsIndhdGNoX2xpc3QiOiIiLCJ1cG9uX3JlamVjdCI6ImNhbmNlbCIsInN5c191cGRhdGV kX29uIjoiMjAxNi0xMi0xNCAwMjo0Njo0NCIsImNoaWxkX2luY2lkZW50cyI6IjAiLCJob2xkX3J lYXNvbiI6IiIsInRhc2tfZWZmZWN0aXZlX251bWJlciI6IklOQzAwMDAwNjAiLCJhcHByb3ZhbF9 oaXN0b3J5IjoiIiwibnVtYmVyIjoiSU5DMDAwMDA2MCIsInJlc29sdmVkX2J5Ijp7ImxpbmsiOiJ odHRwczovL2s4czAwNjc5Nzgtbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGk vbm93L3RhYmxlL3N5c191c2VyLzUxMzcxNTNjYzYxMTIyN2MwMDBiYmQxYmQ4Y2QyMDA3IiwidmF sdWUiOiI1MTM3MTUzY2M2MTEyMjdjMDAwYmJkMWJkOGNkMjAwNyJ9LCJzeXNfdXBkYXRlZF9ieSI 6ImVtcGxveWVlIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzgtbm9kZTE udGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2VyLzY4MWN jYWY5YzBhODAxNjQwMGI5OGEwNjgxOGQ1N2M3IiwidmFsdWUiOiI2ODFjY2FmOWMwYTgwMTY0MDB iOThhMDY4MThkNTdjNyJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiIyMDE2LTE yLTEyIDE1OjE5OjU3Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY3OTc4LW5 vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXNfdXNlcl9 ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjciLCJyb3V0ZV9yZWFzb24 iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImVtcGxveWVlIiwia25vd2xlZGdlIjoiZmFsc2UiLCJvcmR lciI6IiIsImNhbGVuZGFyX3N0YyI6IjEwMjE5NyIsImNsb3NlZF9hdCI6IjIwMTYtMTItMTQgMDI", "status_code": 200, "status_text": "OK", "headers": [], "execution_time": 8 }, { "id": "13", "body": "eyJyZXN1bHQiOnsicGFyZW50IjoiIiwibWFkZV9zbGEiOiJ0cnVlIiwiY2F1c2VkX2J 5IjoiIiwid2F0Y2hfbGlzdCI6IiIsInVwb25fcmVqZWN0IjoiY2FuY2VsIiwic3lzX3VwZGF0ZWR fb24iOiIyMDIwLTA1LTEyIDAxOjQ0OjM1IiwiY2hpbGRfaW5jaWRlbnRzIjoiMCIsImhvbGRfcmV hc29uIjoiIiwidGFza19lZmZlY3RpdmVfbnVtYmVyIjoiSU5DMDAxMDAwNCIsImFwcHJvdmFsX2h pc3RvcnkiOiIiLCJudW1iZXIiOiJJTkMwMDEwMDA0IiwicmVzb2x2ZWRfYnkiOiIiLCJzeXNfdXB kYXRlZF9ieSI6ImFkbWluIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzg tbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2V yLzY4MTZmNzljYzBhODAxNjQwMWM1YTMzYmUwNGJlNDQxIiwidmFsdWUiOiI2ODE2Zjc5Y2MwYTg wMTY0MDFjNWEzM2JlMDRiZTQ0MSJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiI yMDIwLTA1LTEyIDAxOjQ0OjM1Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY 3OTc4LW5vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXN fdXNlcl9ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjEiLCJyb3V0ZV9 yZWFzb24iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImFkbWluIiwia25vd2xlZGdlIjoiZmFsc2UiLCJ", "status_code": 201, "status_text": "Created", "headers": [], "execution_time": 2638 } ], "unserviced_requests": [] }