Compartilhar via

Processamento em lotes | Conceitos da API do Graph

  • Artigo

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

Com a Graph API do AD do Azure, é possível enviar em lote as operações em entidades para reduzir as idas e voltas ao servidor. O envio em lote das suas solicitações reduz a sobrecarga da rede e as operações serão concluídas mais rapidamente.

Importante

Recomendamos que você use o Microsoft Graph em vez da API do Azure AD Graph para acessar os recursos do Azure Active Directory. Nossos esforços de implantação agora estão concentrados no Microsoft Graph e não há planos de novos aprimoramento para a API do Azure AD Graph. Há um número muito limitado de cenários para os quais a API do Azure AD Graph ainda pode ser adequada. Para saber mais, confira a postagem do blog sobre Microsoft Graph ou Azure AD Graph no Centro de Desenvolvimento do Office. Observe que o processamento em lotes atualmente não tem suporte no Microsoft Graph; você precisará usar a API do Azure AD Graph para esse recurso.

Suporte da API do Graph para solicitações em lote de OData

A semântica para processamento em lote de entidades é definida pela Especificação de Processamento em Lote do OData 3.0. A especificação OData define os seguintes conceitos para solicitações em lote:

  • Uma consulta é uma invocação de função ou consulta única.
  • Um conjunto de alterações é um grupo de uma ou mais operações de inserção, atualização, exclusão, invocações de ação ou invocações de serviço.
  • Um lote é um contêiner de operações, incluindo um ou mais conjuntos de alterações ou operações de consulta.

A Graph API dá suporte a um subconjunto da funcionalidade definida pela especificação OData:

  • Um único lote pode conter no máximo cinco conjuntos de alterações e/ou consultas combinados.
  • Um conjunto de alterações pode conter no máximo uma modificação de objeto de origem e até 20 operações de adição e exclusão de links combinadas. Todas as operações no conjunto de alterações devem estar em uma entidade de origem única.

Solicitações em lote da API do Graph

As seções a seguir descrevem como construir uma solicitação em lote, como interpretar a resposta em lote e exemplos de apresentação de cada uma.

Sintaxe da solicitação em lote

Para executar uma solicitação em lote, especifique a opção $lote no URI de solicitação. Por exemplo:

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

Uma solicitação em lote é enviada ao servidor com uma única diretiva POST.

A carga é uma mensagem MIME de várias partes que contém o lote e suas consultas constituintes e os conjuntos de alterações. A carga inclui dois tipos de limites de MIME:

  • Um limite de lote separa cada conjunto de alteração e/ou consulta no lote.
  • Um limite de conjunto de alterações separa as operações individuais em um conjunto de alterações.

Uma solicitação individual em um conjunto de alterações é idêntica a uma solicitação feita quando essa operação é chamada por si mesma. Por exemplo:

  • Para especificar o formato de carga (JSON ou ATOM) para cada operação no conjunto de alterações, inclua Content-Type apropriado e, se necessário, cabeçalhos Accept.
  • Para suprimir o eco de conteúdo da resposta ao criar uma entidade, especifique o cabeçalho Prefer com o valor return-no-content para cada operação de inserção em um conjunto de alterações.

Solicitação de amostra

O exemplo a seguir mostra uma solicitação em lote que contém cinco itens:

  1. Um conjunto de alterações que cria um usuário, testuser@contoso.onmicrosoft.com (POST). Essa operação inclui o cabeçalho Prefer: response-no-content para suprimir o usuário recém-criado que está sendo retornado.
  2. Um conjunto de alterações que atualiza as propriedades Cargo e Departamento do novo usuário (PATCH) e define sua propriedade de navegação do gerenciador (PUT).
  3. Uma consulta para o gerenciador do novo usuário (GET).
  4. Um conjunto de alterações que exclui o novo usuário (DELETE).
  5. Uma consulta para o usuário (GET). Esta operação falhará porque o usuário foi excluído na etapa 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 da resposta em lote

A resposta retorna um código de status geral para a solicitação em lote, e códigos de status individuais e fragmentos de resultados para cada item no lote. A resposta é uma mensagem MIME de várias partes que inclui limites de lote e limites de conjunto de alterações.

