Dávkové zpracování | Rozhraní Graph API koncepty

Článek
06/09/2016

Platí pro: Graph API | Azure Active Directory (AD)

S Azure AD Graph API můžete dávkové operace na entity ke snížení zbytečné komunikace se serverem. Dávkování své žádosti snižuje nároky na síť a vaše operace bude dokončeno rychleji.

Důležité

Důrazně doporučujeme použít Microsoft Graph místo Azure AD Graph API pro přístup k prostředkům Azure Active Directory. Náš vývojový program jsou nyní soustředit na Microsoft Graph a dále jsou plánované pro Azure AD Graph API. Je velmi omezený počet scénářů, pro které Azure AD Graph API může být vhodné; Další informace najdete v tématu Microsoft Graph nebo Azure AD Graph příspěvku na blogu v Office Dev Center. Všimněte si, že není aktuálně podporované dávkové zpracování v aplikaci Microsoft Graph; musíte použít Azure AD Graph API pro tuto funkci.

Podpora rozhraní Graph API pro dávkové žádosti OData

Sémantika pro dávkové zpracování entity jsou definovány OData 3.0 dávkové zpracování specifikace. Specifikace prostředí OData definuje následující koncepty pro dávkové požadavky:

Dotaz je jeden dotaz nebo funkce volání.
Sady změn je skupina jednoho nebo více vložit, aktualizovat nebo odstranit operace, akce volání nebo volání služby.
Batch je kontejner operace, včetně jeden nebo více změnit sady a dotaz operace.

Rozhraní Graph API podporuje podmnožinu funkcí definované specifikací OData:

Jeden batch může obsahovat maximálně pět dotazy nebo změnit sady kombinaci.
Sady změn může obsahovat maximálně jeden zdrojový objekt změny a až 20 operace přidat odkaz a odstraní propojení kombinaci. Všechny operace v sadě změn musí být u jedné zdrojové entity.

Rozhraní Graph API dávkových žádostí

Následující části popisují postup vytvoření dávkového požadavku, jak interpretovat dávkové odpovědi a zobrazit ukázky jednotlivých.

Syntaxe požadavku batch

K provedení dávkového požadavku, zadejte možnost $batch v identifikátoru URI požadavku. Příklad:

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

Dávkového požadavku je odeslat na server s direktivu jeden POST.

Datové části je vícedílné zprávě standardu MIME obsahující dávky a jeho základní dotazy a sady změn. Datová část obsahuje dva typy MIME hranic:

Hranice batch odděluje jednotlivé sady dotazu nebo změny v dávce.
Hranice sadu změn odděluje jednotlivé operace v rámci sady změn.

Jednotlivé požadavky v rámci sady změn je stejný jako požadavek při této operace je volána samostatně. Příklad:

Chcete-li určit formát datové části (JSON nebo ATOM) pro každou operaci v této sady změn, patří odpovídající Content-Type a v případě potřeby, hlavičky Accept.
Při vytváření entity potlačit echo obsahu odpovědi, zadejte hlavičku Prefer s hodnotou obsah no vrátí pro každou operaci vložení v sadě změn.

Ukázková žádost

Následující příklad ukazuje dávkového požadavku, která obsahuje pět položky:

A Změna nastavení, která vytvoří uživatele, testuser@contoso.onmicrosoft.com (POST). Tato operace zahrnuje Prefer: obsah odpovědi ne záhlaví potlačit nevrátila nově vytvořeného uživatele.
Sady změn, který aktualizuje vlastnosti oddělení a pracovní zařazení nového uživatele (oprava) a nastaví její manager navigační vlastnosti (PUT).
Dotaz pro správce nového uživatele (GET).
Sady změn, které odstraní nového uživatele (odstranit).
Dotaz pro uživatele (GET). Tato operace selže, protože byl uživatel odstraněn v předchozím kroku.

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

Syntaxe odpověď dávky

Odpověď se vrátí celkové stavový kód pro dávkový požadavek a jednotlivé stavové kódy a výsledek fragmenty pro každou položku v dávce. Odpověď je vícedílné zprávě standardu MIME zahrnující batch hranice a změně sady hranice.

Za předpokladu, že dávkový požadavek byl správně ověřen a byla úspěšně přijata pomocí rozhraní Graph API, dávkovou žádost vrátí stavový kód 202 platnýchi v případě, že jeden z operace v dávce selže. Pokud žádost o dávkové samotné selže, dojde k chybě před provedením jakékoli operace v dávce. Například dávkovou žádost může selhat z důvodu chyby ověřování, ve kterém případ stavový kód označí tohoto selhání.

