Toplu işleme | Grafik API'si kavramları

Makale
06/09/2016

Uygulandığı öğe: Graph API | Azure Active Directory (AD)

Azure AD grafik API'si ile sunucuya gidiş-dönüş azaltmak için varlıklar üzerinde işlemler toplu. İsteklerinizi toplu işleme ağ yükünü azaltır ve işlemlerinizi daha hızlı bir şekilde tamamlanır.

Önemli

Kullanmanız önerilir Microsoft Graph Azure Active Directory kaynaklara erişmek için Azure AD Graph API yerine. Geliştirme çalışmalarımızı artık Microsoft Graph yoğunlaşmıştır ve herhangi bir geliştirme için Azure AD Graph API planlanmaktadır. Senaryolar için Azure AD Graph API hala uygun olabilir, çok sınırlı sayıda vardır; Daha fazla bilgi için bkz: Microsoft Graph veya Azure AD grafik Office Geliştirici Merkezi blog postasına. Toplu işleme Microsoft Graph içinde şu anda desteklenmiyor unutmayın; Azure AD grafik API'si için bu özelliği kullanmak gerekir.

OData toplu isteklerini grafik API'si desteği

Varlık toplu işleme anlamları tarafından tanımlanan OData 3.0 toplu işleme belirtimi. OData belirtimi toplu istekler için aşağıdaki kavramlar tanımlar:

Tek bir sorgu veya işlev çağrısının sorgudur.
Bir değişiklik kümesini aşağıdakilerden oluşan bir gruptur veya daha fazla Ekle, Güncelleştir veya işlemleri, eylem çağrılarını ya da hizmet çağrılarını silme.
Bir toplu biri de dahil olmak üzere işlemlerinin bir kapsayıcı veya daha fazla kümelerini değiştirmek ve işlemleri sorgu.

Grafik API'si OData belirtim tarafından tanımlanan işlevlerinin bir alt kümesini destekler:

Tek bir toplu iş en fazla beş sorguları içerir ve/veya birleştirilmiş kümelerini değiştirmek.
Bir değişiklik kümesini bir kaynak nesne değiştirilme ve birleştirilmiş 20 bağlantı ekle ve Sil bağlantısını işlemlerine kadar en içerebilir. Değişiklik kümesini tüm işlemleri tek kaynak varlık üzerinde olmalıdır.

Grafik API'si toplu istekleri

Aşağıdaki bölümlerde bir toplu isteği oluşturmak nasıl toplu yanıt yorumlar ve her örnekleri göster.

Toplu istek sözdizimi

Bir toplu isteği gerçekleştirmek için istek URI'si $batch seçeneğini belirtin. Örneğin:

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

Bir toplu isteği tek bir POST yönergesi sunucusuyla gönderilir.

Yükü, toplu işlem ve bağlı sorgular ve değişiklik kümelerini içeren çok parçalı bir MIME iletisidir. Yükü MIME sınırları iki tür içerir:

Bir toplu işlem sınırı her bir sorgu ve/veya değişiklik kümesi toplu işlemdeki ayırır.
Bir değişiklik kümesi sınır bir değişiklik kümesi içinde tek tek işlemleri ayırır.

Bir değişiklik kümesi içinde ayrı bir istek bu işlemin kendisi tarafından çağrıldığında yapılan bir istek aynıdır. Örneğin:

Değişiklik kümesini her bir işlemde eklemek için uygun Content-Type ve gerekirse yükü biçimini (JSON veya ATOM) belirtmek için kabul etme üstbilgisi.
Bir varlık oluşturulurken yanıt içerik Yankı gizlemek için bir değişiklik kümesindeki her ekleme işlemi için dönüş Hayır içerik değerle Prefer üstbilgisini belirtin.

Örnek istek

Aşağıdaki örnek, beş öğelerini içeren bir toplu isteğin gösterir:

Bir değişiklik, kullanıcının oluşturduğu kümesi testuser@contoso.onmicrosoft.com (POST). Bu işlem Prefer içerir: döndürülen yeni oluşturulan kullanıcı gizlemek için yanıt Hayır içerik üstbilgisi.
Yeni kullanıcı (düzeltme eki) departmanı ve iş unvanı özelliklerini güncelleştirir ve onun Yöneticisi gezinti özelliği (PUT) ayarlayan bir değişiklik kümesini.
Bir sorgu (GET) yeni kullanıcı Yöneticisi.
Yeni kullanıcı (silme) siler değişiklik kümesi.
Kullanıcı (GET) için bir sorgu. Kullanıcı önceki adımda silindiği için bu işlemi başarısız olur.

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

Toplu yanıt sözdizimi

Yanıt toplu işlemde toplu istek için genel bir durum kodu ve tek tek durum kodları ve her öğe için sonuç parçalarını döndürür. Yanıt toplu sınırları içeren bir çok parçalı MIME iletisidir ve değişiklik sınırları ayarlayın.

