Combinar vários pedidos HTTP com a criação de batches JSON
A criação de batches JSON permite que os clientes combinem vários pedidos num único objeto JSON e numa única chamada HTTP, reduzindo as ida e voltas de rede e melhorando a eficiência. O Microsoft Graph suporta a criação de batches de até 20 pedidos no objeto JSON.
Neste artigo, vamos explorar as noções básicas do batching JSON, como funciona e como pode utilizá-lo para otimizar as suas aplicações.
Observação
O Microsoft Graph implementa o segmento de caminho do $batchURL do OData para suportar a criação de batches JSON.
Cenário de exemplo
Considere um cliente que pretenda compor uma vista dos seguintes dados não relacionados:
- Uma imagem armazenada no OneDrive
- Uma lista de tarefas de Planejador
- O calendário de um grupo
Combinar essas três solicitações individuais em uma única solicitação em lote pode economizar latência da rede significativa para o aplicativo.
Criar um pedido em lote
Para criar um pedido em lote:
Especifique o método HTTP do pedido como POST.
Especifique o ponto final do URL, quer se destina à
v1.0versão oubetado Microsoft Graph, e acrescente o$batchsegmento ao URL. Ou seja,https://graph.microsoft.com/v1.0/$batch.Defina o corpo do pedido em lote da seguinte forma:
- Um corpo de pedido em lote JSON consiste num único objeto JSON com uma propriedade necessária: pedidos. Esta propriedade é uma coleção de pedidos individuais.
- Para cada pedido individual, as seguintes propriedades podem ser transmitidas.
Propriedade Descrição id Obrigatório. Cadeia de caracteres. Um valor de correlação para associar respostas individuais a pedidos. Este valor permite ao servidor processar pedidos no lote pela ordem mais eficiente. Não sensível a maiúsculas e minúsculas. Tem de ser exclusivo no lote, caso contrário, o pedido do batch falha com um 400código de erro.method Obrigatório. O método HTTP suportado para o pedido especificado no URL. url Obrigatório. O URL do recurso relativo para o pedido individual. Portanto, enquanto o URL absoluto é https://graph.microsoft.com/v1.0/users, este URL é/users.cabeçalhos Opcional, mas obrigatório quando o corpo é especificado. Um objeto JSON com o par chave/valor para os cabeçalhos. Por exemplo, quando o cabeçalho ConsistencyLevel é necessário, esta propriedade é representada como "headers": {"ConsistencyLevel": "eventual"}. Quando o corpo é fornecido, um cabeçalho Content-Type deve ser incluído.corpo Opcional. Pode ser um objeto JSON ou um valor codificado com URL base64, por exemplo, quando o corpo é uma imagem. Quando um corpo é incluído na solicitação, o objeto cabeçalhos deve conter um valor para Content-Type.
Exemplo de pedido em lote JSON
Neste cenário de exemplo, vai construir o pedido de lote JSON. Os pedidos individuais não são interdependentes e, por conseguinte, podem ser colocados no pedido de lote por qualquer ordem.
POST https://graph.microsoft.com/v1.0/$batch
Accept: application/json
Content-Type: application/json
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "/me/memberOf"
},
{
"id": "2",
"method": "GET",
"url": "/me/planner/tasks"
},
{
"id": "3",
"method": "DELETE",
"url": "/groups/0e226165-c685-41ce-8bfc-df8360ab325d"
},
{
"id": "4",
"url": "/users/161ab652-cdbc-490d-82a4-0ada1f0db247/getPasswordSingleSignOnCredentials",
"method": "POST",
"body": {},
"headers": {"Content-Type": "application/json"}
},
{
"id": "5",
"url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
"method": "GET",
"headers": {
"ConsistencyLevel": "eventual"
}
}
]
}
Processar a resposta do lote JSON
O formato de resposta para pedidos em lote JSON difere do formato do pedido da seguinte forma:
- A propriedade no objeto principal do JSON é nomeada respostas em oposição a solicitações.
- As respostas individuais podem aparecer em uma ordem diferente das solicitações. A propriedade ID pode ser utilizada para correlacionar pedidos e respostas individuais.
- Em vez de método e URL, as respostas individuais têm uma propriedade status. O valor de status é o código http status.
- A propriedade cabeçalhos em cada resposta individual representa os cabeçalhos devolvidos pelo servidor, por exemplo, cabeçalhos de Cache-Control e Content-Type.
O código de status em uma resposta de lote geralmente é 200 ou 4xx. Se a solicitação de lote em si for mal formada, o código de status será 400. Se a solicitação de lote for analisável, o código de status será 200. Um 200 código de status nos cabeçalhos de resposta do batch não indica que os pedidos individuais dentro do lote foram bem-sucedidos. É por isso que cada resposta individual na propriedade responses (respostas) tem um código de status.
Exemplo de resposta em lote JSON
Para o exemplo anterior, suponhamos esta resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"responses": [
{
"id": "1",
"status": 200,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"OData-Version": "4.0",
"Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
},
"body": {
"@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
"@odata.nextLink": "https://graph.microsoft.com/beta/me/memberOf?$top=1&$skiptoken=RFNwdAoAAQAAAAAAAAAAFAAAAI45VMy0CO9Ei1L3Lr1q95UBAAAAAAAAAAAAAAAAAAAXMS4yLjg0MC4xMTM1NTYuMS40LjIzMzEGAAAAAAABURXWGePFEEGbudEn3SOTuQEDAQAAAQAAAAA",
"value": [
{
"@odata.type": "#microsoft.graph.directoryRole",
"id": "21004afc-7bb2-4fe6-a1e1-074ebd3e52c1",
"deletedDateTime": null,
"description": "Can manage all aspects of users and groups, including resetting passwords for limited admins.",
"displayName": "User Administrator",
"roleTemplateId": "fe930be7-5e62-47db-91af-98c3a49a38b1"
}
]
}
},
{
"id": "2",
"status": 403,
"headers": {
"Cache-Control": "no-cache",
"X-ProxyCluster": "wus-001.tasks.osi.office.net",
"X-OfficeCluster": "wus-001.tasks.osi.office.net",
"X-Tasks-CorrelationId": "18a8e521-78a4-4129-9b6b-d678116464e7",
"Content-Type": "application/json"
},
"body": {
"error": {
"code": "",
"message": "You do not have the required permissions to access this item.",
"innerError": {
"date": "2025-02-13T10:17:05",
"request-id": "93b6f17e-c05d-4f45-ad2a-6665c708d8a0",
"client-request-id": "e70c5c1b-8b47-68c0-3171-3d22f5e0bd54"
}
}
}
},
{
"id": "3",
"status": 403,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"Content-Type": "application/json"
},
"body": {
"error": {
"code": "Authorization_RequestDenied",
"message": "Insufficient privileges to complete the operation.",
"innerError": {
"date": "2025-02-13T10:17:06",
"request-id": "93b6f17e-c05d-4f45-ad2a-6665c708d8a0",
"client-request-id": "e70c5c1b-8b47-68c0-3171-3d22f5e0bd54"
}
}
}
},
{
"id": "4",
"status": 405,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"Content-Type": "application/json"
},
"body": {
"error": {
"code": "Request_BadRequest",
"message": "Specified HTTP method is not allowed for the request target.",
"innerError": {
"date": "2025-02-13T10:21:18",
"request-id": "3a3b1bf7-3596-4493-8264-de81e028071f",
"client-request-id": "e5f9a304-2796-b7e8-ccce-dd989953ebc4"
}
}
}
},
{
"id": "5",
"status": 200,
"headers": {
"Cache-Control": "no-cache",
"x-ms-resource-unit": "1",
"OData-Version": "4.0",
"Content-Type": "application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8"
},
"body": {
"@odata.context": "https://graph.microsoft.com/beta/$metadata#users(id,displayName,userPrincipalName)",
"@odata.count": 36,
"value": [
{
"id": "10a1d484-cd1a-4162-a5a4-832370bac356",
"displayName": "Lynne Robbins",
"userPrincipalName": "LynneR@contoso.com"
}
]
}
}
]
}
Explicação das respostas individuais na resposta do batch de exemplo
- Os pedidos 1 e 5 foram bem-sucedidos, conforme mostrado pelo
200código de status. - Os pedidos 2 e 3 falharam com um
403código de status porque o autor da chamada não tinha as permissões necessárias. - O pedido 4 falhou com um
405código de status porque o ponto final especificado na propriedade url do pedido está atualmente apenas nobetaurl do pedido que visa ov1.0ponto final do Microsoft Graph. Embora o URL de destino não necessite de um corpo do pedido, ainda tem de especificar os cabeçalhos e parâmetros do corpo em que apenas o corpo pode ser um objeto vazio.
Solicitações de sequenciamento com a propriedade dependsOn
Pode especificar os pedidos no lote a serem executados por uma ordem especificada através da propriedade dependsOn . Esta propriedade é uma matriz de cadeias que referencia o ID de um pedido individual diferente. Por exemplo, no pedido seguinte, o cliente está a especificar que os pedidos devem ser executados no pedido de encomenda 1 e, em seguida, o pedido 2, o pedido 4 e, em seguida, o pedido 3.
{
"requests": [
{
"id": "1",
"method": "GET",
"url": "..."
},
{
"id": "2",
"dependsOn": [ "1" ],
"method": "GET",
"url": "..."
},
{
"id": "4",
"dependsOn": [ "2" ],
"method": "GET",
"url": "..."
},
{
"id": "3",
"dependsOn": [ "4" ],
"method": "GET",
"url": "..."
}
]
}
Se uma solicitação individual falhar, qualquer solicitação que dependa dessa solicitação falhará com código de status 424 (dependência com falha).
Dica
O lote deve ser totalmente sequencial ou totalmente paralelo.
Ignorar limitações de tamanho de URL com processamento em lotes
Outro caso de utilização da criação de batches JSON é ignorar as limitações de comprimento do URL. Nos casos em que a cláusula de filtro é complexa, o comprimento do URL pode ultrapassar as limitações incorporadas nos browsers ou noutros clientes HTTP. Pode utilizar a criação de batches JSON como solução para executar estes pedidos, porque o URL longo torna-se simplesmente parte do payload do pedido.
Limitações de tamanho do lote
- No momento, as solicitações de lote JSON estão limitadas a 20 solicitações individuais.
- Consoante as APIs que fazem parte do pedido de lote, os serviços subjacentes impõem os seus próprios limites de limitação que afetam as aplicações que utilizam o Microsoft Graph para aceder aos mesmos.
- Os pedidos num lote são avaliados individualmente relativamente aos limites de limitação aplicáveis e, se um pedido exceder os limites, falha com um status de
429.
Para obter mais informações, confira Limitação e envio em lote.
Problemas conhecidos
Para obter uma lista de limitações atuais relacionadas a lotes, veja problemas conhecidos.