Combinaison de plusieurs requêtes dans un seul appel HTTP à l’aide du traitement par lots JSONCombine multiple requests in one HTTP call using JSON batching

Le traitement par lots JSON permet d’optimiser votre application en combinant plusieurs requêtes dans un seul objet JSON. Par exemple, un client peut être amené à composer un affichage de données non liées tel que :JSON batching allows you to optimize your application by combining multiple requests into a single JSON object. For example, a client might want to compose a view of unrelated data such as:

  1. Une image stockée dans OneDriveAn image stored in OneDrive
  2. Une liste de tâches de planificateurA list of Planner tasks
  3. Le calendrier d’un groupeThe calendar for a group

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.Combining these three individual requests into a single batch request can save the application significant network latency.

Première requête de lots JSONFirst JSON batch request

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.First you construct the JSON batch request for the previous example. In this scenario, the individual requests are not interdependent in any way and therefore can be placed into the batch request in any order.

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 requêtes de lots peuvent s’afficher dans un ordre différent. La propriété id peut être utilisée pour corréler des requêtes et des réponses.Responses to the batched requests might appear in a different order. The id property can be used to correlate individual requests and responses.

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êteRequest format

Les requêtes de lots sont toujours envoyées à l’aide de POST vers le point de terminaison /$batch.Batch requests are always sent using POST to the /$batch endpoint.

Un corps de requête de lots JSON se compose d’un seul objet JSON avec une propriété obligatoire : requests. La propriété requests est un tableau des requêtes individuelles. Pour chaque requête individuelle, les propriétés id, method et url sont obligatoires.A JSON batch request body consists of a single JSON object with one required property: requests. The requests property is an array of individual requests. For each individual request, the id, method, and url properties are required.

La propriété id fonctionne principalement comme une valeur de corrélation pour associer des réponses aux requêtes. Cela permet au serveur de traiter les requêtes dans le lot dans l’ordre le plus efficace.The id property functions primarily as a correlation value to associate individual responses with requests. This allows the server to process requests in the batch in the most efficient order.

Les propriétés method et url sont exactement ce que vous voyez au début de toute requête HTTP donnée. La méthode est la méthode HTTP, et l’URL est l’URL de ressource à laquelle la requête individuelle est généralement envoyée.The method and url properties are exactly what you would see at the start of any given HTTP request. The method is the HTTP method, and the URL is the resource URL the individual request would typically be sent to.

Les requêtes individuelles peuvent éventuellement contenir également une propriété headers et une propriété body.Individual requests can optionally also contain a headers property and a body property. Ces deux propriétés sont généralement des objets JSON, comme montré dans l’exemple précédent.Both of these properties are typically JSON objects, as shown in the previous example. Dans certains cas, la valeur body peut être une valeur encodée au format Base 64 plutôt qu’un objet JSON (par exemple, si le corps est une image).In some cases, the body might be a base64 URL-encoded value rather than a JSON object - for example, when the body is an image. Lorsqu’une valeur body est incluse dans la requête, l’objet headers doit contenir une valeur pour Content-Type.When a body is included with the request, the headers object must contain a value for Content-Type.

Format de la réponseResponse format

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 :The response format for JSON batch requests is similar to the request format. The following are the key differences:

  • La propriété dans l’objet JSON principal est nommée responses par opposition à requests.The property in the main JSON object is named responses as opposed to requests.
  • Les réponses individuelles peuvent apparaître dans un ordre différent de celui des requêtes.Individual responses might appear in a different order than the requests.
  • Au lieu de method et de url, les réponses individuelles ont une propriété status. La valeur de status est un nombre qui représente le code d’état HTTP.Rather than method and url, individual responses have a status property. The value of status is a number that represents the HTTP status code.

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 code d’état 200 sur la réponse par lot ne signifie 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é responses a un code d’état.The status code on a batch response is typically 200 or 400. If the batch request itself is malformed, the status code is 400. If the batch request is parseable, the status code is 200. A 200 status code on the batch response does not indicate that the individual requests inside the batch succeeded. This is why each individual response in the responses property has a status code.

Outre la propriété responses, il peut y avoir une propriété nextLink dans la réponse par lot. Cela permet à Microsoft Graph de renvoyer une réponse par lot dès que l’une des requêtes individuelles est terminée. Pour vous assurer que toutes les réponses individuelles ont été reçues, continuez à suivre le nextLink dans la mesure où il existe.In addition to the responses property, there might be a nextLink property in the batch response. This allows Microsoft Graph to return a batch response as soon as any of the individual requests has completed. To ensure that all individual responses have been received, continue to follow the nextLink as long as it exists.

Séquencement des requêtes avec la propriété dependsOnSequencing requests with the dependsOn property

Les requêtes individuelles peuvent être exécutées dans l’ordre indiqué à l’aide de la propriété dependsOn. Cette propriété est un tableau de chaînes qui font référence à l’id d’une autre requête individuelle. Pour cette raison, les valeurs d’id doivent être uniques. Par exemple, dans la requête suivante, le client spécifie que les requêtes 1 et 3 doivent être exécutées en premier, puis la requête 2, puis la requête 4.Individual requests can be executed in a specified order by using the dependsOn property. This property is an array of strings that reference the id of a different individual request. For this reason, the values for id must be unique. For example, in the following request, the client is specifying that requests 1 and 3 should be run first, then request 2, then request 4.

{
  "requests": [
    {
      "id": "1",
      "method": "GET",
      "url": "..."
    },
    {
      "id": "2",
      "dependsOn": [ "1" ],
      "method": "GET",
      "url": "..."
    },
    {
      "id": "3",
      "method": "GET",
      "url": "..."
    },
    {
      "id": "4",
      "dependsOn": [ "2" ],
      "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).If an individual request fails, any request that depends on that request fails with status code 424 (Failed Dependency).

Contournement des limitations de longueur d’URL avec le traitement par lotsBypassing URL length limitations with batching

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.An additional use case for JSON batching is to bypass URL length limitations. In cases where the filter clause is complex, the URL length might surpass limitations built into browsers or other HTTP clients. You can use JSON batching as a workaround for running these requests because the lengthy URL simply becomes part of the request payload.

Problèmes connusKnown issues

Pour une liste des limitations actuelles liées au traitement par lots, voir Problèmes connus.For a list of current limitations related to batching, see known issues.

Voir aussiSee also

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.For more information about the JSON batch request/response format, see the OData JSON Format Version 4.01 specification, section Batch Requests and Responses.