Combinar várias solicitações HTTP usando o lote JSON
O lote JSON permite otimizar seu aplicativo combinando várias solicitações (até 20) em um único objeto JSON.
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.
O Microsoft Graph implementa o segmento de caminho da URL do$batch OData para dar suporte ao lote JSON.
Exemplo – Primeira solicitação de lote JSON
Primeiro, você constrói a solicitação de lote JSON para o cenário de exemplo. Nesse cenário, as solicitações individuais não são interdependentes e, portanto, podem ser colocadas na solicitação do lote em 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 solicitação em lote
As solicitações em lote são sempre enviadas usando um POST para o /$batch ponto de extremidade.
Um corpo de solicitação de lote JSON consiste em um único objeto JSON com uma propriedade necessária: solicitações. A propriedade requests é 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 é sensível a casos. Deve ser exclusivo no lote. |
| method | Obrigatório. O método HTTP. |
| url | Obrigatório. A URL de recurso relativo 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, essa 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 por 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 do lote JSON
As respostas para solicitações em lote podem aparecer em uma ordem diferente. A propriedade ID pode ser usada para correlacionar solicitações 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 solicitações de 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.
- 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 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 status nos cabeçalhos de resposta do 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 status.
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 dependOn . Essa 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 e, em seguida, solicitar 2 e, em seguida, solicitar 4 e solicitar 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 o lote JSON é ignorar 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 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 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 qualquer solicitação exceder os limites, ela falha com uma 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.
Conteúdo relacionado
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de