Udostępnij za pośrednictwem

Przetwarzanie wsadowe | Pojęcia dotyczące interfejsu API programu Graph

  • Artykuł

Dotyczy: interfejsu API programu Graph | Azure Active Directory (AD)

Z interfejsem API usługi Azure AD Graph można partii operacje na jednostkach zmniejszenie dwukierunkowe przesyłanie danych do serwera. Przetwarzanie wsadowe żądań zmniejsza obciążenie sieci, a operacje ukończy szybciej.

Ważne

Zdecydowanie zaleca się używanie Microsoft Graph zamiast interfejsu API Azure AD Graph dostęp do zasobów usługi Azure Active Directory. Nasze programistycznych teraz jest skoncentrowana na program Microsoft Graph i interfejsu API usługi Azure AD Graph planowane żadne rozszerzenia funkcjonalności. Istnieje bardzo ograniczoną liczbę scenariuszy, w których interfejsu API usługi Azure AD Graph nadal może być odpowiednie; Aby uzyskać więcej informacji, zobacz Microsoft Graph lub Azure AD Graph wpis w blogu w Centrum deweloperów pakietu Office. Należy pamiętać, że przetwarzanie wsadowe nie jest obecnie obsługiwane w programie Microsoft Graph; należy użyć interfejsu API usługi Azure AD Graph dla tej funkcji.

Interfejs API Graph obsługę żądań wsadowych OData

Semantyka do przetwarzania wsadowego jednostki są definiowane przez specyfikację przetwarzania wsadowego OData 3.0. Specyfikację OData definiuje następujące pojęcia dla żądań wsadowych:

  • Zapytanie jest wywołanie pojedynczego zapytania lub funkcji.
  • Zestawu zmian jest grupą jednego lub więcej wstawiania, aktualizowania lub usuwania operacji, wywołania akcji lub wywołania usługi.
  • Partii jest kontenerem operacji, łącznie z jedną lub więcej zestawy zmian i operacji zapytania.

Interfejsu API programu Graph obsługuje podzbiór funkcji zdefiniowanych przez specyfikację OData:

  • Pojedyncza partia może zawierać maksymalnie pięć zapytania i/lub łączyć zestawy zmian.
  • Zmiany mogą zawierać maksymalnie jedno źródło obiektu modyfikacji i maksymalnie 20 link Dodaj i Usuń łącze operacje połączone. Wszystkie operacje w zestawie zmian musi być w jednostce jednego źródła.

Interfejs API Graph żądań wsadowych

W poniższych sekcjach opisano sposób tworzenia żądania wsadowego sposobu interpretacji odpowiedź wsadowa i Pokaż przykłady każdego z nich.

Składnia żądania wsadowe

Aby wykonać żądanie wsadowe, określ opcję $batch z identyfikatora URI żądania. Przykład:

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

Żądanie wsadowe są wysyłane na serwer za pomocą jednej dyrektywy POST.

Ładunek jest wieloczęściowa wiadomość MIME zawierający partii i jego składników zapytania i zestawy zmian. Ładunek zawiera dwa typy MIME granic:

  • Granic partii oddziela każdego zestawu zapytania i/lub zmiany w partii.
  • Granic zestawu zmian oddziela poszczególnych działań w zestawie zmian.

Oddzielne żądanie w zestawie zmian jest identyczna jak żądanie, gdy ta operacja jest wywoływana przez samego siebie. Przykład:

  • Aby określić format ładunku (JSON lub ATOM) dla każdej operacji w zestawie zmian obejmują odpowiednie Content-Type i, jeśli to konieczne, nagłówki Accept.
  • Aby pominąć echo zawartości odpowiedzi podczas tworzenia jednostki, określ nagłówek Prefer o wartości zwracane nie zawartości dla każdej operacji insert w zestawie zmian.

Przykładowe żądanie

W poniższym przykładzie przedstawiono żądanie wsadowe, która zawiera pięć elementów:

  1. Zestaw, który tworzy użytkownika, zmień A testuser@contoso.onmicrosoft.com (POST). Ta operacja obejmuje Prefer: nagłówek odpowiedzi nie zawartości do pomijania nowo utworzonego użytkownika zostały zwrócone.
  2. Zestaw zmian, który aktualizuje właściwości działu i stanowiskiem nowego użytkownika (poprawki) i ustawia jej właściwości nawigacji Menedżer (PUT).
  3. Zapytanie dla Menedżera nowego użytkownika (GET).
  4. Zestaw zmian, który usuwa nowego użytkownika (Usuń).
  5. Zapytanie dla użytkownika (GET). Ta operacja nie powiedzie się, ponieważ użytkownik został usunięty w poprzednim 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--

Składnia odpowiedzi wsadowych

Odpowiedź zwraca ogólną kod stanu dla żądania wsadowego i kodów stanu poszczególnych i fragmenty wyników dla każdego elementu w partii. Odpowiedź jest wieloczęściowa wiadomość MIME, zawierającą granice partii i zmień określają granice.

Przy założeniu, że żądanie wsadowe zostało prawidłowo uwierzytelnione i pomyślnie zostały odebrane przez interfejs API Graph, żądanie wsadowe zwraca kod stanu 202 zaakceptowane, nawet w przypadku awarii jednej z operacji w partii. Jeśli partii żądanie kończy się niepowodzeniem, ulegnie awarii, przed wykonaniem żadnych operacji w partii. Na przykład żądanie wsadowe może zakończyć się niepowodzeniem z powodu błędu uwierzytelniania, w których przypadku kodu stanu będzie wskazywać awarii.

