Combinar várias solicitações HTTP usando lotes JSON

O envio em lote JSON permite que os clientes combinem várias solicitações em um único objeto JSON e uma única chamada HTTP, reduzindo as viagens de ida e volta da rede e melhorando a eficiência. O Microsoft Graph dá suporte ao envio em lote de até 20 solicitações no objeto JSON.

Neste artigo, exploramos os conceitos básicos do envio em lote JSON, como ele funciona e como você pode usá-lo para otimizar seus aplicativos.

Observação

O Microsoft Graph implementa o segmento de caminho da $batchURL OData para dar suporte ao envio em lote JSON.

Cenário de exemplo

Considere um cliente que deseja compor uma exibição 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 uma solicitação em lote

Para criar uma solicitação em lote:

Especifique o método HTTP de solicitação como POST.
Especifique o ponto de extremidade da URL, se ele é direcionado à v1.0 versão ou beta ao Microsoft Graph, e anexe o $batch segmento à URL. Ou seja, https://graph.microsoft.com/v1.0/$batch.

Defina o corpo da solicitação em lote da seguinte maneira:

Um corpo de solicitação em lote JSON consiste em um único objeto JSON com uma propriedade necessária: solicitações. Esta propriedade é uma coleção de solicitações individuais.
Para cada solicitação individual, as propriedades a seguir podem ser passadas.

Propriedade	Descrição
id	Obrigatório. Cadeia de caracteres. Um valor de correlação para associar respostas individuais a solicitações. Esse valor permite que o servidor processe solicitações no lote na ordem mais eficiente. Não diferencia maiúsculas de minúsculas. Deve ser exclusivo no lote, caso contrário, a solicitação em lote falhará com um código de `400` erro.
method	Obrigatório. O método HTTP com suporte para a solicitação especificada na URL.
url	Obrigatório. A URL do recurso relativa para a solicitação 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 em URL64 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 solicitação em lote JSON

Neste cenário de exemplo, você constrói a solicitação em lote JSON. As solicitações individuais não são interdependentes e, portanto, podem ser colocadas na solicitação em lote em qualquer ordem.

HTTP
JavaScript

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"
      }
    }
  ]
}


const options = {
	authProvider,
};

const client = Client.init(options);

const $batch = {
  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'
      }
    }
  ]
};

await client.api('/$batch')
	.post($batch);

Leia a documentação do SDK para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider .

Processando a resposta em lote JSON

O formato de resposta para solicitações em lote JSON difere do formato de solicitação da seguinte maneira:

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 usada para correlacionar solicitações 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 de status HTTP.
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 em lote não indica que as solicitações individuais dentro do lote foram bem-sucedidas. É por isso que cada resposta individual na propriedade responses tem um código de status.

Exemplo de resposta em lote JSON

Para o exemplo anterior, suponha 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 de respostas individuais no exemplo de resposta em lote

As solicitações 1 e 5 foram bem-sucedidas, conforme mostrado pelo código de 200 status.
As solicitações 2 e 3 falharam com um 403 código de status porque o chamador não tinha as permissões necessárias.
A solicitação 4 falhou com um 405 código de status porque o ponto de extremidade especificado na propriedade url da solicitação está atualmente em beta apenas agora; a URL da solicitação tem como destino o v1.0 ponto de extremidade do Microsoft Graph. Embora a URL de destino não exija um corpo de solicitação, você ainda deve especificar os cabeçalhos e os parâmetros de corpo em que apenas o corpo pode ser um objeto vazio.

Solicitações de sequenciamento com a propriedade dependsOn

Você pode especificar as solicitações no lote a serem executadas em uma ordem especificada usando a propriedade dependsOn . Esta propriedade é uma matriz de cadeias de caracteres que faz referência à ID de uma solicitação individual diferente. Por exemplo, na solicitação a seguir, o cliente está especificando que as solicitações devem ser executadas na solicitação de pedido 1, na solicitação 2, na solicitação 4 e na solicitação 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 uso para envio em lote JSON é contornar as limitações de comprimento da URL. Nos casos em que a cláusula de filtro é complexa, o comprimento da URL pode superar as limitações internas em navegadores ou outros clientes HTTP. Você pode usar o envio em lote JSON como uma solução alternativa para executar essas solicitações porque a URL longa simplesmente se torna parte do conteúdo da solicitação.

Limitações de tamanho do lote

No momento, as solicitações de lote JSON estão limitadas a 20 solicitações individuais.
Dependendo das APIs que fazem parte da solicitação em lote, os serviços subjacentes impõem seus próprios limites de limitação que afetam os aplicativos que usam o Microsoft Graph para acessá-los.
As solicitações em um lote são avaliadas individualmente em relação aos limites de limitação aplicáveis e, se alguma solicitação exceder os limites, ela falhará 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.

Usar os SDKs do Microsoft Graph para solicitações em lote

Comentários

Esta página foi útil?

Last updated on 2026-08-21