Supondo que a solicitação em lote tenha sido autenticada corretamente e recebida com êxito pela API do Graph, a solicitação de lote retorna o código de status 202 Accepted, mesmo que uma das operações no lote falhe. Se a solicitação em lote falhar, isso acontecerá antes de qualquer operação no lote ser executada. Por exemplo, a solicitação em lote pode falhar devido a um erro de autenticação, nesse caso, o código de status indicará essa falha.

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

As operações em um conjunto de alterações são processadas de forma atômica; ou seja, todas as operações no conjunto de alterações são bem-sucedidas ou todo o conjunto de alterações falha. A Graph API continua processando operações no conjunto de alterações até uma delas falhar. Se uma operação falhar, todas as operações anteriores no conjunto de alterações serão revertidas.

Se todas as operações em um conjunto de alterações forem processadas com êxito, o código de status (e o corpo de resposta) para cada operação no conjunto de alterações é exibido na resposta do conjunto de alterações. Se uma operação em um conjunto de alterações falhar, um código de status único é retornado para o conjunto de alterações. Este será o código de status (e o corpo de resposta) retornado pela operação com falha; por exemplo, 400 Solicitação Incorreta ou 404 Não Encontrado.

Resposta de amostra

O exemplo a seguir mostra a resposta para operação em lote enviada na solicitação de exemplo mostrada acima. O status da solicitação em lote é definido como 202 Aceito. Isso indica que não há problemas com a solicitação em lote em si. A resposta para cada item no lote é delimitada com o identificador de limite batchresponse e cada resposta a uma operação em um conjunto de alterações é delimitada por um identificador de limite changesetresponse.

Veja a seguir os fragmentos de resposta para cada item de lote:

  1. O status para a solicitação POST para criar o novo usuário é definido como 204 Sem Conteúdo. Isso ocorre porque o cabeçalho Prefer foi definido como return-no-content na solicitação. Ele indica que o usuário foi criado com êxito.
  2. A resposta para o segundo item de lote contém duas respostas 204 Sem Conteúdo, uma para a atualização do objeto de usuário (PATCH) e outra para configurar o link gerenciador (PUT) no conjunto de alterações. Isso indica que as duas operações foram bem-sucedidas.
  3. A resposta para a solicitação ler o gerenciador de usuário retorna o link para o gerente e um status de 200 OK.
  4. O status de tentativa de excluir o usuário é 204 Sem Conteúdo. Isso indica que a operação foi bem-sucedida
  5. O status de tentativa de leitura do usuário excluído é 404 Não Encontrado e a resposta contém um código e uma mensagem que indica que o usuário (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

Como discutido acima, a API do Graph retornará um código de erro 202 Accepted para todo o lote, se puder aceitar o lote; ou seja, se a solicitação em lote estiver bem formada e não houver erros, como um erro de autenticação. Caso contrário, a Graph API retorna o erro adequado e não processa o lote. Se um item individual dentro do lote falhar, o fragmento de resposta para aquele item conterá um corpo da resposta e o código de status que indica um erro. Quando uma operação dentro de um conjunto de alteração falhar, um único fragmento de resposta será retornado para o conjunto de alterações inteiro e esse fragmento conterá o corpo de resposta e o código de status associados à operação com falha.

O exemplo a seguir mostra uma resposta da solicitação em lote que contém um conjunto de alterações em que uma das operações falhou. Observe que a resposta em lote retorna o código de status 202 Aceito. O código de status retornado para o conjunto de alterações indica que uma operação falhou com um status de 404 Não Encontrado. Outras informações de erro são incluídas no corpo da resposta para a operação com falha. O elemento code especifica o código de erro da API do Graph e o elemento message contém a cadeia de caracteres da mensagem de erro. Neste exemplo, o corpo da resposta foi recuado para facilitar a leitura.

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 a seguir mostra o lote que gerou a resposta acima. Ele contém um único conjunto de alterações que adiciona três usuários a um grupo. As IDs de Objetos para os últimos dois usuários são fictícias: eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee e ffffffff-ffff-ffff-ffff-ffffffffffff. A URL de lote e os cabeçalhos de solicitação associados são omitidos para fins de brevidade.

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