Combinación de varias solicitudes en una llamada HTTP mediante el procesamiento por lotes de JSON

El procesamiento por lotes JSON permite optimizar la aplicación mediante la combinación de varias solicitudes (hasta 20) en un único objeto JSON. Por ejemplo, es posible que un cliente quiera crear una vista de datos no relacionados, como:

• Una imagen almacenada en OneDrive
• Una lista de tareas de Planner
• El calendario de un grupo

La combinación de estas tres solicitudes individuales en una sola solicitud por lotes puede ahorrarle a la aplicación una importante latencia de red.

Microsoft Graph implementa el segmento de ruta de dirección URL de OData $batch para admitir el procesamiento por lotes JSON.

Primera solicitud por lotes JSON

En primer lugar, cree la solicitud por lotes JSON para el ejemplo anterior. En este escenario, las solicitudes individuales no son interdependientes de ninguna manera y, por tanto, se pueden colocar en la solicitud por lotes en cualquier orden.

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

Las respuestas a las solicitudes por lotes pueden aparecer en otro orden. La propiedad id se puede usar para correlacionar solicitudes y respuestas individuales.

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": {
        "OData-Version": "4.0",
      },
      "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
    }
  ]
}

Formato de solicitud

Las solicitudes por lotes siempre se envían mediante un POST al punto de conexión /$batch.

Un cuerpo de solicitud por lotes JSON consta de un único objeto JSON con una propiedad necesaria: requests. La propiedad requests es una colección de solicitudes individuales. Para cada solicitud individual, se pueden pasar las siguientes propiedades.

Propiedad	Descripción
id	Obligatorio. Valor de correlación para asociar respuestas individuales a solicitudes. Este valor permite al servidor procesar solicitudes en el lote en el orden más eficaz.
método	Obligatorio. El método HTTP.
url	Obligatorio. La URL relativa del recurso a la que se enviará normalmente la solicitud individual. Por lo tanto, mientras que la dirección URL absoluta es https://graph.microsoft.com/v1.0/users, esta dirección URL es /users.
encabezados	Opcional pero necesario cuando se especifica el cuerpo. Un objeto JSON con el par clave/valor de los encabezados. Por ejemplo, cuando se requiere el encabezado ConsistencyLevel, esta propiedad se representaría como "headers": {"ConsistencyLevel": "eventual"}. Cuando se suministra el cuerpo, debe incluirse una cabecera Content-Type.
body	Opcional. Puede ser un objeto JSON o un valor codificado en URL base64, por ejemplo, cuando el cuerpo es una imagen. Cuando se incluye un cuerpo con la solicitud, el objeto encabezados debe contener un valor para Content-Type.

Formato de respuesta

El formato de respuesta para las solicitudes por lotes JSON es similar al formato de solicitud. A continuación se muestran las principales diferencias:

• La propiedad del objeto JSON principal se denomina responses en lugar de requests.
• Las respuestas individuales pueden aparecer en un orden diferente a las solicitudes.
• En lugar de método y dirección URL, las respuestas individuales tienen una propiedad de estado . El valor de status es un número que representa el código de estado HTTP.
• La propiedad encabezados de cada respuesta individual representa los encabezados devueltos por el servidor, por ejemplo, los encabezados Cache-Control y Content-Type.

Normalmente, el código de estado en una respuesta por lotes es 200 o 400. Si la propia solicitud por lotes tiene un formato incorrecto, el código de estado es 400. Si la solicitud por lotes se puede analizar, el código de estado es 200. Un código de estado 200 en la respuesta por lotes no indica que las solicitudes individuales comprendidas en el lote se hayan realizado correctamente. Esta es la razón por la que cada respuesta individual de la propiedad responses tiene un código de estado.

Secuenciar solicitudes con la propiedad dependsOn

Las solicitudes individuales se pueden ejecutar en un orden especificado mediante la propiedad dependsOn . Esta propiedad es una matriz de cadenas que hace referencia al identificador de una solicitud individual diferente. Por este motivo, los valores de id deben ser únicos. Por ejemplo, en la siguiente solicitud, el cliente especifica que las solicitudes se deben ejecutar en la solicitud de pedido 1, después en la solicitud 2, en la solicitud 4 y en la solicitud 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": "..."
    }
  ]
}

Si se produce un error en una solicitud individual, cualquier solicitud que dependa de dicha solicitud producirá un error con código de estado 424 (dependencia errónea).

Sugerencia

El lote debe ser completamente secuencial o totalmente paralelo.

Omitir las limitaciones de longitud de URL con el procesamiento por lotes

Un caso de uso adicional para el procesamiento por lotes JSON es omitir las limitaciones de longitud de la dirección URL. En los casos en los que la cláusula de filtro es compleja, la longitud de la dirección URL podría superar las limitaciones integradas en exploradores u otros clientes HTTP. Puede usar el procesamiento por lotes JSON como solución alternativa para ejecutar estas solicitudes porque la dirección URL larga simplemente pasa a formar parte de la carga de la solicitud.

Limitaciones de tamaño de lote

Las solicitudes por lotes JSON están limitadas, de momento, a 20 solicitudes individuales y, además, existen las siguientes limitaciones:

• En función de las API que forman parte de la solicitud por lotes, los servicios subyacentes imponen sus propios límites que afectan a las aplicaciones que usan Microsoft Graph para llevar a cabo el acceso.
• Las solicitudes de un lote se evalúan de forma individual con respecto a los límites de restricción y, si alguna solicitud supera los límites, se produce un error con estado de 429.

Para obtener más información, consulte Limitación y procesamiento por lotes.

Problemas conocidos

Para obtener una lista de las limitaciones actuales relacionadas con el procesamiento por lotes, consulte problemas conocidos.

Vea también

Para más información sobre el formato de solicitud o respuesta por lotes JSON, consulte la especificación OData JSON, versión de formato 4.01, sección Solicitudes y respuestas por lotes.