Toplu istek düzgün bir şekilde doğrulandı ve grafik API'si tarafından başarıyla alındı varsayılarak toplu isteği durum kodunu döndüren 202 kabul edilentoplu işlemlerde biri başarısız olsa bile. Toplu işlem kendisini isteği başarısız olursa, toplu işteki herhangi bir işlem yürütülmeden önce başarısız olur. Örneğin, toplu isteği durum kodu durumda o hatası belirtecektir bir kimlik doğrulama hatası nedeniyle başarısız olabilir.

Bir sorgu öğesi için yanıt parçası başarı veya başarısızlık, uygun bir yanıt gövdesi yanı sıra işlemi belirten tek durum kodunu içerir.

Bir değişiklik kümesini işlemlerinde otomatik olarak işlenir; diğer bir deyişle, değişiklik kümesindeki tüm işlemleri başarılı veya başarısız tüm değişiklik kümesi. Grafik API'si işlemleri başarısız kadar ayarlama değişiklik devam eder. Bir işlem başarısız olursa, tüm önceki işlemlerinde değişiklik kümesini geri alınır.

Bir değişiklik kümesindeki tüm işlemleri başarıyla varsa işlenen, durum kodu (ve yanıt gövdesi) değişiklik kümesindeki her bir işlemin içinde değişiklik kümesi yanıtı görünür. Bir değişiklik kümesindeki bir işlem başarısız olursa, yalnızca bir tek durum kodu için değişiklik kümesini döndürülür. Bu durum kodunu (ve yanıt gövdesi) başarısız işlem tarafından; döndürülen olacaktır Örneğin, 400 Hatalı istek veya 404 Bulunamadı.

Örnek yanıt

Aşağıdaki örnek yanıt yukarıda gösterilen örnek istek gönderilen toplu işlemi için gösterir. Toplu istek durumunu ayarlamak 202 kabul edilen. Bu belirten var. toplu ile herhangi bir sorun kendisini isteği. Her toplu iş öğesinde yanıtı ile ayrılmış yürütülebilir öğelerin batchresponse sınır tanımlayıcısı ve her bir değişiklik kümesi içinde bir işlem yanıta ile ayrılmış bir changesetresponse sınır tanımlayıcı.

Her toplu iş öğesi için yanıt parçaları listeler:

Yeni kullanıcı oluşturmak POST isteği için durum kümesine 204 Hayır içerik. Bunun nedeni, Prefer üstbilgisi ayarlandığı return-no-content isteği. Kullanıcının başarıyla oluşturulduğunu belirtir.
Yanıt ikinci toplu iş öğesi için iki içeren 204 Hayır içerik yanıtlar, kullanıcı nesnesi Güncelleştirmesi (düzeltme eki) için diğeri (PUT) Yöneticisi bağlantı değişiklik kümesini ayarlamak için. Bu, her iki işlem başarılı olduğunu gösterir.
Kullanıcının Yöneticisi'ni okumak istek için yanıt verir Bağlantı Yöneticisi ve durumunu 200 Tamam.
Kullanıcı silme denemesi durumu 204 Hayır içerik. Bu işlemin başarılı olup olmadığını gösterir
Silinen kullanıcı okuma girişimi durumu 404 Bulunamadı ve bir kod ve kullanıcı (kaynak) bulunamadığını belirten ileti yanıtı içerir.

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

Örnek hata yanıtı

Yukarıda açıklandığı gibi grafik API'si hata kodunu döndürür 202 kabul edilen tüm toplu için olan toplu; kabul edebilir, toplu isteği doğru biçimlendirildiğinden ve kimlik doğrulama hatası gibi herhangi bir hata durumunda. Aksi takdirde, grafik API'si uygun hata verir ve toplu işlemez. Toplu iş içinde ayrı bir öğe başarısız olursa bu öğe için yanıt parçası hata gösteren bir durum kodu ve yanıt gövdesi içerir. Bir işlem içinde bir değişiklik başarısız ayarladığınızda, tüm değişiklik kümesi için bir tek yanıt parça döndürülür ve bu parça başarısız işlemle ilişkili durum kodu ve yanıt gövdesi içerir.

Aşağıdaki örnek yanıt hangi başarısız işlemleri birinde ayarlayın bir değişiklik içeren toplu istek gösterir. Toplu yanıt durum kodunu döndüren Not 202 kabul edilen. Değişiklik kümesini bir işlem durumuyla başarısız olduğunu gösteren için durum kodunu döndürdü 404 Bulunamadı. Ek hata bilgileri için başarısız olan işlemi yanıt gövdesi dahil edilir. Kod öğesi grafik API'si hata kodu belirtir ve ileti öğe hata ileti dizesi içeriyor. Bu örnekte, yanıt gövdesi için okunabilirlik girintili.

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

Başvuru için aşağıdaki örnek yukarıdaki yanıtını toplu gösterir. Üç kullanıcıların bir gruba ekleyen tek bir değişiklik kümesi içerir. Son iki kullanıcılar için nesne kimlikleri kurgusal: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee ve ffffffff-ffff-ffff-ffff-ffffffffffff. Toplu URL ve ilişkili istek üstbilgileri okumanızdır göz ardı edilir.

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

Share via