Usar la API de REST de Outlook (versión 2.0)
Se aplica a: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com
Nota
Utilizar Microsoft Graph para crear escenarios más ricos para los servicios de Microsoft 365 incluido Outlook. Descubra cómo realizar una transición a la API de REST de Outlook basada en Microsoft Graph.
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:
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.
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:
- Portal de registro de aplicaciones de Microsoft
- Ámbitos de autorización v2
- Extremos de autenticación v2
- Bibliotecas ADAL v2
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 serhttps://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/beta/users/sadie@contoso.com
. En este ejemplo, la URL raíz seríahttps://outlook.office.com/api/beta/users/sadie@contoso.com
.Con el formato
users/{AAD_userId@AAD_tenandId}
, utilizando la ID de usuario y la id. de la cuenta empresarial en Azure Active Directory. En este ejemplo,users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77
la URL raíz seríahttps://outlook.office.com/api/beta/users/ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77
.
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: users/{AAD_userId@AAD_tenandId}
.
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:
- Referencia de la API de correo
- Referencia de la API de calendario
- Referencia de la API de contactos
- API de REST de tareas
- Referencia de recursos para las API de REST de correo, calendario, contactos y tareas
- Referencia de la API de personas
- Referencia de la API de extensiones de datos
- Referencia de la API de propiedades extendidas
- Referencia de la API de REST de notificaciones de inserción
- Referencia de la API de REST de notificaciones de transmisión por secuencias (versión preliminar)
- Referencia de la API de REST de foto del usuario
- Solicitudes de REST de Outlook por lotes