Combinaison de plusieurs requêtes dans un seul appel HTTP à l’aide du traitement par lots JSON

Le traitement par lots JSON permet d’optimiser votre application en combinant plusieurs requêtes (jusqu’à 20) dans un seul objet JSON. Par exemple, un client peut être amené à composer un affichage de données non liées tel que :

  1. Une image stockée dans OneDrive
  2. Une liste de tâches de planificateur
  3. 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.

Première requête de lots JSON

Tout d’abord vous construisez la requête de lots JSON pour l’exemple précédent. Dans ce scénario, les requêtes individuelles ne sont pas interdépendantes d’aucune manière et par conséquent peuvent être placées dans la requête de lots 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"
      }
    }
  ]
}

Les réponses aux lots de requêtes peuvent apparaître 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.

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": "2",
      "status": 200,
      "body": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.plannerTask)",
        "value": []
      }
    },
    {
      "id": "4",
      "status": 204,
      "body": null
    }
  ]
}

Format de la requête

Les lots de requêtes sont toujours envoyés à l’aide d’un BILLET au point de terminaison /$batch.

Un corps de lot de requêtes JSON se compose d’un objet JSON unique avec une propriété requise : requêtes. La propriété requêtes est une collection de requêtes individuelles. Pour chaque requête individuelle, les propriétés suivantes peuvent être passées.

Property Description
id Obligatoire. Valeur de corrélation permettant d’associer des réponses individuelles à des requêtes. Cette valeur permet au serveur de traiter les requêtes dans le lot dans l’ordre le plus efficace.
méthode Obligatoire. Méthode HTTP.
url Obligatoire. URL de ressource relative à laquelle la requête individuelle est généralement envoyée. 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 comme "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 en URL base64, par exemple, lorsque le corps est une image. Lorsqu’un corps est inclus dans la requête, l’objet des en-têtes doit contenir une valeur pour Content-Type.

Format de la réponse

Le format de la réponse pour les requêtes de lots JSON est similaire au format de la requête. Voici les principales différences :

  • 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 méthode et url, les réponses individuelles ont une propriété état. La valeur de l’état est un nombre qui représente le code d’état HTTP.

Le code d’état sur un lot de réponses est généralement 200 ou 400. Si le lot de requêtes lui-même est incorrect, le code d’état est 400. Si le lot de requêtes est analysable, le code d’état est 200. Un code d’état 200 sur le lot de réponses 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é réponses a un code d’état.

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

Les requêtes individuelles peuvent être exécutées 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 requête individuelle différente. Pour cette raison, les valeurs de ID doivent être uniques. Par exemple, dans la requête suivante, le client spécifie que les requêtes doivent être exécutées dans l’ordre de requête 1, ensuite requête 3, puis requête 2, et requête 4.

{
  "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 cas d’utilisation supplémentaire pour le traitement par lots JSON consiste à contourner les limitations de longueur d’URL. Dans le cas où la clause de filtre est complexe, la longueur de l’URL peut dépasser les limitations intégrées aux navigateurs ou autres clients HTTP. Vous pouvez utiliser le traitement par lots JSON comme solution de contournement pour ces requêtes en cours d’exécution, car l’URL longue s’intègre simplement à la charge utile de la requête.

Problèmes connus

Pour une liste des limitations actuelles liées au traitement par lots, voir Problèmes connus.

Voir aussi

Pour plus d’informations sur le format de requête/réponse de lots JSON, voir la spécification de version 4.01 du format JSON OData, section Requêtes et réponses de lots.