Batch-bearbetning | Graph API-begrepp

Gäller för: Graph API | Azure Active Directory (AD)

Du kan batch-åtgärder på enheterna för att minska görs till servern med Azure AD Graph API. Batchbearbetning dina begäranden minskar nätverksresurser och din verksamhet slutförs snabbare.

Viktigt

Vi rekommenderar starkt att du använder Microsoft Graph i stället för Azure AD Graph API för att komma åt resurser i Azure Active Directory. Vårt utvecklingsarbete är nu samlade på Microsoft Graph och inga fler förbättringar som planeras att Azure AD Graph API. Det finns ett begränsat antal scenarier som Azure AD Graph API kan fortfarande vara lämplig. Mer information finns i Microsoft Graph eller Azure AD Graph blogginlägget i Office Dev Center. Observera att batch-bearbetning inte stöds för närvarande i Microsoft Graph; Du behöver använda Azure AD Graph API för den här funktionen.

Graph API-stöd för OData-batch-begäranden

Semantiken för entiteten batchbearbetning definieras av den bearbetning OData 3.0 Batch-specifikationen. OData-specifikationen definierar följande begrepp för gruppbegäranden:

En fråga är ett enda anrop frågan eller funktionen.
En ändringslista är en grupp med en eller flera infoga, uppdatera eller ta bort åtgärder, åtgärden anrop eller service-anrop.
En batch är en behållare för åtgärder, inklusive en eller flera ändringsuppsättningar och fråga åtgärder.

Graph API stöder en delmängd av funktionerna som definierats av OData-specifikationen:

En enskild batch kan innehålla högst fem frågor och/eller ändra anger kombineras.
En ändringslista får innehålla högst en källa objekt ändras och upp till 20 Lägg till länk och ta bort länk operations kombineras. Alla åtgärder i ändringslistan måste finnas på en enda entitet.

Gruppbegäranden för Graph API

I följande avsnitt beskrivs hur du skapar en batch-begäran för att tolka batchsvar och visar exempel på var och en.

Syntax för batch-begäran

Ange alternativet $batch på URI-begäran för att utföra en batch-begäran. Exempel:

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

Batch-begäran skickas till servern med en enda POST-direktiv.

Nyttolasten är ett flerdelade MIME-meddelande som innehåller gruppen och dess ingående frågor och ändringsgrupper. Nyttolasten innehåller två typer av MIME-gränser:

En batch gräns avgränsar varje fråga och/eller ändra uppsättning i batchen.
Ändra set gräns separerar enskilda åtgärder i en Ändringsgrupp.

En enskild begäran inom en ändringslista är identisk med en begäran om att åtgärden anropas av sig själv. Exempel:

Om du vill ange nyttolastformatet (JSON eller ATOM) för varje åtgärd i ändringsuppsättningen är lämplig Content-Type och, om det behövs, acceptera huvuden.
Om du inte svar innehåll echo när du skapar en entitet, ange rubriken Prefer med RETUR utan innehåll värdet för varje insert-åtgärden i en Ändringsgrupp.

Exempel på begäran

I följande exempel visas en batch-begäran som innehåller fem objekt:

En ändringslista som skapar en användare, testuser@contoso.onmicrosoft.com (POST). Den här åtgärden innehåller Prefer: svar utan innehåll sidhuvud att utelämna den nyligen skapade användaren som returneras.
En ändringslista som uppdaterar egenskaperna för den nya användaren (korrigering) avdelning och befattning och anger egenskapen manager navigering (PUT).
En fråga för manager på den nya användaren (GET).
En ändringslista som tar bort den nya användaren (ta bort).
En fråga för användare (GET). Den här åtgärden misslyckas eftersom användaren har tagits bort i föregående steg.

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 batch-svar

Svaret returnerar en övergripande statuskoden för batch-begäran och enskilda statuskoder och resultatet fragment för varje objekt i gruppen. Svaret är ett flerdelade MIME-meddelande som innehåller batch gränser och ändringslista gränser.

Förutsatt att batch-begäran har autentiserats korrekt och har har tagits emot av Graph API, batch-begäran returnerar statuskod 202 godkända, även om en av åtgärderna i gruppen misslyckas. Om gruppen begär misslyckas, misslyckas innan alla åtgärder i batchen körs. Batch-begäran kan exempelvis misslyckas på grund av ett autentiseringsfel där fallet statuskoden indikerar att fel.