Fragment odpověď pro položku dotazu obsahuje kód jednoho stavu, který udává úspěch nebo selhání operace, stejně jako žádné příslušné text odpovědi.

Operace v sadě změn se zpracovávají atomicky; To znamená buď úspěšné všechny operace v sadě změn nebo celý změně sady selže. Rozhraní Graph API bude pokračovat zpracování operace změnit nastavení, dokud jeden server selže. Pokud operace selže, všechny předchozí operace v sadě změny budou vráceny.

Pokud všechny operace v sadě změn úspěšně zpracována, kód stavu (a odpovědi) pro každou operaci v rámci této sady změn v rámci odpověď sady změn. Pokud se nezdaří operace v sadě změn, se vrátí jenom jeden stavový kód pro sadu změn. To bude kód stavu (a odpovědi) vrácená operací se nezdařilo; například 400 – Chybný požadavek nebo 404 nebyl nalezen.

Ukázková odpověď

Následující příklad ukazuje odpovědi pro dávkové operace odeslaných v požadavku ukázka uvedené výše. Je nastaven stav pro dávkový požadavek samotné 202 platných. Znamená to, že existuje žádné problémy s dávkového požadavku sám sebe. Odpověď na každou položku v dávce jsou odděleny dávkové odpovědi identifikátor hranic a každá odpověď operace v rámci sady změn je oddělený s changesetresponse hranic identifikátor.

Fragmenty odpovědi pro každou položku batch jsou následující:

Stav požadavku POST k vytvoření nového uživatele nastaven na 204 ne obsahu. Důvodem je, že Prefer záhlaví byla nastavena na return-no-content v požadavku. Označuje, že uživatel byl úspěšně vytvořen.
Odpověď pro položku druhý batch obsahuje dva 204 ne obsahu odpovědi, jeden pro aktualizaci objektu uživatele (oprava) a jeden pro nastavení správce odkaz (PUT) v této sady změn. To znamená, že oba operace byla úspěšná.
Odpovědi na požadavek načíst uživatele správce, vrátí odkaz na správce a stav 200 OK.
Stav pro pokus o odstranění uživatele, je 204 ne obsahu. To znamená, že operace byla úspěšná
Stav pro pokus o čtení Odstraněný uživatel je 404 nebyl nalezen a odpovědi obsahuje kód a zpráva, která určuje, že uživatel (prostředků) nebyl nalezen.

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

Ukázka chybové odpovědi

Jak je popsáno výše, rozhraní Graph API vrátí kód chyby z 202 platných pro celý batch, pokud ho může přijmout na listu; který je, že pokud je ve správném formátu dávkovou žádost a nejsou žádné chyby, jako je například chyby ověřování. Rozhraní Graph API, jinak vrátí příslušná chybová a nezpracovává dávky. Pokud jednotlivé položky v dávce selže, bude obsahovat fragment odpovědi pro tuto položku Stav kód a odpovědi obsahu, která označuje, že chyba. Operace uvnitř změnu nastavena nezdaří, vrátí odpověď jedné fragment pro sadu celý změn a tento fragment bude obsahovat stav kód a odpovědi body přidružené k selhání operace.

Následující příklad ukazuje na odpověď od dávková žádost obsahující sadu ve které jedna operace se nezdařila změn. Všimněte si, že odpověď dávky vrátí stavový kód 202 platných. Vrátí stavový kód pro sadu změn označuje, že operace se nezdařila se stavem 404 nebyl nalezen. Další informace o chybě je součástí odpovědi pro neúspěšnou operaci. Kód element určuje kód chyby rozhraní Graph API a zpráva element obsahuje řetězec chybové zprávy. V tomto příkladu má byl čitelnější odsazeny text odpovědi.

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

Následující příklad ukazuje, pro referenci generovaný výše odpověď dávky. Obsahuje sadu jediné změny, která přidá tři uživatele do skupiny. ID objektu pro poslední dva uživatelé jsou smyšlené: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee a ffffffff-ffff-ffff-ffff-ffffffffffff. Adresu batch URL a hlavičky přidružené žádosti byly vynechány jako stručný výtah.

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

Sdílet prostřednictvím