Compartir a través de

Notificaciones de cambios para recursos de Outlook en Microsoft Graph

  • Artículo

Microsoft Graph API le permite suscribirse a los cambios en un recurso(incluida la creación, actualización o eliminación del recurso) y recibir notificaciones a través de webhooks. Una suscripción especifica los tipos deseados de cambios que se van a supervisar para un recurso específico e incluye una dirección URL para que un punto de conexión reciba notificaciones de esos cambios.

Configurar una suscripción reduce la sobrecarga que supondría tener que consultar y comparar recursos para deducir los cambios. Opcionalmente, puede especificar en la solicitud de suscripción para cifrar e incluir como parte de una notificación los datos de recursos que han cambiado, guardando una llamada API posterior independiente para obtener la carga del recurso.

Hay un límite máximo de 1000 suscripciones activas para los recursos de Outlook por buzón para todas las aplicaciones. Puede suscribirse a los cambios en los contactos, eventos o mensajes del buzón.

Suscribirse a cambios en contactos, calendario o correo

Para suscribirse a las notificaciones de cambios de los recursos de Outlook, cree primero una suscripción.

Los siguientes recursos de Outlook admiten suscripciones con o sin datos de recursos en la carga útil notificación de cambios.

Crear una suscripción

Para crear una suscripción, especifique el recurso de Outlook y el tipo de cambios (creación, actualización o eliminación) para los que desea recibir notificaciones. Vea un ejemplo.

Solicitar permisos

Crear y administrar (obtener, actualizar y eliminar) una suscripción requiere un ámbito de lectura para el recurso. Por ejemplo, para obtener notificaciones de cambio de mensajes, la aplicación necesita el permiso Mail.Read. Las notificaciones de cambio de Outlook admiten ámbitos de permisos delegados y de aplicación. Tenga en cuenta las siguientes limitaciones:

  • El permiso delegado es compatible con la suscripción a los elementos en las carpetas que se encuentran solo en el buzón del usuario que ha iniciado sesión. Por ejemplo, no puede usar el permiso delegado Calendars.Read para suscribirse a eventos en el buzón de otro usuario.

  • Para suscribirse y cambiar las notificaciones de eventos, contactos o mensajes de Outlook en carpetas compartidas o delegadas:

    • Use los permisos de aplicación correspondientes para suscribirse a los cambios de los elementos de una carpeta o un buzón de cualquier usuario del espacio empresarial.
    • No use los permisos de uso compartido de Outlook (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared y sus homólogos de lectura y escritura), ya que no admiten la suscripción a notificaciones de cambios en elementos de carpetas compartidas o delegadas.

En función del recurso, use el permiso con privilegios mínimos especificado en la tabla siguiente para llamar a esta API.

Recurso Rutas de acceso de recursos compatibles Delegado (cuenta profesional o educativa) Delegado (cuenta de Microsoft personal) Aplicación
contacto Cambios en todos los contactos personales en el buzón de un usuario:
/me/contacts
/users/{id}/contacts
Cambios en los contactos de contactFolder de un usuario:
/users/{id}/contactFolders/{id}/contacts		 Contacts.Read Contacts.Read Contacts.Read
event Cambios en todos los eventos del buzón de un usuario:
/me/events
/users/{id}/events		 Calendars.Read Calendars.Read Calendars.Read
message Cambios en todos los mensajes de un buzón de usuario:
/me/messages
/users/{id}/messages
Cambios en los mensajes de mailFolder de un usuario:
/users/{id}/mailFolders/{id}/messages		 Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read Mail.ReadBasic, Mail.Read

Incluir datos de recursos en la carga de notificación

Para que los datos de recursos se incluyan en una notificación de cambio, debe especificar las siguientes propiedades, además de las que normalmente se incluyen al crear una suscripción:

  • includeResourceData: establezca esta propiedad en true para solicitar explícitamente datos de recursos.

  • resource: esta propiedad especifica la dirección URL del recurso. Asegúrese de usar el parámetro de consulta $select para especificar explícitamente las propiedades de recursos de Outlook que se incluirán en la carga útil de notificación.

    Nota:

    No incluir en la URL $top, $skip, $orderby, $select=Body,UniqueBody ni $expand que no sean singleValueExtendedProperties o multiValueExtendedProperties.

  • encryptionCertificate: esta propiedad contiene solo la clave pública que Microsoft Graph usa para cifrar los datos de recursos. Mantenga la clave privada correspondiente endescifrar el contenido.

  • encryptionCertificateId: esta propiedad es su propio identificador para el certificado. Utilice este ID para hacer coincidir en cada notificación de cambio qué certificado utilizar para el descifrado.

