Batch-API
Die Batch API stellt Endpunkte zum Senden einer einzelnen Anforderung mit mehreren REST API-Aufrufen bereit und gibt einen Stream von Antwort-Payloads zurück.
Mit dieser REST API können Integratoren:
- Verringern Sie die zum Senden von API-Anforderungen erforderliche Zeit, indem Sie sie in einem Batch zusammenfassen, und reduzieren Sie den Aufwand, indem Sie Authentifizierung, Sitzungseinrichtung und Roundtrip-Datenverkehr auf einen einzigen Schritt beschränken.
- Erstellen Sie effizienteren Code für clientseitige Integrationen.
- Kombinieren Sie Batch-Elementformate, und fügen Sie sie in eine einzelne Batch-Anforderung ein. Beispielsweise kann ein Batch eine Bases64-codierte Anforderung im XML-Format enthalten, die an einen Endpunkt gesendet wird, und eine Base64-codierte Anforderung im JSON-Format, die an einen anderen Endpunkt gesendet wird.
- Erhalten Sie im Gegenzug einen Stream von Antwortnutzlasten.
- Wenden Sie vorhandene ACLs auf jeden API-Aufruf im Batch an.
Sie können jede in der Instanz verfügbare API in einen Batch- API-Aufruf einbeziehen. Vermeiden Sie aus Leistungsgründen das Einbeziehen von Anforderungen mit langer Laufzeit oder von Anforderungen, die große Datenmengen abrufen.
Wichtig:
Die Batch API weist die gleichen Leistungsmerkmale wie einzelne API-Anforderungen auf, vermeidet jedoch den Overhead mehrerer Client-Server-Anforderungen. Die Batch-API ist nicht für die Verarbeitung paralleler Transaktionen vorgesehen, und API-Anforderungen mit langer Ausführungszeit können dazu führen, dass die API-Anforderung die maximale Transaktionszeit überschreitet und einen Fehler zurückgibt.
Größen- und Verarbeitungsbeschränkungen
Für Nutzlasten gelten die folgenden Größenbeschränkungen:
- Jedes Element in der Anforderung: 5 MB. Sie können diesen Standard ändern, indem Sie die Systemeigenschaft glide.rest.batch.max.inputSize aktualisieren. Höchstwert: 10 MB.
- Jedes Element in der Antwort: 10 MB. Sie können diesen Standard ändern, indem Sie die Systemeigenschaft glide.rest.batch.max.outputSize aktualisieren oder Ihrer Anforderung den Header X-BATCHREQUEST-MAX-OUTPUT-SIZE hinzufügen. Der Wert des Headers X-BATCHREQUEST-MAX-OUTPUT-SIZE darf den Wert der Systemeigenschaft nicht überschreiten.
Hinweis:
Wenn eine Anforderung länger als 30 Sekunden ausgeführt wird, beendet die Transaktionsmengenregel REST Batch API request timeout die Transaktion. Das Erhöhen des Werts dieser Transaktionsmengenregel kann zu Leistungsproblemen führen.
Wenn eine Batch-Anforderung ein Größen- oder Verarbeitungslimit erreicht, bricht das System die Transaktion ab und gibt unverarbeitete Anforderungen im nicht bedienten JSON-Array als Antwort zurück.
Batch: POST /now/batch
Sendet mehrere REST-API-Anforderungen in einem einzigen Aufruf.
Sie können jede in der Instanz verfügbare API in einen Batch- API-Aufruf einbeziehen. Vermeiden Sie aus Leistungsgründen das Einbeziehen von Anforderungen mit langer Laufzeit oder von Anforderungen, die große Datenmengen abrufen.
URL-Format
URL mit Versionsnummer: /api/now/{api_version}/batch
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| „batch_request_id“ | ID, die den Batch von Anforderungen identifiziert. Datentyp: Zeichenfolge |
| rest_requests | Erforderlich. Liste der Anforderungsobjekte, die in die Batch-Anforderung aufgenommen werden sollen. Datentyp: Array |
| rest_requests.body | Base64-codierter Textkörper der Anforderung. Gilt nur für Methoden, die einen Textkörper erfordern, z. B. POST. Vor dem Codieren kann der Textkörper ein beliebiges Format aufweisen. Zum Beispiel XML oder JSON. Datentyp: Zeichenfolge |
| rest_requests.exclude_response_headers | Kennzeichnung, die angibt, ob Antwortheader aus der Antwort ausgeschlossen werden sollen. Gültige Werte:
Datentyp: Boolesch Standardwert: false |
| rest_requests.headers | Liste der Anforderungsheaderobjekte, die an den Endpunkt gesendet werden sollen. Datentyp: Array |
| rest_requests.headers.name | Name des Headers. Datentyp: Zeichenfolge |
| rest_requests.headers.value | Wert des Headers. Datentyp: Zeichenfolge |
| rest_requests.id | Erforderlich. ID für jeden Artikel im Batch. Datentyp: Zeichenfolge |
| rest_requests.method | Erforderlich. Methode zum Aufrufen des zugeordneten Endpunkts. Datentyp: Zeichenfolge |
| rest_requests.url | Erforderlich. Relativer Pfad des Endpunkts, an den die Anforderung gesendet werden soll. Enthält die Abfrageparameter. Datentyp: Zeichenfolge |
Header
Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.
| Kopfzeile | Beschreibung |
|---|---|
| Akzeptieren | Datenformat des Antworttexts. Unterstützt nur application/json. |
| Inhaltstyp | Datenformat des Anforderungstexts. Unterstützt nur application/json. |
| X-BATCHREQUEST-MAX-AUSGABEGRÖSSE | Größenbeschränkung für jedes Element in der Batch-Antwort. Fügen Sie diesen Header hinzu, um eine niedrigere Größenbeschränkung als den Standardwert festzulegen, der durch die Systemeigenschaftglide.rest.batch.max.outputSize festgelegt wird. Sie können keinen höheren Wert als den Wert in der Systemeigenschaft festlegen. Standard: 10 MB. |
| Kopfzeile | Beschreibung |
|---|---|
| Keine |
Statuscodes
Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.
| Statuscode | Beschreibung |
|---|---|
| 200 | Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet. |
| 401 | Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben. |
| 500 | Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler. |
Parameter des Antwort-Haupttexts (JSON)
| Name | Beschreibung |
|---|---|
| „batch_request_id“ | ID des Batches, die dem Parameter batch_request_id in der Anforderung entspricht. Datentyp: Zeichenfolge |
| serviced_requests | Liste der Antwortobjekte aus der Batch-Anforderung. Datentyp: Array |
| serviced_requests.body | Base64-codierter Textkörper der Antwort. Um den Wert des Textkörpers abzurufen, decodieren Sie den Inhalt dieses Parameters Base64. Datentyp: Zeichenfolge |
| serviced_requests.error_message | Falls vorhanden, die Fehlermeldungen. Datentyp: Zeichenfolge |
| serviced_requests.execution_time | Zeit, die für die Ausführung der Batch-Elementanforderung benötigt wurde. Datentyp: Zahl Einheit: Millisekunden |
| serviced_requests.headers | Header für das Batch-Element. Datentyp: Array |
| serviced_requests.headers.name | Name des Headers. Datentyp: Zeichenfolge |
| serviced_requests.headers.value | Wert des Headers. Datentyp: Zeichenfolge |
| serviced_requests.id | ID des Batch-Elements, das dem Parameter rest_requests.id in der Anforderung entspricht. Datentyp: Zeichenfolge |
| serviced_requests.redirect_url | Falls vorhanden, die Umleitungs-URL. Datentyp: Zeichenfolge |
| serviced_requests.status_code | Statuscode für das Batch-Element. Datentyp: Zahl |
| serviced_requests.status_text | Text des Statuscodes für das Batch-Element. Datentyp: Zeichenfolge |
| unserviced_requests | IDs der Anforderungen, die nicht verarbeitet wurden, da die Batch-Anforderung ein Größen- oder Verarbeitungslimit erreicht hat. Datentyp: Array |
cURL-Anforderung
Diese Batch-Anforderung sendet zwei GET-Anforderungen an die Instanz und eine POST-Anforderung an die Incident-Tabelle. Der Textkörper der POST-Anforderung ist Base64-codiert.
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": []
}