Enviar solicitudes REST de Outlook por lotes (versión 2.0)

Se aplica a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

El procesamiento por lotes le permite colocar varias solicitudes REST de Outlook en una única solicitud por lote HTTP, lo que reduce el número de conexiones HTTP y la sobrecarga. Las solicitudes en un lote acceden a los datos del usuario que ha iniciado sesión, protegidos por Azure Active Directory en Office 365 o en una cuenta Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com o Passport.com).

Nota

Para simplificar la referencia, en el resto de este artículo se utiliza Outlook.com para englobar a estos dominios de cuentas Microsoft.

¿No está interesado en la versión 2.0 de la API? En el índice de la izquierda, vaya a la sección Referencia de la API de REST de Office 365 y seleccione la versión que desee.

Información general

Una solicitud REST requiere una conexión HTTP entre el cliente y el servidor, lo que implica una cierta sobrecarga. El procesamiento por lotes le permite reducir la sobrecarga de la conexión al combinar varias llamadas API REST para el mismo contexto en una sola solicitud HTTP POST al extremo $batch.

Por ejemplo, puede combinar llamadas API para el contexto me de la forma siguiente:

POST https://outlook.office.com/api/v2.0/me/$batch

Una solicitud por lote puede incluir hasta 20 llamadas API REST individuales, que pueden ser operaciones de consulta de datos (por ejemplo, GET) o de cambio (por ejemplo, POST). Puede especificar un encabezamiento Prefer para que el lote continúe incluso cuando una o más llamadas REST fallen.

El procesamiento por lotes es especialmente útil para sincronizar grandes cantidades de datos. Las llamadas API en el mismo lote pueden acceder a distintos recursos, como mensajes y eventos, que pertenecen al mismo buzón.

Si necesita hacer más de 20 llamadas, o si el orden de realización de las llamadas es importante, utilice varias solicitudes por lote.

Ejemplo

Un simple ejemplo ilustra mejor el procesamiento por lotes. La siguiente solicitud por lote pone 2 llamadas a API de REST de Outlook en un solo lote para el contexto me:

1. GET de todos los eventos del usuario que ha iniciado sesión.
2. POST y enviar un mensaje.

Solicitud de lote

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

Authorization: Bearer aGFwcHlnQGRr==
Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_myBatchId


--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

GET /api/v2.0/me/events?$select=subject,organizer HTTP/1.1

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/v2.0/me/sendmail HTTP/1.1
Content-Type: application/json

{
  "Message": {
    "Subject": "Meet for lunch?",
    "Body": {
      "ContentType": "Text",
      "Content": "The new cafeteria is open."
    },
    "ToRecipients": [
      {
        "EmailAddress": {
          "Address": "rufus@contoso.com"
        }
      }
    ]
  }
}
 
--batch_myBatchId--

Nota

En el ejemplo anterior que tiene una operación POST al final del lote, actualmente se requiere una nueva línea después del último delimitador de lote --batch_{batchId}--. Consulte más notas sobre formato para cuerpos de solicitud por lote.

Respuesta por lote

La respuesta por lote incluye códigos y cuerpos de respuesta separados, cuando corresponda, para la solicitud por lote y las llamadas individuales.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Length: 786

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAt9AHkAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALfZeSA==\"",
            "Id":"AAMkAGI1AAAt9AHkAAA=",
            "Subject":"Let's go for lunch",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAtCq6LAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALQzodA==\"",
            "Id":"AAMkAGI1AAAtCq6LAAA=",
            "Subject":"Prep for customer visit",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 202 Accepted

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a--

URL de punto de conexión

Puede hacer POST en el extremo $batch para uno de estos 2 contextos:

• Para un usuario que ha iniciado sesión me:

  POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1
  

• Para un usuario específico, donde user_id puede ser un Id. de usuario o una dirección de correo electrónico de usuario:

  POST https://outlook.office.com/api/v2.0/users('{user_id}')/$batch
  

Una vez que haya establecido el contexto en la solicitud POST al extremo $batch, todas las llamadas API REST incluidas en la misma solicitud por lote se deben aplicar al mismo contexto.

Importante

• Si su solicitud por lote es para un usuario específico, asegúrese de hacer referencia al usuario de manera coherente en todo el conjunto de solicitudes por lote. Es decir, utilice solo .../users('{user_id}') o .../users/'{user_id}', pero no ambos.
• Cuando se utiliza la URL raíz https://outlook.office.com, para un rendimiento óptimo, agregue un encabezado x-AnchorMailbox y establézcalo en la dirección de correo electrónico del usuario.
• Además, contemple el caso en que el buzón de un usuario de Outlook.com aún no esté habilitado para la API de REST de Outlook. Verifique si están presentes los códigos de error MailboxNotEnabledForRESTAPI y MailboxNotSupportedForRESTAPI. Vea más información aquí.

Nota

Notas para desarrolladores en China

• Si está desarrollando aplicaciones para Office 365 en China, debe continuar utilizando los puntos de conexión de API de Office 365 para China.
• Si está creando aplicaciones para Outlook.com en China, debe utilizar la versión preliminar del modelo de aplicaciones v2 y el siguiente extremo REST de Outlook: https://outlook.office.com/api/{version}

Versión de la API

El estado de esta API se ha promocionado de versión preliminar a disponibilidad general. Es compatible con las versiones 2.0 y beta de la API REST de Outlook.

Debe especificar el mismo host y la misma versión en la solicitud por lote que en las llamadas REST en el lote.

Usuario objetivo

Puede agrupar llamadas API REST de Outlook para el mismo buzón en un lote. El buzón puede estar en Office 365 o Outlook.com. Intentar acceder a más de un buzón en un conjunto de solicitudes por lote genera una excepción.

Autenticación

