Batch-API

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 5 Minuten Lesedauer

    • Die Batch Die 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 zusammen in Batches zusammenfassen, und reduzieren Sie den Overhead, indem Sie Authentifizierung, Sitzungs-Setup und Round-Trip-Datenverkehr auf einen einzigen Schritt beschränken.
    • Erstellen Sie effizienteren Code für clientseitige Integrationen.
    • Batch-Elementformate mischen und in eine einzelne Batch-Anforderung aufnehmen. 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.
    • 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 ein einbeziehen Batch API-Aufruf. Vermeiden Sie aus Leistungsgründen die Einbeziehung von Anforderungen mit langer Ausführungszeit, die große Datenmengen abrufen.

    Wichtig:
    Die Batch-API weist dieselben Leistungsmerkmale auf wie einzelne API-Anforderungen, vermeidet jedoch den Overhead mehrerer Client-Server-Anforderungen. Die Batch-API ist nicht für die parallele Transaktionsverarbeitung vorgesehen, und API-Anforderungen mit langer Laufzeit können dazu führen, dass die API-Anforderung die maximale Transaktionszeit überschreitet und einen Fehler zurückgibt.

    Größenbeschränkungen und Verarbeitungsbeschränkungen

    Nutzlasten entsprechen diesen Größenbeschränkungen:

    • Jedes Element in der Anforderung: 5 MB​. Sie können diesen Standard ändern, indem Sie aktualisieren glide.rest.batch.max.inputSize​Systemeigenschaft. Höchstwert: 10 MB.
    • Jedes Element in der Antwort: 10 MB. Sie können diesen Standard ändern, indem Sie aktualisieren glide.rest.batch.max.outputSize​Systemeigenschaft oder Hinzufügen von X-BATCHREQUEST-MAX-OUTPUT-SIZE​Header zu Ihrer Anforderung. Die X-BATCHREQUEST-MAX-OUTPUT-SIZE​Der Headerwert darf den Wert der Systemeigenschaft nicht überschreiten.
    Hinweis:
    Wenn eine Anforderung länger als 30 Sekunden ausgeführt wird, wird die REST Batch API request timeoutTransaktionskontingentregel beendet die Transaktion. Das Erhöhen des Werts dieser Transaktionsquotenregel kann zu Leistungsproblemen führen.

    Wenn eine Batch-Anforderung ein Größenlimit oder Verarbeitungslimit erreicht, bricht das System die Transaktion ab und gibt unverarbeitete Anforderungen in zurück Nicht aktiviert JSON-Array in der Antwort.

    Batch: /Now/Batch VERÖFFENTLICHEN

    Sendet mehrere REST API-Anforderungen in einem einzigen Aufruf.

    Sie können jede in der Instanz verfügbare API in ein einbeziehen Batch API-Aufruf. Vermeiden Sie aus Leistungsgründen die Einbeziehung von Anforderungen mit langer Ausführungszeit, die große Datenmengen abrufen.

    URL-Format

    Versionierte URL: /api/now/{api_Version}/Batch

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Version des Endpunkts, auf den zugegriffen werden soll. Beispiel: v1 Oder v2 .

    Datentyp: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstext-Parameter (JSON)
    Name Beschreibung
    Batch_Request_ID ID, die den Batch der Anforderungen identifiziert.

    Datentyp: Zeichenfolge
    Rest_Requests Erforderlich. Liste der Anforderungsobjekte, die in die Batch-Anforderung aufgenommen werden sollen.

    Datentyp: Array

    "rest_requests":[
   {
      "body": "String",
      "exclude_response_headers": Boolean,
      "headers":[Array],
      "id": "String",
      "method": "String",
      "url": "String"
   }
]
    Rest_Requests.body Base64-codierter Text der Anforderung. Gilt nur für Methoden, die einen Text erfordern, z. B. POST. Vor der Codierung kann der Textkörper ein beliebiges Format haben. 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:
    • Wahr: Antwortheader sind nicht in der Antwort enthalten.
    • Falsch: Antwortheader sind in der Antwort enthalten.

    Datentyp: Boolesch

    Standardwert: false
    Rest_Requests.Header Liste der Anforderungsheader-Objekte, die an den Endpunkt gesendet werden sollen.

    Datentyp: Array

    "headers":[
  {
    "name":"String",
    "value":"String"
  }
]
    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 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 .

    Tabelle : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder multipart/mixed.

    Um mehrteilige Antworten zu streamen, legen Sie fest glide.rest.serialize.disable_response_stream_bufferingSystemeigenschaft auf „wahr“. Weitere Informationen finden Sie unter Available system properties.
    Inhaltstyp Datenformat des Anforderungstexts. Unterstützt nur application/json.
    X-BATCHREQUEST-MAX-OUTPUT-SIZE ​ Größenbeschränkung für jedes Element in der Batch-Antwort. Fügen Sie diesen Header hinzu, um eine niedrigere Größenbeschränkung als die vom festgelegten Standardwerte bereitzustellen ​glide.rest.batch.max.outputSize​Systemeigenschaft. Sie können keinen höheren Wert als den Wert in der Systemeigenschaft festlegen.

    Standard: 10 MB.
    Tabelle : 5. Antwortkopfzeilen
    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 REST API-HTTP-Antwortcodes .

    Tabelle : 6. Statuscodes
    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 mit übereinstimmt batch_request_idParameter in der Anforderung.

    Datentyp: Zeichenfolge
    Serviced_Requests Liste der Antwortobjekte aus der Batch-Anforderung.

    Datentyp: Array

    "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-codierter Textkörper der Antwort. Um den Wert des Textkörpers abzurufen, decodiert Base64 den Inhalt dieses Parameters.

    Datentyp: Zeichenfolge
    Serviced_Requests.error_message Falls vorhanden, werden die Fehlermeldungen angezeigt.

    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.Header Header für das Batch-Element.

    Datentyp: Array

    "headers":[
  {
    "name":"String",
    "value":"String"
  }
]
    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 mit übereinstimmt rest_requests.idParameter in der Anforderung.

    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ößenlimit 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 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": []
}