Пакетная обработка | Общие понятия API Graph

Статья
21.10.2021

API Graph для Azure AD позволяет выполнять пакетные операции с сущностями, снижающие количество обращений к серверу. Объединение запросов в пакеты снижает нагрузку на сеть и ускоряет выполнение операций.

Важно!

Для доступа к ресурсам Azure Active Directory мы настоятельно рекомендуем использовать Microsoft Graph вместо API Azure AD Graph.Теперь наши усилия сфокусированы на разработке Microsoft Graph; дальнейшее продвижение API Azure AD Graph мы не планируем.Есть очень мало сценариев, в которых по-прежнему можно использовать API Azure AD Graph. Дополнительные сведения об этом см. в записи блога в центре разработчиков Office, где сравниваются решения Microsoft Graph и Azure AD Graph.Обратите внимание на то, что в настоящее время Microsoft Graph не поддерживает пакетную обработку; для работы с этой функцией необходимо использовать API Graph Azure AD.

Поддержка API Graph для пакетных запросов OData

Семантика для пакетной обработки сущностей определяется спецификацией пакетной обработки OData 3.0. Спецификация протокола OData определяет следующие понятия для пакетных запросов.

Под запросом понимается одиночный запрос или вызов функции.
Набор изменений — это группа из одной или нескольких операций вставки, обновления или удаления, вызовов действий или служб.
Пакет — это контейнер операций, содержащий один или несколько наборов изменений и операций запросов.

API Graph поддерживает подмножество функциональных возможностей, определенных в спецификации протокола OData.

Общее количество запросов и наборов изменений в одном пакете не может превышать пяти.
Набор изменений может содержать не более одного изменения исходного объекта и в сумме до 20 операций добавления и удаления ссылки. Все операции в наборе изменений должны применяться к одной исходной сущности.

Пакетные запросы API Graph

В следующих разделах приведены инструкции по созданию пакетных запросов и интерпретации пакетных ответов, а также примеры обеих операций.

Синтаксис пакетного запроса

Для выполнения пакетного запроса задайте параметр $batch в коде URI запроса. Пример.

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

Пакетный запрос отправляется на сервер в одной директиве POST.

Полезные данные представляют собой сообщение MIME из нескольких частей, содержащее пакет и его составляющие — запросы и наборы изменений. Полезные данные включают в себя границы MIME двух типов.

Граница пакета отделяет каждый запрос и/или набор изменений в пакете.
Граница набора изменений разделяет отдельные операции в наборе изменений.

Отдельный запрос в наборе изменений совпадает с запросом, который выполняется при прямом вызове операции. Пример.

Для назначения формата полезных данных (JSON или ATOM) каждой операции в наборе изменений включите подходящие заголовки Content-Type и при необходимости Accept.
Если при создании сущности требуется запретить вывод на экран содержимого ответа, задайте заголовок Prefer со значением return-no-content для каждой операции вставки в наборе изменений.

Пример запроса

В следующем примере показан пакетный запрос из пяти элементов.

Набор изменений, обеспечивающий создание пользователя: testuser@contoso.onmicrosoft.com (POST). В эту операцию включен заголовок Prefer: response-no-content для запрета возврата только что созданного пользователя.
Набор изменений, обеспечивающий обновление свойств нового пользователя "Отдел" и "Должность" (PATCH) и назначение его руководителю свойства навигации (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-сообщение, содержащее границу пакета и границу набора изменений.

Если пакетный запрос прошел проверку подлинности и успешно принят службами API Graph, он возвращает код состояния 202 Accepted даже в случае сбоя одной из операций в пакете. Сбой пакетного запроса всегда предшествует выполнению любой операции в пакете. Например, пакетный запрос может завершиться неудачно из-за ошибки проверки подлинности, в таком случае будет возвращен соответствующий код состояния.

Фрагмент ответа для элемента запроса содержит один код состояния, указывающий на успешное выполнение или сбой операции, а также соответствующий текст ответа.

Операции в наборе изменений обрабатываются нераздельно: это означает, что либо все операции в наборе изменений выполняются успешно, либо происходит сбой набора изменений в целом. Обработка операции в наборе изменений службами API Graph продолжается до первого сбоя. Сбой одной из операций вызывает откат всех предшествующих операций в наборе изменений.

Если все операции в наборе изменений обработаны успешно, в ответ набора изменений включается код состояния (и текст ответа) для каждой операции в наборе изменений. В случае сбоя одной из операций в наборе изменений для этого набора возвращается только один код состояния. Это код состояния (и текст ответа), возвращаемый сбойной операцией; например 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--

Пример ответа с ошибкой

Как указано выше, API Graph возвращает код ошибки 202 — Принято для пакета в целом: это означает, что пакет представлен в правильном формате и не содержит ошибок, например ошибки проверки подлинности. В противном случае API Graph возвращает соответствующее сообщение об ошибке, а пакет не обрабатывается. При сбое отдельного элемента в пакете фрагмент ответа для этого элемента содержит код состояния и текст ответа, указывающий на ошибку. При сбое операции внутри набора изменений для всего этого набора возвращается один фрагмент ответа, который содержит код состояния и текст ответа, связанный со сбойной операцией.

В следующем примере показан ответ на пакетный запрос, содержащий набор изменений, в котором произошел сбой одной из операций. Обратите внимание на то, что ответ на пакет возвращает код состояния 202 — Принято. Код состояния, возвращенный для набора изменений, указывает на сбой операции с состоянием 404 — Объект не найден. Дополнительные сведения об ошибках включены в текст ответа, относящийся к сбойной операции. Элемент code указывает код ошибки API Graph, а элемент message содержит строку сообщения об ошибке. В этом примере текст ответа показан с отступами для удобства чтения.

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