バッチ API

Xanadu API リファレンス

Release

xanadu

ft:locale

ja-JP

ft:publication_title

Xanadu API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

バッチ API

リリースバージョン: Xanadu

更新日 2024年08月01日

所要時間：16分

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

この REST API を使用すると、インテグレーターは次のことができます。

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

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

重要:

Batch 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. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。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_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": []
}