Combiner plusieurs requêtes HTTP à l’aide du traitement par lot JSON
Le traitement par lot JSON vous permet d’optimiser votre application en combinant plusieurs requêtes (jusqu’à 20) dans un seul objet JSON.
Prenons l’exemple d’un client qui souhaite composer une vue des données non liées suivantes :
- Une image stockée dans OneDrive
- Une liste de tâches de planificateur
- Le calendrier d’un groupe
La combinaison de ces trois requêtes individuelles dans une requête de lots unique permet d’enregistrer la latence du réseau significative de l’application.
Microsoft Graph implémente le segment de $batchchemin d’URL OData pour prendre en charge le traitement par lot JSON.
Exemple : première demande de lot JSON
Tout d’abord, vous construisez la demande de lot JSON pour l’exemple de scénario. Dans ce scénario, les requêtes individuelles ne sont pas interdépendantes et peuvent donc être placées dans la demande de lot dans n’importe quel ordre.
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"
}
}
]
}
Explication d’un format de demande de lot
Les lots de requêtes sont toujours envoyés à l’aide d’un BILLET au point de terminaison /$batch.
Un corps de demande de lot JSON se compose d’un seul objet JSON avec une propriété obligatoire : requests. La propriété requests est une collection de requêtes individuelles. Pour chaque requête individuelle, les propriétés suivantes peuvent être passées.
| Propriété | Description |
|---|---|
| id | Obligatoire. Chaîne. Valeur de corrélation permettant d’associer des réponses individuelles à des demandes. Cette valeur permet au serveur de traiter les demandes dans le lot dans l’ordre le plus efficace. Ne respecte pas la casse. Doit être unique dans le lot. |
| méthode | Obligatoire. Méthode HTTP. |
| url | Obligatoire. URL de ressource relative pour la requête individuelle. Par conséquent, alors que l’URL absolue est https://graph.microsoft.com/v1.0/users, cette URL est /users. |
| en-têtes | Facultatif mais obligatoire lorsque le corps est spécifié. Objet JSON avec la paire clé/valeur pour les en-têtes. Par exemple, lorsque l’en-tête ConsistencyLevel est requis, cette propriété est représentée sous la forme "headers": {"ConsistencyLevel": "eventual"}. Lorsque le corps est fourni, un en-tête Content-Type doit être inclus. |
| body | Facultatif. Il peut s’agir d’un objet JSON ou d’une valeur encodée URL en base64, par exemple, lorsque le corps est une image. Lorsqu’un corps est inclus dans la requête, l’objet desen-têtes doit contenir une valeur pour Content-Type. |
Exemple : Première réponse par lot JSON
Les réponses aux requêtes de lots peuvent s’afficher dans un ordre différent. La propriété id peut être utilisée pour mettre en corrélation des requêtes et des réponses individuelles.
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
}
]
}
Explication d’un format de réponse par lot
Le format de réponse pour les demandes de traitement par lots JSON diffère du format de requête comme suit :
- La propriété dans l’objet JSON principal est nommée réponses par opposition à requêtes.
- Les réponses individuelles peuvent apparaître dans un ordre différent de celui des requêtes.
- Au lieu de la méthode et de l’URL, les réponses individuelles ont une propriété d’état. La valeur de l’état est le code d’état HTTP.
- La propriété headers dans chaque réponse individuelle représente les en-têtes retournés par le serveur, par exemple, les en-têtes Cache-Control et Content-Type.
Le code d’état sur une réponse par lot est généralement 200 ou 400. Si la requête de lots proprement dite est incorrecte, le code d’état est 400. Si la requête de lots est analysable, le code d’état est 200. Un 200 code d’état sur les en-têtes de réponse de lot n’indique pas que les requêtes individuelles à l’intérieur du lot ont réussi. C’est pourquoi chaque réponse individuelle dans la propriété response a un code d’état.
Séquencement des requêtes avec la propriété dependsOn
Vous pouvez spécifier les demandes dans le lot à exécuter dans un ordre spécifié à l’aide de la propriété dependsOn . Cette propriété est un tableau de chaînes qui fait référence à l’ID d’une demande individuelle différente. Par exemple, dans la requête suivante, le client spécifie que les demandes doivent être exécutées dans la demande de commande 1, puis la demande 2, puis la demande 4, puis la demande 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": "..."
}
]
}
En cas d’échec d’une requête individuelle, toute requête qui dépend de celle-ci échoue avec un code d’état 424 (échec de dépendance).
Conseil
Le lot doit être entièrement séquentiel ou entièrement parallèle.
Contournement des limitations de longueur d’URL avec le traitement par lots
Un autre cas d’usage pour le traitement par lot JSON consiste à contourner les limitations de longueur d’URL. Dans les cas où la clause de filtre est complexe, la longueur de l’URL peut dépasser les limitations intégrées aux navigateurs ou à d’autres clients HTTP. Vous pouvez utiliser le traitement par lot JSON comme solution de contournement pour l’exécution de ces requêtes, car la longue URL fait simplement partie de la charge utile de la requête.
Limitations de taille de lot
- Les requêtes de lots JSON sont actuellement limitées à 20 requêtes individuelles.
- En fonction des API qui font partie de la demande par lot, les services sous-jacents imposent leurs propres limites de limitation qui affectent les applications qui utilisent Microsoft Graph pour y accéder.
- Les demandes d’un lot sont évaluées individuellement par rapport aux limites de limitation applicables et si une demande dépasse les limites, elle échoue avec l’état
429.
Pour plus d’informations, consultez Limitation et traitement par lot.
Problèmes connus
Pour une liste des limitations actuelles liées au traitement par lots, voir Problèmes connus.