Delen via

Batchverwerking | Graph API-concepten

  • Artikel

Van toepassing op: Graph API | Azure Active Directory (AD)

Met Azure AD Graph API kunt u batch-bewerkingen op entiteiten te verminderen interactie met de server. Uw verzoeken, batchverwerking minder netwerkbelasting en uw bewerkingen sneller voltooid.

Belangrijk

Wordt aangeraden dat u Microsoft Graph in plaats van Azure AD Graph API voor toegang tot Azure Active Directory-resources. Ontwikkeling van onze producten nu concentreren zich bij Microsoft Graph en geen verdere verbeteringen zijn gepland voor Azure AD Graph API. Er zijn een zeer beperkt aantal scenario's waarvoor Azure AD Graph API nog steeds mogelijk geschikt; Zie voor meer informatie de Microsoft Graph of de Azure AD Graph blogbericht in het Office-ontwikkelaarscentrum. Houd er rekening mee dat batchverwerking wordt momenteel niet ondersteund in Microsoft Graph; u moet gebruikmaken van Azure AD Graph API voor deze functie.

Graph API-ondersteuning voor aanvragen voor OData-batch

De semantiek voor batchverwerking entiteit zijn gedefinieerd door de OData 3.0 Batch-verwerking specificatie. De OData-specificatie definieert de volgende concepten voor batchaanvragen:

  • Een query is een enkel query of functie-aanroep.
  • Een wijzigingsset is een groep van een of meer invoegen, bijwerken of verwijderen van bewerkingen, actie aanroepen of service aanroepen.
  • Een batch is een container van bewerkingen, inclusief een of meer sets wijzigen en bewerkingen opvragen.

De Graph API ondersteunt een subset van de functionaliteit die door de OData-specificatie zijn gedefinieerd:

  • Één batch kan maximaal vijf query's bevatten en/of wijzigingensets zijn gecombineerd.
  • Een wijzigingsset kan maximaal één bron-object is gewijzigd en maximaal 20 koppeling toevoegen en verwijderen-link bewerkingen gecombineerd bevatten. Alle bewerkingen in de wijzigingsset moeten zich op een enkele bronentiteit.

Batchaanvragen Graph API

De volgende secties wordt beschreven hoe een batchaanvraag maakt het interpreteren van de batchrespons en voorbeelden van elke weergeven.

De syntaxis van de batch-aanvraag

Geef de optie $batch op de aanvraag-URI voor het uitvoeren van een batchaanvraag. Bijvoorbeeld:

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

Een batchaanvraag is verzonden naar de server met een enkele POST-instructie.

De nettolading is een meerdelige MIME-bericht met de batch en samenstellende query's en wijzigingssets. De nettolading bevat twee soorten MIME grenzen:

  • De grens van een batch scheidt elke set query en/of de wijziging in de batch.
  • De grens van een wijziging set scheidt afzonderlijke bewerkingen binnen een wijzigingsset.

Een afzonderlijke aanvraag binnen een wijzigingsset is identiek aan een aanvraag wanneer deze bewerking wordt aangeroepen door zelf. Bijvoorbeeld:

  • Als u wilt de indeling van nettolading (JSON of ATOM) opgeven voor elke bewerking in de wijzigingsset, de juiste Content-Type zijn en, indien nodig, kopteksten te accepteren.
  • Als u wilt de inhoud echo antwoord onderdrukken tijdens het maken van een entiteit, geeft u de Prefer-header met de waarde Nee-return-inhoud voor elke invoegbewerking in een wijzigingsset.

Voorbeeld van een aanvraag

Het volgende voorbeeld ziet u een batchaanvraag met vijf items:

  1. Een set die wordt gemaakt van een gebruiker wijzigen testuser@contoso.onmicrosoft.com (POST). Deze bewerking bevat de Prefer: Nee-antwoordinhoud-header moet worden onderdrukt de nieuwe gebruiker wordt geretourneerd.
  2. Een wijzigingsset die de eigenschappen voor afdeling en de functie van de nieuwe gebruiker (PATCH), en stelt de navigatie-eigenschap manager (PUT).
  3. Een query voor de manager van de nieuwe gebruiker (GET).
  4. Een wijzigingsset waarmee de nieuwe gebruiker (verwijderen) worden verwijderd.
  5. Een query voor de gebruiker (GET). Deze bewerking is mislukt omdat de gebruiker in de vorige stap is verwijderd.
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--

De syntaxis van de batch-antwoord

De respons retourneert een algemene statuscode voor de batch-aanvraag en afzonderlijke statuscodes en resultaat fragmenten voor elk item in de batch. Het antwoord is een meerdelige MIME-bericht met batch grenzen en wijziging stellen grenzen.

Ervan uitgaande dat de batch-aanvraag heeft geverifieerd en correct is ontvangen door de Graph API, wordt de batch-aanvraag statuscode 202 geaccepteerde, zelfs als een van de bewerkingen in de batch is mislukt. Als de batch aangevraagd zelf mislukt, mislukt dit voordat een bewerking in de batch wordt uitgevoerd. De batch-aanvraag kan bijvoorbeeld mislukken vanwege een verificatiefout waarin de statuscode van aanvraag deze fout wordt aangegeven.

