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
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários