Combinación de varias solicitudes HTTP mediante el procesamiento por lotes 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.
Considere la posibilidad de un cliente que quiera crear una vista de los siguientes datos no relacionados:
- 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 $batchsegmento de ruta de acceso url de OData para admitir el procesamiento por lotes JSON.
Ejemplo: Primera solicitud por lotes JSON
En primer lugar, se crea la solicitud por lotes JSON para el escenario de ejemplo. En este escenario, las solicitudes individuales no son interdependientes 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"
}
}
]
}
Explicación de un formato de solicitud por lotes
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. Cadena. 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. No distingue mayúsculas de minúsculas. Debe ser único en el lote. |
| método | Obligatorio. El método HTTP. |
| url | Obligatorio. Dirección URL del recurso relativa para 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 representa 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. |
Ejemplo: Primera respuesta por lotes JSON
Las respuestas a las solicitudes por lotes pueden aparecer en otro orden. La propiedad id se puede usar para correlacionar solicitudes y respuestas individuales.
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
}
]
}
Explicación de un formato de respuesta por lotes
El formato de respuesta para las solicitudes por lotes JSON difiere del formato de solicitud como se indica a continuación:
- 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 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 200 código de estado en los encabezados de respuesta por lotes no indica que las solicitudes individuales dentro del lote se realizaron 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
Puede especificar las solicitudes en el lote que se van a 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 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
Otro caso de uso 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 actualmente a veinte solicitudes individuales.
- En función de las API que forman parte de la solicitud por lotes, los servicios subyacentes imponen sus propios límites de limitación que afectan a las aplicaciones que usan Microsoft Graph para acceder a ellas.
- Las solicitudes de un lote se evalúan individualmente con respecto a los límites de limitación aplicables y, si alguna solicitud supera los límites, se produce un error con un 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.