Usar la API de REST de Outlook (versión 1.0)

  • Artículo

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

Nota

La versión 1.0 de la API REST de Outlook está obsoleta. A partir del 1 de noviembre de 2018, las aplicaciones ya no podrán utilizar la autentificación básica con el punto de conexión REST v1.0. El 1 de noviembre de 2019, el extremo REST v1.0 se retirará completamente, y la documentación de v1.0 se eliminará poco después. Comience a migrar su aplicación para utilizar la API REST de Outlook en v1.0 de Microsoft Graph. Vea más detalles en nuestro anuncio.

La API de REST de Outlook incluye los siguientes subconjuntos para permitir el acceso a los datos del buzón de los usuarios de Office 365, Hotmail.com, Live.com, MSN.com, Outlook.com y Passport.com.

La siguiente tabla enumera la primera versión en que estuvo disponible la funcionalidad principal de cada subconjunto. Tenga en cuenta que dentro de cada subconjunto pueden agregarse posteriormente nuevas características y API en una versión más moderna.

Subconjunto de la API Versiones disponibles
Procesamiento por lotes de múltiples llamadas API v2.0, beta
API de calendario v2.0, v1.0, beta
API de contactos v2.0, v1.0, beta
API de extensiones de datos v2.0, beta
API de propiedades extendidas v2.0, beta
API de correo v2.0, v1.0, beta
API de notificaciones push v2.0, beta
API de notificaciones de transmisión por secuencias (versión preliminar) beta
API de personas beta
API de tareas v2.0, beta
API de foto de usuario v2.0, beta

Nota

El resto de este artículo incluye información común aplicable a todos los subconjuntos de la API de REST de Outlook. Para simplificar la referencia, en el resto de este artículo se usa Outlook.com para englobar las cuentas de los dominios Hotmail.com, Live.com, MSN.com, Outlook.com y Passport.com.

Registrar y autenticar su aplicación

Para usar la API de REST de Outlook con el fin de acceder a los datos del buzón de un usuario, su aplicación debe ocuparse del registro y la autorización de dicho usuario:

  1. Primero, registre su aplicación para obtener acceso a la API de REST de Outlook. Luego podrá implementar las llamadas API en la aplicación.

  2. En tiempo de ejecución, obtenga la autorización del usuario y haga solicitudes de la API de REST para acceder al buzón del mismo.

Actualmente hay dos enfoques sobre cómo controlar el registro de la aplicación y la autorización del usuario:

Extremo de autenticación de Azure AD v2

El extremo de autenticación de Azure AD v2 simplifica compilar una aplicación que funcione tanto con cuentas Microsoft de una organización como personales. Permite a los usuarios con cuentas del trabajo, la escuela o personales iniciar sesión con un solo botón.

Este modelo de programación convergente es el enfoque más moderno, que comprende lo siguiente:

Este enfoque proporciona un registro de la aplicación y una experiencia de autorización del usuario sin fisuras para obtener los tokens apropiados con el fin de acceder a los datos del buzón de los usuarios de Office 365 o Outlook.com. Si está desarrollando una aplicación para Outlook.com, debe usar este enfoque.

En vez de solicitar permisos durante el registro de la aplicación, el extremo de autenticación v2 le permite pedir confirmación dinámicamente y solicitar los permisos necesarios en función de las acciones de usuario correspondientes en tiempo de ejecución.

Este modelo de programación convergente consta de varios componentes, por lo que si usa uno de ellos, debería utilizar también los otros.

Para obtener más información, consulte ejemplos de introducción y Autenticar las API de Office 365 y Outlook.com utilizando el extremo de autenticación v2.

Importante

Al crear o actualizar una aplicación, asegúrese de que esta sea capaz de manejar los buzones de Outlook.com que se hayan habilitado y a los que usted puede acceder utilizando la API de REST de Outlook, y también los buzones que estén a la espera de habilitarse. Vea más información sobre cómo probar y manejar tales escenarios de Outlook.com.

Registrarse y autenticarse con Azure AD y OAuth

