Partilhar via

Processamento de batches | Conceitos da Graph API

  • Artigo

Aplica-se a: Graph API | Azure Active Directory (AD)

Com o AD Graph API do Azure, pode batch operações em entidades para reduzir e voltas para o servidor. Os pedidos de criação de batches reduz a sobrecarga de rede e as operações de concluirá mais rapidamente.

Importante

Recomendamos vivamente que utilize Microsoft Graph em vez do AD Graph API do Azure para aceder aos recursos do Azure Active Directory. A nossa esforços de desenvolvimento são agora concentrated no Microsoft Graph e estão a ser planeados sem melhoramentos adicionais para AD Graph API do Azure. Existem um número muito limitado de cenários para o qual AD Graph API do Azure ainda poderá ser apropriado; Para obter mais informações, consulte o Microsoft Graph ou o Azure AD Graph blogue no Dev Center do Office. Tenha em atenção que processamento em lote não é atualmente suportado no Microsoft Graph; terá de utilizar o Azure AD Graph API para esta funcionalidade.

Suporte de Graph API para pedidos de batch de OData

A semântica para processamento de batches de entidade é definida pelo Batch processamento especificação do OData 3.0. A especificação do OData define os seguintes conceitos para pedidos de batch:

  • Uma consulta é uma invocação de consulta ou uma função única.
  • Um conjunto de alterações é um grupo de um ou mais inserem, atualizar ou eliminar de operações, invocações de ação ou invocações de serviço.
  • Um batch é um contentor de operações, incluindo um ou mais conjuntos de alterações e operações de consulta.

A Graph API suporta um subconjunto da funcionalidade definida pela especificação do OData:

  • Um único lote pode conter um máximo de cinco consultas e/ou alterar conjuntos combinados.
  • Um conjunto de alterações pode conter um máximo de modificação do objeto de uma origem e até 20 operações de ligação Adicionar e eliminar a associação combinadas. Todas as operações no conjunto de alterações tem de ser uma entidade de origem única.

Pedidos de batch da Graph API

As secções seguintes descrevem como construir um pedido de batch, como interpretar a resposta de lote e Mostrar amostras de cada.

Sintaxe do pedido de batch

Para efetuar um pedido de batch, especifique a opção de $batch no URI do pedido. Por exemplo:

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

É enviado um pedido de batch para o servidor com uma diretiva POST único.

O payload é uma mensagem MIME com várias parte, que contém o batch e respetivas consultas constituintes e conjuntos de alterações. O payload inclui dois tipos de limites MIME:

  • Um limite de batch separa cada conjunto de consulta e/ou a alteração no batch.
  • Um limite de conjunto de alterações separa operações individuais dentro de um conjunto de alterações.

Um pedido individuais dentro de um conjunto de alterações é idêntico a um pedido efetuado quando essa operação é chamada por si só. Por exemplo:

  • Para especificar o formato de payload (JSON ou ATOM) para cada operação no conjunto de alterações, incluem o tipo de conteúdo adequado e, se necessário, aceita os cabeçalhos.
  • Para suprimir o eco de conteúdo de resposta ao criar uma entidade, especifique o cabeçalho de Prefer com o valor de retorno não-conteúdo para cada operação de inserção num conjunto de alterações.

Exemplo de pedido

O exemplo seguinte mostra um pedido de batch que contenha cinco itens:

  1. A alterar o conjunto que cria um utilizador, testuser@contoso.onmicrosoft.com (POST). Esta operação inclui a Prefer: cabeçalho de resposta não-conteúdo para suprimir o utilizador recentemente criado a ser devolvido.
  2. Um conjunto de alterações que atualiza as propriedades de departamento e cargo do utilizador novo (PATCH) e define a propriedade de navegação do Gestor (PUT).
  3. Uma consulta para o Gestor do utilizador novo (GET).
  4. Um conjunto de alterações que elimina o utilizador novo (DELETE).
  5. Uma consulta para o utilizador (GET). Esta operação irá falhar porque o utilizador foi eliminado no passo anterior.
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--

Sintaxe de resposta de batch

A resposta devolve um código de estado geral para o pedido de batch e códigos de estado individual e fragmentos de resultado para cada item no batch. A resposta é uma mensagem MIME com várias parte, que inclui os limites do batch e alteração definem limites.

Partindo do princípio que o pedido de batch ter sido corretamente autenticado e foi recebido com êxito pela Graph API, o pedido de batch devolve o código de estado aceites 202, mesmo se uma das operações no lote falha. Se o lote pedido próprio falhar, falhar antes de qualquer operação no lote é executada. Por exemplo, o pedido de batch poderão falhar devido a um erro de autenticação, em que, caso o código de estado irá indicar essa falha.

O fragmento de resposta para um item de consulta contém um código de estado único que indica o êxito ou falha da operação, bem como quaisquer corpo de resposta adequado.

As operações num conjunto de alterações são processadas atomically; ou seja, a todas as operações no conjunto de alteração com êxito ou falha de definir a alteração de toda. A Graph API continua operações de processamento em conjunto até que uma falha de alterações. Se uma operação falhar, todas as operações anteriores o conjunto de alterações são revertidas.

Se a todas as operações num conjunto de alterações com êxito são processados, o código de estado (e corpo da resposta) para cada operação dentro do conjunto de alteração aparece na resposta de conjunto de alterações. Se falhar uma operação num conjunto de alterações, é devolvido um código de estado único para o conjunto de alterações. Este será o código de estado (e corpo da resposta) devolvido pela operação de falha; Por exemplo, 400 incorretos pedem ou 404 não encontrado.

Resposta de amostra

O exemplo seguinte mostra a resposta para a operação de lotes enviada no pedido de exemplo mostrado acima. O estado para o pedido de batch em si é definido como aceites 202. Isto indica que não existe nenhum problemas com o lote pedem próprio. A resposta a cada item no lote é delimitada com o batchresponse identificador de limites e cada resposta a uma operação dentro de um conjunto de alterações é delimitada com um changesetresponse limites Identificador.

As designações seguintes fragmentos de resposta para cada item de lote:

  1. O estado para o pedido POST criar o novo utilizador é definido como 204 não conteúdo. Isto acontece porque o Prefer cabeçalho foi definido como return-no-content no pedido. Indica que o utilizador foi criado com êxito.
  2. A resposta para o segundo item de batch contém dois 204 não conteúdo respostas, uma para a atualização do objeto de utilizador (PATCH) e outra para definir a ligação de gestor (PUT) no conjunto de alterações. Isto indica que o se ambas as operações foram bem-sucedidas.
  3. A resposta para o pedido ler o Gestor do utilizador, devolve a ligação para o gestor e o estado de 200 OK.
  4. O estado para a tentativa de eliminar o utilizador, é 204 não conteúdo. Isto indica que a operação foi concluída com êxito
  5. O estado para a tentativa de leitura de utilizador eliminado, é 404 não encontrado e a resposta contém um código e a mensagem que indica que o utilizador (recurso) não foi encontrado.
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--

Resposta de erro de amostra

Conforme mencionado acima, a Graph API devolve um código de erro de aceites 202 para todo o lote se pode aceitar o lote; que seja, se o pedido de batch é bem formado e existirem erros, tais como um erro de autenticação. Caso contrário, a Graph API devolve o erro apropriada e não processa o batch. Se um item individuais num lote falhar o fragmento de resposta para que o item irá conter um corpo de código e a resposta de estado que indica que o erro. Quando uma operação no interior de uma alteração definido falhar, será devolvido um fragmento de resposta único para o conjunto de alterações todo e que fragmento irá conter o corpo de código e a resposta de estado associado a operação falhada.

O exemplo seguinte mostra uma resposta do pedido de batch que contenha um conjunto no qual das operações falhada de alterações. Tenha em atenção que a resposta de batch devolve o código de estado aceites 202. O código de estado devolvido para o conjunto de alterações indica que uma operação falhou com o estado 404 não encontrado. Informações de erro adicionais estão incluídas no corpo da resposta para a operação falhada. O código elemento Especifica o código de erro da Graph API e o mensagem elemento contém a cadeia de mensagem de erro. Neste exemplo, o corpo da resposta tem sido avanços para legibilidade.

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

Para referência, o exemplo seguinte mostra o lote que gerou a resposta acima. Contém um conjunto de única alteração que adiciona três utilizadores a um grupo. Os IDs de objeto para os dois últimos utilizadores são fictícios: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee e ffffffff-ffff-ffff-ffff-ffffffffffff. O URL de lote e cabeçalhos de pedido associada estão omitidos de uma forma abreviada.

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

Recursos adicionais