批次處理 |Graph API 概念

發行項
2021/10/21

Azure AD 圖形 API 可讓您整批處理實體上的作業，以減少返往伺服器的次數。批次處理要求可降低網路負荷，更快速完成您的作業。

重要

我們強烈建議您使用 Microsoft Graph 來存取 Azure Active Directory 資源，而不是使用 Azure AD Graph API。我們目前致力於開發 Microsoft Graph，對於 Azure AD Graph API 則沒有進一步增強的計劃。Azure AD Graph API 仍適用於非常少數的案例；如需詳細資訊，請參閱 Office 開發人員中心的 Microsoft Graph 或 Azure AD Graph (英文) 部落格文章。請注意，Microsoft Graph 目前不支援批次處理，您必須使用 Azure AD Graph API 來取得這項功能。

OData 批次要求的 Graph API 支援

實體批次處理的語意由 OData 3.0 批次處理規格所定義。 OData 規格定義下面批次要求的概念：

查詢是單一查詢或函數引動。
變更集是一或多組的插入、更新/刪除作業、動作引動或服務引動。
批次是作業的容器，包含一或多個變更集和查詢作業。

圖形 API 支援由 OData 規格所定義的功能子集：

單一批次最多可包含相加起來五個查詢和/或變更集。
一個變更集最多可包含一個來源物件修改，以及相加起來最多 20 個新增連結和刪除連結作業。變更集的所有作業必須在單一來源實體上。

Graph API 批次要求

下列各節說明如何建構批次要求以及如何解譯批次回應，並分別提供一個示範。

批次要求語法

若要執行批次要求，請在要求 URI 中指定 $batch 選項。例如：

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

批次要求使用單一 POST 指示詞傳送至伺服器。

裝載是含有批次及其構成查詢和變更集的多重部分 MIME 訊息。裝載包含兩種 MIME 界限：

批次界限分隔批次中的每個查詢和/或變更集。
變更集界限分隔變更集內的個別作業。

變更集內的個別要求與呼叫作業本身時所提出的要求相同。例如：

若要對變更集的每個作業指定裝載格式 (JSON 或 ATOM)，請包括適當的內容類型和 (如有需要) Accept 標頭。
若要在建立實體時隱藏回應內容回應，請指定 Prefer 標頭，並為變更集中每項插入作業指定未傳回內容值。

範例要求

下列範例顯示包含五個項目的批次要求：

變更集：建立使用者 testuser@contoso.onmicrosoft.com (POST)。此作業包含 Prefer: response-no-content 標頭來隱藏傳回的新建立使用者。
變更集：更新新使用者的「部門」和「職稱」屬性 (PATCH)，並設定其 manager 導覽屬性 (PUT)。
查詢：新使用者的經理 (GET)。
變更集：刪除新的使用者 (DELETE)。
查詢：使用者 (GET)。此作業會失敗，因為上一步中已刪除使用者。

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

批次回應語法

回應會傳回批次要求的整體狀態碼，以及批次中每個項目的個別狀態碼和結果片段。回應是含有批次界限和變更集界限的多重部分 MIME 訊息。

假設批次要求已經正確地驗證，且 Graph API 已順利收到此要求，即使批次中的其中一項作業失敗，批次要求還是會傳回狀態碼 202 已接受。如果批次要求本身為失敗，那麼在執行批次中的任何作業之前便會失敗。例如，批次要求可能會由於驗證錯誤而失敗，在此情況下，狀態碼會指出該失敗。

查詢項目的回應片段包含單一狀態碼，指出作業成功或失敗，以及任何適當的回應內文。

變更集中的作業會以不可分割方式處理，換句話說，若不是變更集中的所有作業成功，就是整個變更集失敗。圖形 API 會繼續處理變更集中的作業，直到其中一項作業失敗為止。如果作業失敗，變更集中先前執行的所有作業都會回復。

如果成功處理變更集中的所有作業，則變更集內每項作業的狀態碼 (和回應內文) 會出現在變更集回應內。如果變更集中的某項作業失敗，則變更集只會傳回單一狀態碼。這將是失敗作業所傳回的狀態碼 (和回應內文)；例如 400 錯誤的要求 或 404 找不到。

範例回應

下列範例顯示針對上述範例要求中所傳送之批次作業的回應。批次要求本身的狀態會設為 202 已接受。這表示批次要求本身沒有問題。對批次中每個項目的回應以 batchresponse 界限識別碼分隔，而對變更集內某項作業的每個回應以 changesetresponse 界限識別碼分隔。

以下列出每個批次項目的回應片段：

將建立新使用者 POST 要求的狀態設為 204 沒有內容。這是因為要求中的 Prefer 標頭已設為 return-no-content。這表示已順利建立使用者。
第二個批次項目的回應包含兩個 204 沒有內容* 回應，其中一個是關於使用者物件更新 (PATCH)，另一個是關於在變更集中設定管理員連結 (PUT)。這表示兩個作業都順利完成。
要求讀取使用者之管理員的回應傳回管理員的連結和狀態 200 確定。
嘗試刪除使用者的狀態是 204 沒有內容。這表示作業順利完成。
嘗試讀取已刪除之使用者的狀態是 404 找不到，而回應包含代碼和指出找不到使用者 (資源) 的訊息。

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

範例錯誤回應

如上所述，Graph API 可接受整個批次時，將會傳回錯誤碼 202 已接受。也就是說，批次要求的格式正確且沒有錯誤，例如驗證錯誤。否則，圖形 API 會傳回適當的錯誤，且不會處理批次。如果批次內的某個項目失敗，則該項目的回應片段將包含狀態碼和指出錯誤的回應內容。當變更集內的作業失敗時，整個變更集會傳回單一回應片段，而該片段包含失敗作業相關的狀態碼和回應內文。

下列範例顯示包含變更集 (其中一項作業失敗) 的批次要求的回應。請注意，批次回應傳回狀態碼 202 已接受。變更集傳回的狀態碼指出作業失敗，狀態為 404 找不到。其他錯誤資訊會包含在失敗作業的回應主體中。代碼元素指定 Graph API 錯誤碼，訊息元素包含錯誤訊息字串。在此範例中，回應內容已縮排，更易閱讀。

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

下列範例顯示產生上述回應的批次，供您參考。其中包含將三個使用者加入至群組的單一變更集。最後兩個使用者的物件識別碼是虛構的︰eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee 和 ffffffff-ffff-ffff-ffff-ffffffffffff。為求簡單明瞭，已省略批次 URL 和相關的要求標頭。

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

共用方式為