バッチ API

Yokohama API リファレンス

Release

yokohama

ft:locale

ja-JP

ft:publication_title

Yokohama API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

バッチ API

リリースバージョン: Yokohama

更新日 2025年01月30日

所要時間：16分

バッチ API は、複数の REST API 呼び出しを含む単一の要求を送信するエンドポイントを提供し、応答ペイロードのストリームを返します。

この REST API により、インテグレーターは次のことが可能になります。

API 要求をまとめてバッチ処理することで送信に必要な時間を短縮し、認証、セッションセットアップ、および往復トラフィックを 1 つのステップに絞り込むことでオーバーヘッドを削減します。
クライアント側の統合のために、より効率的なコードを作成します。
バッチアイテム形式を混在させ、単一のバッチ要求に含めます。たとえば、1 つのバッチに、あるエンドポイントに送信する XML 形式の Bases64 エンコード要求と、別のエンドポイントに送信する JSON 形式の Base64 エンコード要求を含めることができます。
戻りとして応答ペイロードのストリームを受け取ります。
バッチ内の各 API 呼び出しに既存の ACL を適用します。

インスタンスで利用可能な任意の API をバッチ API 呼び出しに含めることができます。パフォーマンス上の理由から、長時間実行される要求や大量のデータを取得する要求を含めないでください。

重要:

バッチ API は、個々の API 要求と同じパフォーマンス特性を持ちますが、複数のクライアント/サーバー要求のオーバーヘッドを回避します。Batch API は並列トランザクション処理を対象としていないため、実行時間の長い API 要求により、API 要求が最大トランザクション時間を超えてエラーを返す可能性があります。

サイズと処理制限

ペイロードは、次のサイズ制限に従います。

要求内の各アイテム: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 ヘッダー値は、システムプロパティの値を超えることはできません。

注:

要求の実行時間が 30 秒を超えた場合、 REST Batch API request timeout トランザクションクォータルールによってトランザクションが終了します。このトランザクションクォータルールの値を増やすと、パフォーマンスの問題が発生する可能性があります。

バッチ要求がサイズまたは処理制限に達すると、システムはトランザクションをキャンセルし、未処理の要求を応答の未処理の JSON アレイに返します。

バッチ:POST /now/batch

1 回の呼び出しで複数の REST API 要求を送信します。

URL 形式

バージョニングされた URL: /api/now/{api_version}/batch

サポートされている要求パラメーター

表 : 1. パスパラメーター
名前	説明
api_version	アクセスするエンドポイントのバージョン。たとえば、 `v1` や `v2` などです。データタイプ：文字列

表 : 2. クエリパラメーター
名前	説明
なし

表 : 3. 要求本文パラメーター (JSON)
名前	説明
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:応答ヘッダーは応答に含まれます。データタイプ：ブールデフォルト値：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	必須。要求を送信するエンドポイントの相対パス。クエリパラメーターが含まれます。データタイプ：文字列

ヘッダー

次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 4. 要求ヘッダー
ヘッダー	説明
受容	応答本文のデータ形式。application/jsonのみをサポートしています。
Content-Type	要求本文のデータ形式。application/jsonのみをサポートしています。
X-BATCHREQUEST-MAX-OUTPUT-SIZE	バッチ応答内の各アイテムのサイズ制限。このヘッダーを追加して、glide.rest.batch.max.outputSize システムプロパティで設定されているデフォルトよりも小さいサイズ制限を指定します。システムプロパティの値よりも大きい値を設定することはできません。デフォルト:10 MB。

表 : 5. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 6. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	権限がありません。ユーザー認証情報が正しくないか、渡されていません。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON)


名前	説明
batch_request_id	要求の batch_request_id パラメーターに一致するバッチの ID。データタイプ：文字列
serviced_requests	バッチ要求からの応答オブジェクトのリスト。データタイプ：アレイ `"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": []
}