Batch-API
Die Batch- API stellt Endpunkte zum Senden einer einzelnen Anforderung bereit, die mehrere REST-API-Aufrufe enthält, und gibt einen Stream von Antwortnutzlasten zurück.
Mit dieser REST-API können Integratoren:
- Verringern Sie die Zeit, die zum Senden von API-Anforderungen erforderlich ist, indem Sie sie in Stapeln zusammenfassen, und reduzieren Sie den Overhead, indem Sie Authentifizierung, Sitzungseinrichtung und Round-Trail-Datenverkehr auf einen einzigen Schritt beschränken.
- Erstellen Sie effizienteren Code für clientseitige Integrationen.
- Batch-Elementformate mischen und in eine einzelne Batch-Anforderung einbeziehen. Beispielsweise kann ein Batch eine Bases64-codierte Anforderung im XML-Format zum Senden an einen Endpunkt und eine Base64-codierte Anforderung im JSON-Format zum Senden an einen anderen Endpunkt enthalten.
- Empfangen eines Streams von Antwortnutzlasten als Rückgabe.
- 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 die Einbeziehung von Anforderungen mit langer Ausführungszeit und Anforderungen, die große Datenmengen abrufen.
Wichtig:
Die Batch-API weist die gleichen Leistungsmerkmale auf wie einzelne API-Anforderungen, vermeidet jedoch den Overhead mehrerer Client-Server-Anforderungen. Die Batch-API ist nicht für die parallele Transaktionsverarbeitung gedacht, 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 Verarbeitungsgrenzen
Nutzlasten entsprechen den 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 die Kopfzeile X-BATCHREQUEST-MAX-OUTPUT-SIZE zu Ihrer Anforderung hinzufügen. Der Header-Wert 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 Transaktionskontingentregel REST Batch API request timeout die Transaktion. Das Erhöhen des Werts dieser Transaktionsquotenregel kann zu Leistungsproblemen führen.
Wenn eine Batch-Anforderung eine Größen- oder Verarbeitungsgrenze erreicht, bricht das System die Transaktion ab und gibt unverarbeitete Anforderungen im nicht bedienten JSON-Array in der 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 die Einbeziehung von Anforderungen mit langer Ausführungszeit und Anforderungen, die große Datenmengen abrufen.
URL-Format
Versionierte URL: /api/now/{api_version}/batch
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| api_version | Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| batch_request_id | ID, die den Anforderungs-Batch 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 der Codierung kann der Text 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 der Kopfzeile. Datentyp: Zeichenfolge |
| rest_requests.headers.value | Wert der Kopfzeile. Datentyp: Zeichenfolge |
| rest_requests.id | Erforderlich. ID für jedes Element 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. |
| Content-Type | 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 der Systemeigenschaftglide.rest.batch.max.outputSize anzugeben. 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-Antwortcodesder 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, der 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 zu erhalten, decodieren Sie den Inhalt dieses Parameters mit 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 der Kopfzeile. Datentyp: Zeichenfolge |
| serviced_requests.headers.value | Wert der Kopfzeile. 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 eine Größen- oder Verarbeitungsgrenze 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 Text 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": []
}