-Fragment van de reactie voor een query-item bevat één statuscode die ofwel het slagen of mislukken van de bewerking, evenals een juiste antwoordtekst aangeeft.

De bewerkingen in een wijzigingsset worden moment; verwerkt dat wil zeggen, alle bewerkingen in de wijzigingsset is mislukt of de hele wijziging ingesteld mislukt. De Graph API blijft bewerkingen voor de verwerking in de wijzigingenset totdat een mislukt. Als een bewerking is mislukt, worden alle voorgaande bewerkingen in de wijzigingsset teruggedraaid.

Als alle bewerkingen in een wijzigingsset is verwerkt, de status code (en antwoordtekst) voor elke bewerking in de wijzigingsset wordt weergegeven in het antwoord van de set wijzigen. Als een bewerking in een wijzigingsset is mislukt, wordt slechts één statuscode geretourneerd voor de wijzigingsset. Dit is de status code (en antwoordtekst) geretourneerd door de mislukte bewerking; bijvoorbeeld: 400 onjuiste aanvraag of 404 niet gevonden.

Voorbeeldreactie

Het volgende voorbeeld ziet het antwoord voor de batchbewerking in het bovenstaande voorbeeld van een aanvraag verzonden. De status van de batchaanvraag zelf is ingesteld op 202 geaccepteerde. Dit geeft aan dat er geen problemen zijn met de batch zelf aanvragen. Het antwoord op elk item in de batch worden gescheiden met het batchresponse grens-id en elk antwoord op een bewerking in een wijzigingsset is gescheiden door een changesetresponse grens ID.

Hieronder vindt u de fragmenten reactie voor elke batch-item:

  1. De status voor de POST-aanvraag voor het maken van de nieuwe gebruiker is ingesteld op 204 geen inhoud. Dit komt doordat de Prefer header is ingesteld op return-no-content in de aanvraag. Hiermee wordt aangegeven dat de gebruiker is gemaakt.
  2. De reactie voor het tweede item in de batch bevat twee 204 geen inhoud antwoorden, één voor het bijwerken van de gebruiker object (PATCH) en één voor het instellen van de koppeling manager (PUT) in de wijzigingsset. Hiermee wordt aangegeven of beide bewerkingen gewijzigd zijn.
  3. Het antwoord voor de aanvraag om te lezen van de manager van de gebruiker, retourneert de koppeling naar de manager en de status van 200 OK.
  4. De status van de poging om te verwijderen van de gebruiker is 204 geen inhoud. Dit geeft aan dat de bewerking voltooid is
  5. De status voor de poging tot het lezen van de verwijderde gebruiker 404 niet gevonden en het antwoord bevat een code en een bericht weergegeven dat aangeeft dat de gebruiker (resource) is niet gevonden.
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--

Fout voorbeeldreactie

Zoals hierboven wordt beschreven, de Graph API retourneert een foutcode van 202 geaccepteerde voor de hele batch als de batch; die kan worden geaccepteerd, als de batch-aanvraag een onjuiste indeling heeft en er geen fouten, zoals een verificatiefout zijn. Anders de Graph API retourneert de fout en de batch niet verwerkt. Als een afzonderlijke item in de batch mislukt bevatten-fragment van de reactie voor het item een status code en antwoord hoofdtekst die dat de fout aangeeft. Wanneer een bewerking in een wijziging ingesteld mislukt, wordt een enkele antwoordthread-fragment geretourneerd voor de hele wijzigingsset en die fragment bevat de status en het antwoord hoofdtekst die zijn gekoppeld aan de mislukte bewerking.

Het volgende voorbeeld ziet een reactie van de batch-aanvraag met een wijzigingsset waarbij een van de bewerkingen is mislukt. Houd er rekening mee dat het batchantwoord-statuscode retourneert 202 geaccepteerde. De statuscode geretourneerd voor de wijzigingsset geeft aan dat een bewerking is mislukt met de status van 404 niet gevonden. Aanvullende foutinformatie is opgenomen in de hoofdtekst van de reactie voor de mislukte bewerking. De code element geeft u de foutcode Graph API en de bericht element bevat de fouttekenreeks bericht. In dit voorbeeld is de antwoordtekst ingesprongen voor de leesbaarheid.

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

Voor een verwijzing naar ziet het volgende voorbeeld van de batch die het bovenstaande antwoord gegenereerd. Het bevat een set één wijziging die drie gebruikers toegevoegd aan een groep. De Object-id's voor de laatste twee gebruikers zijn fictief: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee en ffffffff-ffff-ffff-ffff-ffffffffffff. De batch-URL en de bijbehorende aanvraagheaders worden weggelaten als beknopt alternatief bevat.

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

Aanvullende bronnen