Combiner plusieurs requêtes HTTP à l’aide du traitement par lot JSON

Article
02/22/2025

Le traitement par lot JSON permet aux clients de combiner plusieurs requêtes en un seul objet JSON et un seul appel HTTP, ce qui réduit les allers-retours réseau et améliore l’efficacité. Microsoft Graph prend en charge le traitement par lot de jusqu’à 20 requêtes dans l’objet JSON.

Dans cet article, nous explorons les principes de base du traitement par lots JSON, son fonctionnement et la façon dont vous pouvez l’utiliser pour optimiser vos applications.

Remarque

Microsoft Graph implémente le segment de $batchchemin d’URL OData pour prendre en charge le traitement par lot JSON.

Exemple de scénario

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.

Création d’une demande de traitement par lots

Pour créer une demande de traitement par lots :

Spécifiez la méthode HTTP de requête post.
Spécifiez le point de terminaison d’URL, s’il cible la v1.0 version ou beta de Microsoft Graph, puis ajoutez le $batch segment à l’URL. Autrement dit, https://graph.microsoft.com/v1.0/$batch.

Définissez le corps de la demande de lot comme suit :

Un corps de demande de lot JSON se compose d’un seul objet JSON avec une propriété obligatoire : requests. Cette propriété 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 ; sinon, la demande de lot échoue avec un `400` code d’erreur.
méthode	Obligatoire. Méthode HTTP prise en charge pour la requête spécifiée dans l’URL.
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 de demande de lot JSON

Dans cet exemple de scénario, vous construisez la demande de traitement par lots JSON. 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.

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);

Pour plus d’informations sur l’ajout du SDK à votre projet et la création d’un instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Traitement de la réponse par lot JSON

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. La propriété id peut être utilisée pour mettre en corrélation des requêtes et des réponses individuelles.
Au lieu de la méthode et de l’URL, les réponses individuelles ont une propriété status. La valeur de status est le code status 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 4xx. 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 status 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 status.

Exemple de réponse par lot JSON

Pour l’exemple précédent, supposons que cette réponse :

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

Explication des réponses individuelles dans l’exemple de réponse par lot

Les requêtes 1 et 5 ont réussi comme indiqué par le 200 code status.
Les requêtes 2 et 3 ont échoué avec un 403 code status, car l’appelant ne disposait pas des autorisations requises.
La requête 4 a échoué avec un 405 code status, car le point de terminaison spécifié dans la propriété url de la requête est actuellement uniquement dansbeta, mais l’URL de la requête cible le v1.0 point de terminaison de Microsoft Graph. Bien que l’URL cible ne nécessite pas de corps de requête, vous devez toujours spécifier les en-têtes et les paramètres de corps où seul le corps peut être un objet vide.

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 un status de 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.

Utiliser les Kits de développement logiciel (SDK) Microsoft Graph pour traiter les demandes par lot

Partager via

Combiner plusieurs requêtes HTTP à l’aide du traitement par lot JSON

Exemple de scénario

Création d’une demande de traitement par lots

Exemple de demande de lot JSON

Traitement de la réponse par lot JSON

Exemple de réponse par lot JSON

Explication des réponses individuelles dans l’exemple de réponse par lot

Séquencement des requêtes avec la propriété dependsOn

Contournement des limitations de longueur d’URL avec le traitement par lots

Limitations de taille de lot

Problèmes connus

Commentaires

Ressources supplémentaires

Partager via

Combiner plusieurs requêtes HTTP à l’aide du traitement par lot JSON

Exemple de scénario

Création d’une demande de traitement par lots

Exemple de demande de lot JSON

Traitement de la réponse par lot JSON

Exemple de réponse par lot JSON

Explication des réponses individuelles dans l’exemple de réponse par lot

Séquencement des requêtes avec la propriété dependsOn

Contournement des limitations de longueur d’URL avec le traitement par lots

Limitations de taille de lot

Problèmes connus

Contenu connexe

Commentaires

Ressources supplémentaires