Este es un enfoque más antiguo para acceder a los datos del buzón solamente en Office 365. Si planea acceder a datos en Outlook.com o crear una nueva aplicación para Office 365, use en cambio el extremo de autenticación v2.

Por el momento, para acceder a los datos del buzón de Office 365, puede continuar registrando la aplicación en Azure AD como antes, especificando los permisos en el ámbito apropiado que requiera dicha aplicación. En tiempo de ejecución, su aplicación puede seguir utilizando Azure AD y OAuth para autenticar solicitudes de aplicaciones. Puede encontrar más detalles en conceptos de autenticación de una aplicación de Office 365. Debe planificar una ruta de actualización.

Con este enfoque, puede optar por acceder a la API de REST de Outlook llamándola directamente en sus aplicaciones de Office 365 o usando las bibliotecas de cliente de Office 365.

Ruta de actualización

El estatus del extremo de autenticación v2 se ha promovido de versión preliminar a disponibilidad general (GA) para programadores de Outlook y Outlook.com.

Si tiene una aplicación en producción que acceda a datos del buzón de Office 365, o si está creando una nueva aplicación para Office 365 o Outlook.com, planee usar el extremo de autenticación v2 junto con el más reciente extremo de Outlook (https://outlook.office.com/, vea abajo más información) para aprovechar la ventaja de tener que escribir solo un conjunto de código tanto para Office 365 para organizaciones como para usuarios particulares de Outlook.com.

Si tiene una aplicación en producción que use la API de Windows Live para acceder a datos del buzón de Outlook.com, deberá reescribir la aplicación para usar el extremo de autenticación v2 y la API de REST de Outlook. Conforme la API de Windows Live vaya quedándose obsoleta para Outlook.com y los usuarios de Outlook.com vayan habilitando sus buzones para la API de REST de Outlook, estos usuarios irán recibiendo errores HTTP 404 cuando intenten ejecutar dichas aplicaciones de la API de Windows Live.

En cambio, la API de REST de Outlook le abre nuevas oportunidades.—Puede elegir entre una lista de lenguajes comunes, como Node, Python, Swift, Java, etc., escribir la aplicación una sola vez y capturar tanto usuarios de Outlook.com como también usuarios de Office 365 en la web, iOS, Android o dispositivos de Windows.

Nota

Si desea que su aplicación en producción continúe accediendo solamente a datos del buzón de Outlook.com, puede seguir utilizando los mismos ámbitos de Windows Live para acceder a la mayoría de la API de REST de Outlook. Para obtener más información, consulte Usar los ámbitos de Windows Live y la API de REST de Outlook para acceder a datos de un buzón de Outlook.com.

Independientemente del enfoque que utilice para el registro de la aplicación y la autorización del usuario, o tanto si su aplicación se destina a datos del buzón de Office 365 o de Outlook.com, el extremo de REST de Outlook más reciente está en producción y puede empezar a utilizarlo en sus llamadas API de REST en cuanto desee:

https://outlook.office.com/api/{version}/{user_context}

El siguiente extremo de REST de Outlook continuará funcionando durante un tiempo solo para datos del buzón de Office 365:

https://outlook.office365.com/api/{version}/{user_context}

Vea abajo más información sobre acciones de REST admitidas, extremos y versiones.

Importante

  • La autorización básica ya no es compatible con el extremo de la API de REST de Outlook https://outlook.office.com. Use el extremo de autenticación v2 o Azure AD para realizar la autorización y la autenticación de una aplicación que use el nuevo extremo de la API de REST de Outlook.
  • Para un rendimiento óptimo al usar el nuevo extremo de REST de Outlook, agregue un encabezado x-AnchorMailbox para cada solicitud y configúrelo para la dirección de correo electrónico del usuario. Por ejemplo: x-AnchorMailbox:john@contoso.com
  • Dado que la habilitación de buzones en Outlook.com para la API de REST de Outlook se prolonga durante un tiempo, su cuenta existente de Outlook.com puede tardar en habilitarse. Para probar su aplicación de acceso de datos en los buzones de Outlook.com que ya se han habilitado, puede solicitar una cuenta de vista previa de desarrolladores de Outlook.com, nueva y habilitada enviando un correo electrónico a outlookdev@miccrosoft.com
  • Si su aplicación accede a datos de un buzón de Outlook.com, debe manejar escenarios donde el buzón del usuario aún no esté habilitado para la API de REST de Outlook. En tales situaciones, cuando realice una solicitud REST, se producirá un error como los siguientes:
    • Error de HTTP: 404
    • Código de error: MailboxNotEnabledForRESTAPI o MailboxNotSupportedForRESTAPI
    • Mensaje de error: "La API de REST aún no es compatible con este buzón.
  • Para muestras de código que usan el extremo de autenticación v2, consulte dev.outlook.com.

Usar los ámbitos de Windows Live y la API de REST de Outlook para acceder a datos de un buzón de Outlook.com

Si su aplicación en producción para Outlook.com usa ámbitos de Windows Live y no pretende acceder a datos de buzones de Office 365, puede continuar utilizando esos ámbitos de Windows Live con la mayor parte de la API de REST de Outlook. La siguiente tabla muestra cómo los ámbitos de Windows Live se correlacionan con los de la API de REST de Outlook. Tenga en cuenta que no hay un ámbito de Windows Live que se correlacione directamente con Mail.Read; su aplicación puede usar wl.imap para acceder a las operaciones de la API de REST de Outlook que requieran Mail.Read.

Ámbitos de Windows Live Ámbitos de la API de REST de Outlook
wl.basic User.Read, Contacts.Read
wl.calendars Calendars.Read
wl.calendars_update Calendars.ReadWrite
wl.contacts_create Contacts.ReadWrite
wl.contacts_calendars Calendars.Read
wl.emails User.Read
wl.events_create Calendars.ReadWrite
wl.imap Mail.ReadWrite, Mail.Send

Acciones y extremos de REST admitidos

Para interactuar con la API de REST de Outlook, envíe solicitudes HTTP que utilicen un método admitido: GET, POST, PATCH o DELETE. Los cuerpos de las solicitudes POST y PATCH y las respuestas del servidor se envían en cargas útiles JSON.

Los nombres de los recursos de la URL de la ruta de acceso y los parámetros de consulta no distinguen entre mayúsculas y minúsculas. Pero los valores que asigne, los identificadores de entidad y otros valores codificados en base64 sí distinguen entre mayúsculas y minúsculas.

Todas las solicitudes de la API de REST de Outlook utilizan el siguiente formato nuevo de URL raíz:

https://outlook.office.com/api/{version}/{user_context}

Con la autorización de usuario adecuada, la API de REST en esta URL raíz proporciona acceso a datos del buzón en Office 365 y Outlook.com. El resto del artículo describe la API de REST en este extremo.

Si tiene código que utilice la dirección URL raíz existente https://outlook.office365.com/api/{version}/{user_context}, su código continuará funcionando durante un tiempo para Office 365, pero debería plantearse cambiar a la nueva URL raíz.

Importante

Para un rendimiento óptimo, al realizar una solicitud de REST utilizando la nueva URL raíz, agregue un encabezado x-AnchorMailbox y configúrelo para 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í.

Notas para programadores de China

  • Si está desarrollando aplicaciones para Office 365 en China, debe continuar utilizando los extremos de API de Office 365 para China.

  • Si está creando aplicaciones para Outlook.com en China, pruebe el extremo de autenticación v2 y utilice el siguiente nuevo extremo de REST de Outlook: https://outlook.office.com/api/{version}/{user_context}.

Versiones de la API admitidas

{version} representa la versión de la API de REST de Outlook en la URL raíz indicada. Puede especificar uno de los siguientes valores:

  • v1.0. Es la versión más antigua en estado de disponibilidad general (GA) y se puede utilizar en lel código de producción. Un ejemplo de URL es http://outlook.office.com/api/v1.0/me/events.

  • v2.0. Esta versión también está en estado GA y se puede usar en código de producción. Un ejemplo de URL es http://outlook.office.com/api/v2.0/me/events. Esta versión incluye cambios que pueden romper la v1.0, y conjuntos de API adicionales que han madurado y se han promovido del estado de versión preliminar al de GA.

  • beta. Esta versión se encuentra en el estado de versión preliminar y no debe usarse en código de producción. Un ejemplo de URL es http://outlook.office.com/api/beta/me/events. Esta versión incluye las más recientes API en estado de GA, así como conjuntos de API adicionales que están en versión preliminar y que pueden cambiar antes de la versión final.

La mayoría de las operaciones de REST en la API de REST de Outlook se admiten y se comportan como se ha descrito en las distintas versiones que se mencionan arriba.

Usuario objetivo

Con la excepción de la API de REST de foto del usuario, {user_context} es el usuario con la sesión iniciada actualmente, ya que las solicitudes de la API de REST de Outlook siempre se realizan en nombre del usuario actual.

Para la API de REST de foto del usuario, {user_context} puede ser el usuario con la sesión iniciada o un usuario especificado mediante su ID de usuario.

Independientemente del conjunto de la API de REST de Outlook, puede especificar {user_context} en solicitudes de REST de una de las siguientes maneras:

  • Con el acceso directo me: /api/{version}/me. La URL raíz pasa a ser https://outlook.office.com/api/{version}/me.

  • Con el formato users/{upn} para pasar el UPN o una dirección proxy del usuario con la sesión iniciada, como por ejemplo: /api/v1.0/users/sadie@contoso.com. En este ejemplo, la URL raíz sería https://outlook.office.com/api/v1.0/users/sadie@contoso.com.

La utilización de una u otra es una cuestión de preferencia. En respuestas del servidor, el contexto del usuario se identifica con este formato: /api/v1.0/users('sadie@contoso.com')

Acceder a un elemento de una colección

La API de REST de Outlook admite dos formas de especificar un elemento de una colección de entidades. Se evalúan de manera idéntica, por lo que la utilización de una u otra es una cuestión de preferencia.

  • En el segmento de la URL después de la colección, por ejemplo: /api/{version}/me/events/AAMkAGI3...

  • Entre paréntesis, como una cadena entrecomillada, por ejemplo: /api/{version}/me/events('AAMkAGI3...')

Utilizar una biblioteca cliente para acceder a la API de REST de Outlook

Las bibliotecas cliente de la API de Office 365 facilitan la interacción con la API de REST:

Ayudan a administrar tokens de autenticación y simplifican el código necesario para consultar y consumir datos en Office 365.

Apagado del extremo en versión preliminar anterior

Si ya está usando https://outlook.office.com/api o https://outlook.office365.com/api como URL raíz
para acceder a la API de REST de Outlook, esta desaprobación de algo obsoleto no le afecta. Siga leyendo si todavía está usando el extremo en versión preliminar anterior https://outlook.office365.com/ews/odata.

La API de REST de Outlook pasó de su versión preliminar inicial a la disponibilidad general de la v1.0 en octubre de 2014. Para completar esta transición, finalmente apagamos el viejo extremo en versión preliminar https://outlook.office365.com/ews/odata el 15 de octubre de 2015.

Requeríamos todas las aplicaciones y servicios con el extremo antiguo https://outlook.office365.com/ews/odata para mover a https://outlook.office.com/api/v1.0 el 15 de octubre de 2015. v1.0 es el extremo con disponibilidad general (GA) mínimo al que pasar para esa fecha.

Alternativamente, puede usar de preferencia el extremo v2.0 en GA (https://outlook.office.com/api/v2.0), o el extremo en versión preliminar (https://outlook.office.com/api/beta) si quiere probar las API más recientes en estado de versión preliminar. Tenga en cuenta que, en general, una API en estado de versión preliminar puede cambiar antes de llegar a su versión final. Si las usa, prepárese para verificar las características de su aplicación y realizar los cambios apropiados. Cuando se completen las API en versión preliminar, también podrá acceder a estas mejoras en un extremo en estado de GA.

Pasos siguientes

Proceda a usar la API de REST de Outlook: