Comparar los extremos de Microsoft Graph y la API de REST de Outlook

  • Artículo

Las API REST de Outlook están disponibles tanto en Microsoft Graph como en el punto de conexión de la API de Outlook (https://outlook.office.com/api). Por lo general, las API proporcionan las mismas funciones y usan los mismos tipos de recursos.

Nota:

Las API de REST de Outlook estan en desuso.

Los puntos de conexión REST de Outlook se retirarán por completo en marzo de 2024. Aplicaciones de migración que se pueden usar en Microsoft Graph. Esto no incluye la audiencia del token de OAuth2 como se describe en Autenticación de una conexión IMAP, POP o SMTP mediante OAuth.

¿Qué punto de conexión debo usar?

Use Microsoft Graph, Outlook REST v2.0 está en su ruta de acceso para retirarse. El punto de conexión de Microsoft Graph le permite acceder a Outlook y le ofrece más servicios y características, incluidos otros servicios de Office 365, Enterprise Mobility + Security y Windows 10. Si se decanta por los puntos de conexión de Microsoft Graph, su aplicación podrá obtener un token de acceso que puede proporcionar acceso a datos de Outlook y de otros recursos, y todo sin tener que realizar varias solicitudes de token.

Diferencias en las características

Hay algunas características que, bien solo están disponibles en el punto de conexión de Outlook, bien están en versión beta en Microsoft Graph.

Nota:

Trabajamos constantemente para integrar en Microsoft Graph todas las características ahora disponibles en el punto de conexión de Outlook. La lista se actualiza, así que recuerde comprobarla frecuentemente.

Característica Diferencia entre los puntos de conexión
Tareas de Outlook El acceso a las tareas de los usuarios en Microsoft Graph está disponible desde la API de To Do
Notificaciones enriquecidas La API de Outlook permite a los desarrolladores solicitar campos específicos que se incluirán en la carga de notificación mediante el parámetro $select. Actualmente, Microsoft Graph solo admite esta característica en el punto de conexión beta y planea lanzarla a la versión 1.0 próximamente.
Notificaciones de streaming La API de Outlook es compatible con notificaciones de emisión en directo en la vista previa en el extremo beta. Microsoft Graph no admite esta característica y no forma parte de la hoja de ruta.

Cambiar de punto de conexión de Outlook a Microsoft Graph

Las API son muy similares en el punto de conexión de Microsoft Graph y en el de Outlook. Sin embargo, hay algunas diferencias que debe conocer, especialmente si va a migrar a Microsoft Graph o a usar los dos puntos de conexión en la misma aplicación.

Versiones de API

La API de Microsoft Graph tiene dos versiones: v1.0 y beta, mientras que Outlook tiene v1.0, v2.0 y beta. Microsoft Graph v1.0 coincide con Outlook v2.0 y Microsoft Graph beta, con Outlook beta.

Ámbitos de OAuth

Aunque los puntos de conexión de Microsoft Graph y Outlook dependen de tokens emitidos por Azure AD y los permisos que se usan son los mismos, la forma en que la aplicación solicita estos permisos difiere un poco para cada punto de conexión.

El punto de conexión de Azure OAuth2 versión 2.0

Las aplicaciones que usen el extremo de Azure AD versión 2.0 para OAuth2 solicitan ámbitos de permiso en el parámetro scope en una solicitud de token o de autenticación.

  • Para Microsoft Graph, las aplicaciones especifican permisos con el prefijo https://graph.microsoft.com/. Por ejemplo, una aplicación puede solicitar el permiso Mail.Read añadiendo https://graph.microsoft.com/Mail.Read en el parámetro scope.
  • Para el extremo de Outlook, las aplicaciones especifican permisos con el prefijo https://outlook.office.com/. Por ejemplo, una aplicación puede solicitar el permiso Mail.Read añadiendo https://outlook.office.com/Mail.Read en el parámetro scope.

Nota:

Si un dominio no se incluye en un ámbito, Microsoft Graph se toma por defecto.

Los tokens emitidos para un punto de conexión no son válidos para el otro. Además, no se pueden mezclar permisos de un extremo con permisos del otro en una única solicitud.

El punto de conexión de Azure AD versión 2.0 solo es compatible con el flujo de credenciales del cliente para el punto de conexión de Microsoft Graph. Las aplicaciones que tienen que usar un token de una sola aplicación con el punto de conexión de Outlook deben usar el extremo de la versión 1.0 de Azure AD.

El punto de conexión de Azure OAuth2 versión 1.0

Las aplicaciones que usen el extremo de Azure AD versión 1.0 especifican los permisos necesarios durante el registro de la aplicación en el Portal de Azure.

  • Para Microsoft Graph, elija la API de Microsoft Graph al agregar los permisos necesarios.
  • Para el extremo de Outlook, elija la API de Office 365 Exchange Online al agregar los permisos necesarios.

Nombres de propiedad de los recursos

Los recursos son en gran medida los mismos entre Microsoft Graph y Outlook. Sin embargo, ambos puntos de conexión abordan el uso de mayúsculas y minúsculas en los nombres de propiedad de manera diferente. En Microsoft Graph, los nombres de propiedad comienzan por minúscula, mientras que en Outlook comienzan por mayúscula. Por lo tanto, la conversión entre ambas solo requiere un cambio de minúscula a mayúscula y viceversa. Los nombres de propiedad que se cambian se especifican en la tabla siguiente.

Por ejemplo, el recurso de mensaje de Microsoft Graph define propiedades como subject, from y receivedDateTime. En el punto de conexión de Outlook, estas propiedades se denominarán Subject, From y ReceivedDateTime.

Nombres de propiedad modificados

Los siguientes nombres de propiedad son diferentes en Microsoft Graph y en Outlook.

Tipo de recurso Propiedad en Microsoft Graph Propiedad en Outlook
contact mobilePhone MobilePhone1

Seguimiento de cambios (sincronización)

Dos puntos de conexión admiten colecciones de consultas para cambios relativos a un estado de sincronización. Aunque la funcionalidad es la misma, los métodos son ligeramente diferentes.

En el punto de conexión de Microsoft Graph, los cambios se consultan usando consultas delta. Esto se implementa como una función delta en la colección.

En el punto de conexión de Outlook, los cambios se consultan agregando un encabezado a las consultas de la colección de recursos normales.

Procesamiento por lotes

Lo dos puntos de conexión admiten lotes hasta de 20 solicitudes independientes en una solicitud HTTP.

Procesamiento por lotes de Microsoft Graph codifica varias solicitudes API en un cuerpo JSON con un tipo de contenido de application/json.

Además del formato de cuerpo JSON, el procesamiento por lotes del punto de conexión de Outlook también es compatible con un formato de cuerpo de varias partes con un tipo de contenido de multipart/mixed.

Ejemplo: recuperación de un mensaje

Echemos un vistazo a un sencillo ejemplo. En este escenario, una aplicación web solicita una lista de mensajes de la bandeja de entrada del usuario.

Microsoft Graph

En primer lugar, la aplicación pide al usuario que inicie sesión para autorizar la operación. Dado que la aplicación usa el ámbito de Microsoft Graph Mail.Read, la dirección URL de autorización es parecida a la siguiente:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+Mail.Read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Cuando la aplicación tenga un token de acceso, envía la siguiente solicitud:

GET https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject,from,receivedDateTime,isRead
Accept: application/json
Authorization: Bearer <token>

El servidor devuelve la siguiente respuesta:

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('b63d5fb9-4f43-44c4-8f9d-fd0727842876')/mailFolders('inbox')/messages(subject,from,receivedDateTime,isRead)",
  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/mailfolders/inbox/messages?$top=1&$select=subject%2cfrom%2creceivedDateTime%2cisRead&$skip=1",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "id": "AAMkAGI2...",
      "receivedDateTime": "2015-11-03T03:21:04Z",
      "subject": "Scrum",
      "isRead": false,
      "from": {
        "emailAddress": {
          "name": "user0TestUser",
          "address": "user0@contoso.com"
        }
      }
    }
  ]
}

Outlook

En primer lugar, la aplicación pide al usuario que inicie sesión para autorizar la operación. Dado que la aplicación usa el ámbito de Outlook https://outlook.office.com/Mail.Read, la dirección URL de autorización es parecida a la siguiente:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?scope=openid+https%3A%2F%2Foutlook.office.com%2Fmail.read&response_type=code&client_id=<SOME GUID>&redirect_uri=<REDIRECT URL>

Cuando la aplicación tenga un token de acceso, envía la siguiente solicitud:

GET https://outlook.office.com/api/v2.0/me/mailfolders/inbox/messages?$top=1&$select=Subject,From,ReceivedDateTime,IsRead
Accept: application/json
Authorization: Bearer <token>

El servidor devuelve la siguiente respuesta:

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "@odata.nextLink": "https://outlook.office.com/api/v2.0/$metadata#Me/MailFolders('inbox')/Messages(Subject,From,ReceivedDateTime,IsRead)",
  "value": [
    {
      "@odata.etag": "W/\"CwAAABYAAACd9nJ/tVysQos2hTfspaWRAAD8ujHV\"",
      "Id": "AAMkAGI2...",
      "ReceivedDateTime": "2015-11-03T03:21:04Z",
      "Subject": "Scrum",
      "IsRead": false,
      "From": {
        "EmailAddress": {
          "Name": "user0TestUser",
          "Address": "user0@contoso.com"
        }
      }
    }
  ]
}