Consulte un ejemplo para suscribirse a las notificaciones de cambio con datos de recursos para el recurso mensaje.

Refinar las condiciones de una notificación

Puede restringir aún más las condiciones de una notificación utilizando el parámetro de consulta $filter. Consulte un ejemplo.

Una aplicación común de $filter es recibir una notificación cuando se produce un cambio en una propiedad de recurso específica. Por ejemplo, puede usar $filter para suscribirse a mensajes no leídos en una carpeta (la propiedad isRead es false) e incluir todos los tipos de cambio:

  • Un mensaje agregado o marcado como no leído en la carpeta activaría una notificación Created.
  • Leer un mensaje o marcarlo como leído en la carpeta desencadenaría una notificación Deleted.
  • Un cambio en cualquier propiedad, que no sea isRead, de un recurso messageen la carpeta desencadenaría una notificación de Updated.

Si no usa al $filter crear la suscripción:

  • Agregar un mensaje a la carpeta resultaría en una notificación Created.
  • Leer un mensaje de la carpeta, marcar el mensaje como leído o cambiar cualquier otra propiedad de mensaje de un mensaje de esa carpeta resultaría en una notificación Updated.
  • Eliminar el mensaje resultaría en una notificación Delete.

Suscribirse a las notificaciones del ciclo de vida

Los recursos de mensajes, contacto, y eventos de Outlook también admiten la suscripción a las notificaciones del ciclo de vida. Las notificaciones del ciclo de vida son necesarias en caso de que la aplicación quite sus suscripciones o se pierdan algunas notificaciones de cambios. Las aplicaciones deben implementar la lógica para detectar la pérdida y recuperarse de la misma, y para reanudar un flujo continuo de notificaciones de cambio. Para obtener más información, consulte suscribirse a las notificaciones del ciclo de vida.

Realizar un seguimiento de la duración de la suscripción

Asegúrese de extender una suscripción antes de que expire. La duración máxima de una suscripción sin datos de recursos de Outlook se puede encontrar en la tabla de duración de la suscripción.

Si pierde el permiso concedido anteriormente para una suscripción y la suscripción expira mientras tanto, vuelva a solicitar el permiso para crear una nueva suscripción.

Recibir cargas de notificación

En función de la suscripción, las notificaciones pueden incluir datos de recursos. Las suscripciones con datos de recursos permiten obtener la carga de recursos junto con la notificación, lo que evita la sobrecarga de una llamada API independiente para obtener los datos de recursos modificados.

Recepción de notificaciones con datos de recursos

A continuación se muestra un ejemplo de la carga de una notificación con datos de recursos de un recurso mensaje. Las propiedades resource y resourceData corresponden a la instancia del mensaje que desencadenó la notificación. Use la propiedad encryptedContent para descifrar los datos del recurso.

{
    "value": [
      {
        "subscriptionId": "dfd11b2f-8222-4189-9545-4205c95d6235",
        "subscriptionExpirationDateTime": "2021-12-31T16:16:44.9907405+05:30",
        "changeType": "created",
        "resource": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
        "clientState": "<<--SpecifiedClientState-->>",
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
        "encryptedContent": {
          "data": "<<--EncryptedContent-->>",
          "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
          "dataSignature": "Qw/9ubWeUYJPWWXvNiGgct2FkNG2MXTRm/BLUpJM66k=",
          "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
          "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "resourceData": {
          "@odata.type": "#microsoft.graph.message",
          "@odata.id": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
          "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUR8n\"",
          "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA="
        }
      }
    ]
    "validationTokens": ["<<--ValidationTokens-->>"]
}

