Freigeben über

Batchverarbeitung | Graph-API-Konzepte

  • Artikel

Gilt für: Graph-API | Azure Active Directory (AD)

Mit der Azure AD Graph-API können Sie Vorgänge für Entitäten in Batches zusammenfassen, um Roundtrips zum Server zu verringern. Wenn Sie Ihre Anforderungen in Batches zusammenfassen, wird der Netzwerkaufwand verringert und werden die zugehörigen Vorgänge schneller abgeschlossen.

Wichtig

Es wird dringend empfohlen, für den Zugriff auf Azure Active Directory-Ressourcen Microsoft Graph zu verwenden, nicht die Azure AD Graph-API. Wir konzentrieren unsere Entwicklungsarbeit auf Microsoft Graph, weitere Verbesserungen für die Azure AD Graph-API sind nicht geplant. Es gibt einige wenige Szenarien, in denen die Azure AD Graph-API möglicherweise noch geeignet ist. Weitere Informationen finden Sie im Office Dev Center im Blogbeitrag Microsoft Graph or the Azure AD Graph. Beachten Sie, dass Batchverarbeitung in Microsoft Graph derzeit nicht unterstützt wird. Sie müssen die Azure AD Graph-API für dieses Feature verwenden.

Graph-API-Unterstützung für OData-Batchanforderungen

Die Semantik für die Batchverarbeitung von Entitäten ist in der OData 3.0-Spezifikation für „Batch Processing“ (Batchverarbeitung) definiert. In der OData-Spezifikation sind die folgenden Konzepte für Batchanforderungen definiert:

  • Eine Abfrage (query) ist ein einzelner Abfrage- oder Funktionsaufruf.
  • Ein Changeset ist eine Gruppe, die mindestens einen Einfüge-, Aktualisierungs- oder Löschvorgang oder Aktions- oder Dienstaufruf umfasst.
  • Ein Batch ist ein Container von Vorgängen, der ein oder mehrere Changesets und Abfragevorgänge enthält.

Die Graph-API unterstützt eine Teilmenge der Funktionen, die in der OData-Spezifikation definiert sind:

  • Ein einzelner Batch kann eine Kombination aus bis zu fünf Abfragen und/oder Changesets enthalten.
  • Ein Changeset kann höchstens eine Quellobjektänderung und eine Kombination aus bis zu 20 "add-link"- und "delete-link"-Vorgängen enthalten. Alle Vorgänge im Changeset müssen sich auf eine einzelne Quellentität beziehen.

Graph-API-Batchanforderungen

In den folgenden Abschnitten wird beschrieben, wie eine Batchanforderung erstellt und die Batchantwort interpretiert wird; dies wird jeweils mit Beispielen veranschaulicht.

Syntax für Batchanforderungen

Geben Sie die $batch-Option im Anforderungs-URI an, um eine Batchanforderung auszuführen. Beispiel:

https://graph.windows.net/contoso.onmicrosoft.com/$batch?api-version=1.6

Eine Batchanforderung wird mit einer einzigen POST-Direktive an den Server gesendet.

Die Nutzlast ist eine mehrteilige MIME-Nachricht, die den Batch und dessen zugehörige Abfragen und Changesets enthält. Die Nutzlast beinhaltet zwei Arten von MIME-Begrenzungen:

  • Eine Batchbegrenzung trennt jede Abfrage und/oder jedes Changeset im Batch.
  • Eine Changesetbegrenzung trennt die einzelnen Vorgänge in einem Changeset.

Eine einzelne Anforderung in einem Changeset ist identisch mit einer Anforderung, die ausgeführt wird, wenn dieser Vorgang allein aufgerufen wird. Beispiel:

  • Um das Nutzlastformat (JSON oder ATOM) für jeden Vorgang im Changeset anzugeben, fügen Sie die entsprechenden Content-Type- und ggf. Accept-Header ein.
  • Um das Echo des Antwortinhalts zu unterdrücken, wenn eine Entität erstellt wird, geben Sie für jeden Einfügevorgang in einem Changeset den Prefer-Header mit dem Wert „return-no-content“ an.

Beispielanforderung

Das folgende Beispiel zeigt eine Batchanforderung, die fünf Elemente enthält:

  1. Ein Changeset, das den neuen Benutzer testuser@contoso.onmicrosoft.com erstellt (POST). Dieser Vorgang enthält den Header „Prefer: response-no-content“, um zu verhindern, dass der neu erstellte Benutzer zurückgegeben wird.
  2. Ein Changeset, das die Eigenschaften "department" (Abteilung) und "jobTitle" (Position) des neuen Benutzers aktualisiert (PATCH) und dessen Eigenschaft für die Managernavigation festlegt (PUT).
  3. Eine Abfrage für den Manager des neuen Benutzers (GET).
  4. Ein Changeset, das den neuen Benutzer löscht (DELETE).
  5. Eine Abfrage für den Benutzer (GET). Dieser Vorgang schlägt fehl, weil der Benutzer im vorherigen Schritt gelöscht wurde.
