Combinar vários pedidos HTTP com a criação de batches JSON

  • Artigo

A criação de batches JSON permite-lhe otimizar a sua aplicação ao combinar vários pedidos (até 20) num único objeto JSON.

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.

O Microsoft Graph implementa o segmento de caminho do $batchURL do OData para suportar a criação de batches JSON.

Exemplo - Primeiro pedido de lote JSON

Em primeiro lugar, vai construir o pedido de lote JSON para o cenário de exemplo. Neste cenário, 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/drive/root:/{file}:/content"
    },
    {
      "id": "2",
      "method": "GET",
      "url": "/me/planner/tasks"
    },
    {
      "id": "3",
      "method": "GET",
      "url": "/groups/{id}/events"
    },
    {
      "id": "4",
      "url": "/me",
      "method": "PATCH",
      "body": {
        "city" : "Redmond"
      },
      "headers": {
        "Content-Type": "application/json"
      }
    },
    {
      "id": "5",
      "url": "users?$select=id,displayName,userPrincipalName&$filter=city eq null&$count=true",
      "method": "GET",
      "headers": {
        "ConsistencyLevel": "eventual"
      }
    }
  ]
}

Explicação de um formato de pedido em lote

As solicitações em lote são sempre enviadas usando um POST para o /$batch ponto de extremidade.

Um corpo de pedido em lote JSON consiste num único objeto JSON com uma propriedade necessária: pedidos. A propriedade requests é 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.
method Obrigatório. O método HTTP.
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 - Primeira resposta em lote JSON

As respostas para solicitações em lote podem aparecer em uma ordem diferente. A propriedade ID pode ser utilizada para correlacionar pedidos e respostas individuais.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "responses": [
    {
      "id": "1",
      "status": 302,
      "headers": {
        "location": "https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi"
      }
    },
    {
      "id": "3",
      "status": 401,
      "body": {
        "error": {
          "code": "Forbidden",
          "message": "..."
        }
      }
    },
    {
      "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/v1.0/$metadata#users(id,displayName,userPrincipalName)",
        "@odata.count": 12,
        "value": [
          {
            "id": "071cc716-8147-4397-a5ba-b2105951cc0b",
            "displayName": "Adele Vance",
            "userPrincipalName": "AdeleV@Contoso.com"
          }
        ]
      }
    },
    {
      "id": "2",
      "status": 200,
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
        "value": []
      }
    },
    {
      "id": "4",
      "status": 204,
      "body": null
    }
  ]
}

Explicação de um formato de resposta em lote

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.
  • Em vez do método e do URL, as respostas individuais têm uma propriedade de estado . O valor do estado é o código de estado 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 400. 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 estado 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 estado.

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 o estado .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.

Conteúdo relacionado