Para obtener más información sobre cómo validar tokens y descifrar la carga, consulte Configurar notificaciones de cambio que incluyan datos de recursos.

A continuación se muestra un ejemplo de una carga de notificación descifrada. La carga descifrada se ajusta al esquema de Outlook message. La carga es similar a la que devuelve una operación GET message. Sin embargo, la carga de notificación contiene solo las propiedades especificadas con un parámetro $select en la propiedad resource de la suscripción. Las cargas de notificación para otros recursos de Outlook, como contacto y evento siguen sus esquemas respectivos.

{
    "receivedDateTime@odata.type":"#DateTimeOffset",
    "receivedDateTime":"2021-12-30T10:53:35Z",
    "subject":"TEST MESSAGE FOR RICH NOTIFICATIONS",
    "bodyPreview":"Hello,\r\n\r\nWhat\u2019s up?\r\n\r\nThanks\r\nMegan",
    "importance@odata.type":"#microsoft.graph.importance",
    "importance":"normal",
    "from": {
        "@odata.type":"#microsoft.graph.recipient",
        "emailAddress": {
            "@odata.type":"#microsoft.graph.emailAddress",
            "name":"Megan Brown",
            "address":"Megan.Brown@microsoft.com"
        }
    }
}

Recibir notificaciones sin datos de recursos

Las notificaciones sin datos de recursos le proporcionarán suficiente información para realizar llamadas GET para obtener el recurso. Las suscripciones para notificaciones sin datos de recursos no requieren un certificado de cifrado, ya que los datos de recursos reales no se envían.

En el ejemplo siguiente se muestra la carga útil de una notificación que corresponde a un recurso de Outlook mensaje. Incluye las propriedades resource y resourceData, que representan el recurso que desencadenó la notificación. Use las propiedades de resource y @odata.id para realizar llamadas a Microsoft Graph y obtener la carga del recurso.

Nota:

Las llamadas GET siempre devuelven el estado actual del recurso. Si se cambia el recurso entre el momento en que se envía la notificación y el momento en que se recupera el recurso, la operación devuelve el estado del recurso en la recuperación.

"value": [
 {
   "subscriptionId": "c6126aa3-0ed8-412f-a988-71e6cee627c4",
   "subscriptionExpirationDateTime": "2022-01-02T03:12:18.2257768+05:30",
   "changeType": "created",
   "resource": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIxAAA=",
   "resourceData": {
     "@odata.type": "#Microsoft.Graph.Message",
     "@odata.id": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIAAA=",
     "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUUXn\"",
     "id": "AAMkAGUwNjQ4ZjIxAAA="
   },
   "clientState": "<<--SpecifiedClientState-->>",
   "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
 }
]

Ejemplos

Ejemplo 1: Crear una suscripción para obtener notificaciones de cambios sin datos de recursos cuando el usuario recibe un mensaje nuevo

En el ejemplo siguiente se solicita una notificación para un mensaje que se crea en el buzón del usuario.

Solicitud

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "expirationDateTime": "2021-07-07T21:42:18.2257768+00:00",
    "clientState": "secretClientState"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "5522bd62-7c96-4530-85b0-00b916f6151a",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientState",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T21:42:18.2257768Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "notificationUrlAppId": null
}

Ejemplo 2: Creación de una suscripción para obtener notificaciones de cambio con datos de recursos cuando el usuario recibe un mensaje nuevo

En el ejemplo siguiente se suscribe a notificaciones con datos de recursos para un mensaje que se crea en el buzón del usuario. Las propiedades del recurso message que se va a incluir en la carga de notificación se especifican mediante el parámetro de consulta $select.

Solicitud

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "178eec5f-cf3c-4e7e-8a9c-8640deb5b5c5",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Ejemplo 3: Creación de una suscripción para obtener notificaciones de cambio con datos de recursos para un mensaje basado en una condición

En el ejemplo siguiente se suscribe a notificaciones con datos de recursos para un mensaje que se crea en la carpeta Borradores, que contiene uno o varios datos adjuntos y de importancia alta.

Solicitud

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "239dbc5f-cf3c-4e7e-8c9c-3340abc5b5c5",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-20T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

Contenido relacionado