De la misma forma que con el envío de llamadas API REST de Outlook como solicitudes individuales, debe incluir un token de acceso válido en un encabezado Authorization de solicitud. Si especifica este encabezado para la solicitud por lote, el token de acceso debería proporcionar el permiso necesario para todas las llamadas en ese lote. Opcionalmente, puede especificar un token de acceso para una llamada específica en el lote si esa llamada requiere un token de acceso distinto.

Obtener un token de acceso requiere que haya registrado e identificado su aplicación y obtenido la autorización correspondiente. Obtenga más información sobre algunas opciones de registro y autorización optimizadas para usted. Tenga esto en cuenta a medida que obtenga más información sobre las solicitudes de procesamiento por lotes.

Encabezados de solicitud por lote

Incluya los siguientes encabezados para cada solicitud por lote:

Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_<batchId> 

donde {batchId} identifica un lote y se utiliza para delimitar las solicitudes del lote. Puede ser un GUID o cualquier cadena distintiva.

Puede incluir otros encabezados cuando corresponda. A excepción de los encabezados relacionados con el contenido, como Content-Type, los encabezados en la solicitud por lote generalmente se aplican a todas las operaciones en el lote. Si especifica un encabezado tanto en la solicitud por lote como en una operación específica en el lote, este último tiene prioridad y se aplica a esa operación.

Cuerpo de la solicitud por lote

Comience cada operación de un lote con las siguientes líneas de encabezado:

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

Termine la última operación del lote de la forma siguiente:

--batch_{batchId}--
 

Formato de un cuerpo de solicitud por lote

Tenga en cuenta los siguientes requisitos de formato; de lo contrario, su solicitud por lote puede fallar o es posible que no devuelva las respuestas que espera:

• Asegúrese de tener una nueva línea adicional antes de un delimitador de límites de lote, tal como se muestra en el siguiente cuerpo de solicitud que tiene 2 operaciones GET por lotes.
• En concreto, si tiene una solicitud POST al final de un lote similar a la primera solicitud por lote de ejemplo, asegúrese de que haya una nueva línea después del último delimitador de lote --batch_{batchId}--.

Puede ver más ejemplos de cuerpos de solicitud por lote en Procesamiento por lotes (versión 3.0 de OData).

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/messages    HTTP/1.1

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/events    HTTP/1.1

--batch_{batchId}--
 

Operaciones en un lote

Puede especificar hasta 20 operaciones en una solicitud por lote.

Una operación en un lote puede ser una consulta de datos, una modificación, una acción o una solicitud de invocación de función. Si bien no es necesario que repita las URL completas y establezca todos los encabezados para cada operación en el lote, asegúrese de incluir encabezados y cuerpo de solicitud específicos si son necesarios para una operación.

Formatos admitidos de solicitudes en un lote

Como se ha mencionado anteriormente, el host, la versión y el contexto deben ser coherentes en todo un conjunto de solicitudes por lote. Las solicitudes incluidas en el mismo lote pueden ser una combinación de cualquiera de los siguientes 3 formatos. Para los ejemplos siguientes, suponga que la solicitud POST al extremo $batch tiene este aspecto:

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

URL absoluta

Incluya el host, la versión y el contexto en la URL. Por ejemplo:

GET https://outlook.office.com/api/v2.0/me/messages?$select=subject,sender HTTP/1.1 

URL relativa al host

Incluya una URL relativa al host especificado en la solicitud por lote. Si bien no repite el host en cada solicitud por lote, sí incluye la versión y el contexto. Por ejemplo:

GET /api/v2.0/me/messages?$select=subject,sender HTTP/1.1

Por ejemplo:

En este formato, no repite el host, la versión y el contexto en la solicitud por lote. Por ejemplo:

GET messages?$select=subject,sender HTTP/1.1

Por ejemplo:

Una solicitud por lote se procesa por sí sola como una solicitud y devuelve su propio código de respuesta. Una solicitud por lote bien formada con encabezados correctos devuelve HTTP 200 - Correcto. Sin embargo, esto no significa que todas las solicitudes en el lote hayan tenido éxito.

Cada solicitud en el cuerpo de solicitud por lote se procesa a su vez por separado y devuelve su propio código de respuesta, así como cualquier cuerpo de respuesta y mensaje de error.

El servidor puede realizar operaciones de un lote en cualquier orden. Si se deben realizar operaciones en un orden específico, no debe ponerlas en la misma solicitud por lote. En su lugar, envíe una operación individual, y espere la respuesta antes de enviar la siguiente.

De forma predeterminada, el procesamiento se detiene en la primera operación que devuelve un error. Puede especificar el siguiente encabezado para que el procesamiento ignore el error y continúe con la siguiente operación en el lote:

Prefer: odata.continue-on-error

Pasos siguientes

Tanto si está listo para empezar a compilar una aplicación como si simplemente desea obtener más información, tenemos todo lo que necesita.

• Comience con las API REST de correo, calendario y contactos.
• ¿Desea ver ejemplos? Los tenemos.

O bien, obtenga más información sobre el uso de la plataforma de Office 365:

• API REST de Outlook en el Centro de desarrollo de Outlook
• Información general del desarrollo en la plataforma de Office 365
• Autenticación de aplicaciones y autorización de recursos de Office 365
• Registre manualmente su aplicación con Azure AD para poder acceder a las API de Office 365
• Referencia de las API REST de correo
• Referencia de las API de REST de calendario
• Referencia de las API de REST de contactos
• API de REST de tareas (vista previa)
• Referencia de recursos para las API de REST de correo, calendario, contactos y tareas
• Referencia de la API REST de extensiones de datos de Office 365
• Referencia de la API REST de contactos de Outlook
• Referencia de la API de REST de notificaciones
• Referencia de la API de REST de foto del usuario