Fragmentu odpowiedzi dla elementu zapytania zawiera kod pojedynczego stanu, który wskazuje powodzenie lub Niepowodzenie operacji, jak również wszystkie odpowiednie treści odpowiedzi.

Operacje w zestawie zmian są przetwarzane automatycznie; oznacza to, że wszystkie operacje w zestawie zmian powiodła się albo całą zmianę ustawić kończy się niepowodzeniem. Interfejsu API programu Graph nadal operacje przetwarzania w zestawie dopiero po niepowodzeniu jednego zmian. W przypadku niepowodzenia operacji wszystkich poprzednich operacji w zestawie zmian są przywracane.

Jeśli wszystkie operacje w zestawie zmian pomyślnie przetworzone, kod stanu (i treść odpowiedzi) dla każdej operacji w ramach zestawu zmian jest wyświetlany w odpowiedzi zestaw zmian. W przypadku niepowodzenia operacji w zestawie zmian dla zestawu zmian jest zwracany tylko jeden stan kodu. Są to stan kodu (i treść odpowiedzi) zwrócony przez operację zakończoną niepowodzeniem; na przykład 400 Niewłaściwe żądanie lub 404 — Nie znaleziono.

Przykładowa odpowiedź

W poniższym przykładzie przedstawiono odpowiedzi dla operacji zbiorczej wysłanych w żądaniu przykładowych pokazano powyżej. Stan dla żądania wsadowego sam jest ustawiony na 202 zaakceptowane. Oznacza to, że nie ma problemów z partii żądania samej siebie. Rozdzielana odpowiedzi do każdego elementu w partii z batchresponse rozdzielana identyfikator granic i każdego odpowiedzią na operację w zestawie zmian z changesetresponse granic Identyfikator.

Poniższa lista zawiera fragmenty odpowiedzi dla każdego elementu partii:

  1. Stan dla żądania POST do utworzenia nowego użytkownika jest ustawiony na 204 nr zawartości. Jest to spowodowane Prefer ustawiono nagłówka return-no-content w żądaniu. Wskazuje on, że użytkownik został pomyślnie utworzony.
  2. Odpowiedź dla drugiego elementu partii zawiera dwa 204 zawartości nie odpowiedzi: jeden dla aktualizacji obiektu użytkownika (poprawki), a drugi do ustawiania łącze Menedżera (PUT) w zestawie zmian. Oznacza to, że obie operacje zostały wprowadzone pomyślnie.
  3. Odpowiedzi na żądanie odczytu menedżerem użytkownika, zwraca łącze do menedżera i stan 200 OK.
  4. Jest w stanie usunąć użytkownika, próba 204 nr zawartości. Oznacza to, że operacja zakończyła się pomyślnie
  5. Stan próba odczytania usuwanego użytkownika to 404 — Nie znaleziono i odpowiedź zawiera kod i komunikat informujący o tym, że nie znaleziono użytkownika (zasobów).
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--

Przykładowa odpowiedź błąd

Jak wspomniano powyżej, interfejsu API programu Graph zwraca kod błędu 202 zaakceptowane dla całej partii, jeśli może zaakceptować partii; będący, jeśli żądanie partii jest poprawnie sformułowany i nie ma żadnych błędów, takich jak błąd uwierzytelniania. W przeciwnym razie interfejsu API programu Graph zwraca odpowiednie błąd i nie może przetwarzać partii. Jeśli pojedynczy element partii nie powiedzie się fragmentu odpowiedzi dla tego elementu będzie zawierać stan kodu i reagowania treści, która wskazuje, że błąd. Podczas operacji wewnątrz zmiany ustawić kończy się niepowodzeniem, fragment pojedynczą odpowiedź zostanie zwrócony dla zestawu zmian całego i tego fragmentu zawiera treść kodu i reagowania stan skojarzony z operację zakończoną niepowodzeniem.

W poniższym przykładzie przedstawiono odpowiedzi z żądania wsadowego, który zawiera grupę zmian, w którym jeden operacji nie powiodło się. Należy pamiętać, że odpowiedź wsadowa zwraca kod stanu 202 zaakceptowane. Kod stanu zwrócony dla zestawu zmian wskazuje, że operacja nie powiodła się ze stanem 404 — Nie znaleziono. Dodatkowe informacje o błędzie znajduje się w treści odpowiedzi dla operacji nie powiodło się. Kod element określa interfejs API programu Graph kod błędu i komunikat element zawiera ciąg komunikat błędu. W tym przykładzie treść odpowiedzi został wcięty dla czytelności.

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

Odwołania w poniższym przykładzie przedstawiono partii wygenerowania odpowiedzi powyżej. Zawiera zestaw jednej zmiany, który dodaje trzech użytkowników do grupy. Identyfikatory obiektów dla ostatnich dwóch użytkowników są fikcyjne: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee i ffffffff-ffff-ffff-ffff-ffffffffffff. Adres URL wsadowego i nagłówki żądania skojarzonych zostały pominięte w celu jego skrócenia.

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

Dodatkowe zasoby