Svaret fragment för en artikel i frågan innehåller en enkel statuskod som anger antingen lyckades eller misslyckades för åtgärden samt eventuella brödtext för svar som är lämpliga.

Åtgärder i en Ändringsgrupp bearbetas automatiskt; det vill säga antingen alla åtgärder i ändringslistan lyckas, eller hela ändringen ange misslyckas. Graph API fortsätter bearbetningen i ändringslistan tills en misslyckas. Om en åtgärd misslyckas återställs alla föregående åtgärder i listan.

Om alla åtgärder i en Ändringsgrupp lyckas bearbetas status kod (och svarstexten) för varje åtgärd i listan visas inom ändra set-svar. Om en åtgärd i en Ändringsgrupp misslyckas, returneras en enkel statuskod för ändringsgruppen. Detta blir status koden (och svarstexten) returneras av den misslyckade åtgärden; till exempel 400 Felaktig förfrågan eller 404 hittades inte.

Exempelsvar

I följande exempel visas svaret för batchåtgärd som skickades i begäran exemplet ovan. Status för den batch-begäranden anges till 202 godkända. Detta anger att det inga problem med batch begära sig själv. Svaret på varje objekt i batchen avgränsas med den batchresponse gräns identifierare, och varje svar på en åtgärd i en avgränsas med en changesetresponse gräns identifierare.

I följande lista visas svaret fragment för varje batch-objekt:

Status för POST-begäran att skapa den nya användaren anges till 204 Nej innehåll. Detta beror på att den Prefer huvud har angetts return-no-content i begäran. Anger att användaren har skapats.
Svaret på det andra batch-objektet innehåller två 204 Nej innehåll svar, en för objektet uppdateringen (korrigering) och en för att ställa in länken manager (PUT) i listan. Detta anger att både operations har genomförts.
Svaret på begäran att läsa användarens chef returnerar länken till chefen och statusen 200 OK.
Status för försök att ta bort den här användaren är 204 Nej innehåll. Detta anger att åtgärden lyckades
Status för försök att läsa den borttagna användaren är 404 hittades inte och svaret innehåller en kod och ett meddelande som anger att användaren (resurs) inte hittades.

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--

Fel exempelsvar

Som beskrivs ovan kan Graph API returnerar en felkod för 202 godkända för hela batch om den kan acceptera batch; som är, om batch-begäran är giltig och att det inte finns några fel, till exempel ett autentiseringsfel. Annars returnerar lämpliga fel Graph-API och bearbetar inte batchen. Om ett enskilt objekt i batchen inte innehålla status kod och svar brödtext som anger felet svar fragment för objektet. När en åtgärd i en ändring misslyckas, returneras ett enda svar fragment för hela ändringsuppsättningen och det fragmentet innehåller status-kod och svar brödtext som är associerade med den misslyckade åtgärden.

I följande exempel visas ett svar från batch-begäran som innehåller en ändring i där en av åtgärderna misslyckas. Observera att batch svaret returnerar statuskod 202 godkända. Statuskoden som returnerades för ändringsgruppen anger att en åtgärd misslyckades med status 404 hittades inte. Ytterligare information om fel ingår i svarstexten för den misslyckade åtgärden. Den kod element anger felkoden Graph API och meddelandet elementet innehåller felsträng för meddelandet. I det här exemplet har blivit sänkt svarstexten för läsbarhet.

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--

I följande exempel visas referens batch som genererade svaret ovan. Den innehåller en enda ändring som lägger till tre användare i en grupp. Objekt-ID för de två sista användarna är fiktiva: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee och ffffffff ffff-ffff-ffff-ffffffffffff. Batch-URL och associerade begärandehuvuden utelämnas planeringsaspekter.

--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--

Ytterligare resurser

Last updated on 2016-06-09

Dela via

Batch-bearbetning | Graph API-begrepp

Graph API-stöd för OData-batch-begäranden

Gruppbegäranden för Graph API

Syntax för batch-begäran

Exempel på begäran

Syntax för batch-svar

Exempelsvar

Fel exempelsvar

Ytterligare resurser

Ytterligare resurser