Combinación de varias solicitudes HTTP mediante el procesamiento por lotes JSON
El procesamiento por lotes JSON permite a los clientes combinar varias solicitudes en un único objeto JSON y una sola llamada HTTP, lo que reduce los recorridos de ida y vuelta de red y mejora la eficacia. Microsoft Graph admite el procesamiento por lotes de hasta 20 solicitudes en el objeto JSON.
En este artículo, se exploran los conceptos básicos del procesamiento por lotes JSON, cómo funciona y cómo se puede usar para optimizar las aplicaciones.
Nota:
Microsoft Graph implementa el $batchsegmento de ruta de acceso url de OData para admitir el procesamiento por lotes JSON.
Escenario de ejemplo
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.
Creación de una solicitud por lotes
Para crear una solicitud por lotes:
Especifique el método HTTP de solicitud como POST.
Especifique el punto de conexión de dirección URL, si tiene como destino la
v1.0versión obetade Microsoft Graph, y anexe el$batchsegmento a la dirección URL. Es decir,https://graph.microsoft.com/v1.0/$batch.Defina el cuerpo de la solicitud por lotes de la siguiente manera:
- Un cuerpo de solicitud por lotes JSON consta de un único objeto JSON con una propiedad necesaria: requests. Esta propiedad 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; de lo contrario, se produce un error en la solicitud por lotes con un código de 400error.método Obligatorio. Método HTTP compatible con la solicitud especificada en url. 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.
Solicitud por lotes JSON de ejemplo
En este escenario de ejemplo, construirá la solicitud por lotes JSON. 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/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"
}
}
]
}
Procesamiento de la respuesta por lotes JSON
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. La propiedad id se puede usar para correlacionar solicitudes y respuestas individuales.
- 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 4xx. 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.
Respuesta por lotes JSON de ejemplo
En el ejemplo anterior, suponga esta respuesta:
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"
}
]
}
}
]
}
Explicación de respuestas individuales en la respuesta por lotes de ejemplo
- Las solicitudes 1 y 5 se realizaron correctamente, como se muestra en el código de
200estado. - Se produjo un error en las solicitudes 2 y 3 con un
403código de estado porque el autor de la llamada no tenía los permisos necesarios. - Se produjo un error en la solicitud 4 con un
405código de estado porque el punto de conexión especificado en la propiedad url de la solicitud está actualmente solo enbetala dirección URL de la solicitud destinada alv1.0punto de conexión de Microsoft Graph. Aunque la dirección URL de destino no requiere un cuerpo de solicitud, debe especificar los encabezados y los parámetros del cuerpo donde solo el cuerpo puede ser un objeto vacío.
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.