POST https://graph.windows.net/contoso.onmicrosoft.com/$batch?api-version=1.5 HTTP/1.1
Authorization: Bearer ey … jQA
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Host: graph.windows.net
Content-Length: 2961

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd620 
Content-Length: 631       

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd620 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/users?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 256
Prefer: return-no-content
Host: graph.windows.net

{
    "accountEnabled": true,
    "displayName": "Test User",
    "mailNickname": "testuser",
    "passwordProfile": { "password" : "Test1234", "forceChangePasswordNextLogin": false },
    "userPrincipalName": "testuser@contoso.onmicrosoft.com"
}

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd620----batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf 
Content-Length: 909

--changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

PATCH /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 72
Host: graph.windows.net

{
    "department": "Engineering",
    "jobTitle": "Test Engineer"
}

--changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

PUT /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com/$links/manager?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/a71e4d1c-ce99-40dc-8d4b-390eac63e039"
}

--changeset_4b2cbfb7-011d-4edb-8bbf-e044f9830aaf----batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: application/http 
Content-Transfer-Encoding:binary

GET /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com/$links/manager?api-version=1.5 HTTP/1.1
Accept: application/json
Host: graph.windows.net

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_9a0b5878-0f4a-4f57-91c5-9792cdd5ef20 
Content-Length: 331       

--changeset_9a0b5878-0f4a-4f57-91c5-9792cdd5ef20 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

DELETE /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Accept: application/json
Host: graph.windows.net


--changeset_9a0b5878-0f4a-4f57-91c5-9792cdd5ef20----batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: application/http 
Content-Transfer-Encoding:binary

GET /contoso.onmicrosoft.com/users/testuser@contoso.onmicrosoft.com?api-version=1.5 HTTP/1.1
Accept: application/json
Host: graph.windows.net

--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

Syntax für Batchantworten

Die Antwort gibt einen allgemeinen Statuscode für die Batchanforderung sowie einzelne Statuscodes und Ergebnisfragmente für jedes Element im Batch zurück. Die Antwort ist eine mehrteilige MIME-Nachricht, die Batchbegrenzungen und Changesetbegrenzungen enthält.

Angenommen, die Batchanforderung wurde ordnungsgemäß authentifiziert und erfolgreich von der Graph-API empfangen. In diesem Fall gibt die Batchanforderung den Statuscode 202 Accepted zurück, selbst wenn einer der Vorgänge im Batch fehlschlägt. Wenn die Batchanforderung selbst fehlschlägt, schlägt sie fehl, bevor ein Vorgang im Batch ausgeführt wird. Bei der Batchanforderung kann beispielsweise aufgrund eines Authentifizierungsfehlers ein Fehler auftreten. In diesem Fall wird der Fehler vom Statuscode angegeben.

Das Antwortfragment für ein Abfrageelement enthält einen einzelnen Statuscode, der entweder den Erfolg oder Fehlschlag des Vorgangs sowie alle entsprechenden Antworttexte angibt.

Die Vorgänge in einem Changeset werden atomar verarbeitet; d. h., entweder alle Vorgänge im Changeset werden erfolgreich abgeschlossen, oder der gesamte Changeset schlägt fehl. Die Graph-API fährt mit dem Verarbeiten von Vorgängen im Changeset fort, bis ein Vorgang fehlschlägt. Bei einem Vorgangsfehler erfolgt ein Rollback aller vorherigen Vorgänge im Changeset.

Wurden alle Vorgänge in einem Changeset erfolgreich verarbeitet, ist der Statuscode (und Antworttext) für jeden Vorgang im Changeset in der Changesetantwort enthalten. Wenn ein Vorgang in einem Changeset fehlschlägt, wird nur ein einziger Statuscode für das Changeset zurückgegeben. Dies ist der Statuscode (und Antworttext), der für den fehlgeschlagenen Vorgang zurückgegeben wurde, etwa 400 Bad Request oder 404 Not Found.

Beispielantwort

Im folgenden Beispiel wird die Antwort für den Batchvorgang veranschaulicht, der in der obigen Beispielanforderung gesendet wurden. Der Status für die Batchanforderung selbst ist auf 202 Accepted festgelegt. Dies kennzeichnet, dass es keine Probleme mit dem Batch selbst gibt. Die Antwort auf jedes Element im Batch ist mit der batchresponse-Begrenzungs-ID und jede Antwort auf einen Vorgang in einem Changeset mit einer changesetresponse-Begrenzungs-ID begrenzt.

Die folgende Liste enthält die Antwortfragmente für jedes Batchelement:

  1. Der Status für die POST-Anforderung, mit der der neue Benutzer erstellt wird, ist auf 204 No Content festgelegt. Der Grund hierfür ist, dass der Prefer-Header in der Anforderung auf return-no-content festgelegt wurde. Dies gibt an, dass der Benutzer erfolgreich erstellt wurde.
  2. Die Antwort für das zweite Batchelement enthält zwei 204 No Content -Antworten, eine für die Aktualisierung des Benutzerobjekts (PATCH) und eine für die Einstellung des Managerlinks (PUT) im Changeset. Dies gibt an, dass beide Vorgänge erfolgreich waren.
  3. Die Antwort für die Anforderung zum Lesen des Managers des Benutzers gibt den Link zu dem Manager und den Status 200 OK zurück.
  4. Der Status für den Versuch, den Benutzer zu löschen, lautet 204 No Content. Dies weist darauf hin, dass der Vorgang erfolgreich war.
  5. Der Status für den Versuch, den gelöschten Benutzer zu lesen, lautet 404 Not Found , und die Antwort enthält einen Code und eine Nachricht, in der mitgeteilt wird, dass der Benutzer (die Ressource) nicht gefunden wurde.
HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
Content-Type: multipart/mixed; boundary=batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Expires: -1
Server: Microsoft-IIS/8.5
ocp-aad-diagnostics-server-name: Nv0YIi2YUldDWu0YPQAXsYwXQ4ttyr7ded6Waf8xyCc=
request-id: 2f7d2f81-3441-4c2a-b494-25cd1d6ce624
client-request-id: f40c00af-3e1f-4198-9261-386f0e3aecc6
x-ms-gateway-rewrite: false
x-ms-dirapi-data-contract-version: 1.5
ocp-aad-session-key: cdhenl3mgHuI3vaRRIQ14uXdwRLUqirNpDXjJP42EzUEvqhhn2NFr22ulR4PsqrM1UD_eSUDItt7J9kUQhNvTT_48q90coHHt2RutCIgPNg.lD81Z0iS2SaHbqkfAaDvbbigoX7ak7rfiUGFby0LOIE
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Tue, 20 Jan 2015 23:21:15 GMT
Content-Length: 3065

--batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: multipart/mixed; boundary=changesetresponse_8a63ce5e-ed31-4de6-bc90-9d3ff31debbb--changesetresponse_8a63ce5e-ed31-4de6-bc90-9d3ff31debbb
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
Preference-Applied: return-no-content
DataServiceVersion: 3.0;
Location: https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/6a287a96-ede9-44d2-b685-d6fc03a124c5/Microsoft.DirectoryServices.User
DataServiceId: https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/6a287a96-ede9-44d2-b685-d6fc03a124c5


--changesetresponse_8a63ce5e-ed31-4de6-bc90-9d3ff31debbb----batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: multipart/mixed; boundary=changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6--changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 1.0;


--changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 1.0;


--changesetresponse_11ba5cf0-9fba-4995-9f15-bd5c9981cdd6----batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
DataServiceVersion: 3.0;
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8
X-Content-Type-Options: nosniff
Cache-Control: no-cache

{
  "odata.metadata":"https://graph.windows.net/contoso.onmicrosoft.com/$metadata#directoryObjects/$links/manager",
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/directoryObjects/a71e4d1c-ce99-40dc-8d4b-390eac63e039/Microsoft.DirectoryServices.User"
}
--batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: multipart/mixed; boundary=changesetresponse_bb215a84-f91e-4486-a771-ba2cc5d429d1--changesetresponse_bb215a84-f91e-4486-a771-ba2cc5d429d1
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 1.0;


--changesetresponse_bb215a84-f91e-4486-a771-ba2cc5d429d1----batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 404 Not Found
X-Content-Type-Options: nosniff
Cache-Control: no-cache
DataServiceVersion: 3.0;
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8

{
  "odata.error":
    {
      "code":"Request_ResourceNotFound",
      "message":
        {
          "lang":"en",
          "value":"Resource 'testuser@contoso.onmicrosoft.com' does not exist or one of its queried reference-property objects are not present."
        }
    }
}
--batchresponse_1eb70252-25d2-466c-9a1d-7a3f45378b06--

Beispielfehlerantwort

Wie oben erläutert, gibt die Graph-API den Fehlercode 202 Accepted für den gesamten Stapel zurück, wenn sie den Batch akzeptiert. Dies ist der Fall, wenn die Batchanforderung wohlgeformt ist und keine Fehler vorliegen, etwa ein Authentifizierungsfehler. Andernfalls gibt die Graph-API den entsprechenden Fehler zurück, und der Batch wird nicht von ihr verarbeitet. Tritt für ein einzelnes Element im Batch ein Fehler auf, enthält das Antwortfragment für dieses Element einen Statuscode und einen Antworttext, der den Fehler angibt. Wenn in einem Vorgang in einem Changeset ein Fehler auftritt, wird für den gesamten Changeset ein einzelnes Antwortfragment zurückgegeben, und dieses Fragment enthält den Statuscode und den Antworttext, die dem fehlgeschlagenen Vorgang zugeordnet sind.

Das folgende Beispiel zeigt eine Antwort zu einer Batchanforderung, die ein Changeset enthält, in dem einer der Vorgänge fehlgeschlagen ist. Beachten Sie, dass die Batchantwort den Statuscode 202 Accepted zurückgibt. Der für das Changeset zurückgegebene Statuscode gibt an, dass ein Vorgang mit dem Status 404 Not Found fehlgeschlagen ist. Weitere Fehlerinformationen sind im Antworttext für den fehlgeschlagenen Vorgang enthalten. Das code-Element gibt den Fehlercode für die Graph-API an, und das message-Element enthält die Zeichenfolge der Fehlermeldung. In diesem Beispiel wurde der Antworttext zur besseren Lesbarkeit eingezogen.

HTTP/1.1 202 Accepted
Cache-Control: no-cache
Pragma: no-cache
Content-Type: multipart/mixed; boundary=batchresponse_3ac28387-a100-4758-8998-8b9ec36f9fdc
Expires: -1
Server: Microsoft-IIS/8.5
ocp-aad-diagnostics-server-name: 1l3fvSoDCV+VKoBCuHRN+HIwCACBOck3dqmtCGj+aiU=
request-id: e434261b-c32f-48b4-b21d-3e1beab6d525
client-request-id: 236bf26e-b4e8-40a4-b6fb-d41105a7b178
x-ms-gateway-rewrite: false
x-ms-dirapi-data-contract-version: 1.5
ocp-aad-session-key: 9aOaAUxX95OZ0ctrYbeLUproN-37GypZXrss0PYKhEfqamKRG-C68hFcCw5h-ZCWFqBrXPrldGEnjq4CKKr0bW91tjrdo-BlwAqHxbP5jq4.FaXtVZni3cSsWFRMSjQAbjiluPcEvZofwp9OH3t1fyk
X-Content-Type-Options: nosniff
DataServiceVersion: 1.0;
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Powered-By: ASP.NET
Date: Wed, 21 Jan 2015 21:13:25 GMT
Content-Length: 779

--batchresponse_3ac28387-a100-4758-8998-8b9ec36f9fdc
Content-Type: multipart/mixed; boundary=changesetresponse_72ba9a5a-2da3-4d39-ae4f-dd9527efd742--changesetresponse_72ba9a5a-2da3-4d39-ae4f-dd9527efd742
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 404 Not Found
X-Content-Type-Options: nosniff
DataServiceVersion: 3.0;
Content-Type: application/json;odata=minimalmetadata;streaming=true;charset=utf-8

{
  "odata.error":
    {
      "code":"Request_ResourceNotFound",
      "message":
        {
          "lang":"en",
          "value":"Resource 'eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee' does not exist or one of its queried reference-property objects are not present."
        }
    }
}
--changesetresponse_72ba9a5a-2da3-4d39-ae4f-dd9527efd742----batchresponse_3ac28387-a100-4758-8998-8b9ec36f9fdc--

Das folgende Beispiel zeigt zu Referenzzwecken den Batch, der die oben genannte Antwort generiert hat. Er enthält ein einzelnes Changeset, das einer Gruppe drei Benutzer hinzufügt. Die Objekt-IDs für die beiden letzten Benutzer sind frei erfunden: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee and ffffffff-ffff-ffff-ffff-ffffffffffff. Die Batch-URL und die zugehörigen Anforderungsheader sind aus Gründen der Übersichtlichkeit nicht angegeben.

--batch_36522ad7-fc75-4b56-8c71-56071383e77b 
Content-Type: multipart/mixed; boundary=changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Length: 1432

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/groups/fc15e7ef-993f-4865-bf37-317d9b8017b8/$links/members?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/a71e4d1c-ce99-40dc-8d4b-390eac63e039"
}

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/groups/fc15e7ef-993f-4865-bf37-317d9b8017b8/$links/members?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee
"
}

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

POST /contoso.onmicrosoft.com/groups/fc15e7ef-993f-4865-bf37-317d9b8017b8/$links/members?api-version=1.5 HTTP/1.1
Content-Type: application/json
Accept: application/json
Content-Length: 112
Host: graph.windows.net

{
  "url":"https://graph.windows.net/contoso.onmicrosoft.com/users/ffffffff-ffff-ffff-ffff-ffffffffffff"
}

--changeset_5a769eb2-d1a7-4a10-94f6-d1a5ed5c4bc0----batch_36522ad7-fc75-4b56-8c71-56071383e77b--

Zusätzliche Ressourcen