Recepción de eventos de cambio de Microsoft Graph API a través de Azure Event Grid

Microsoft Graph API proporciona notificaciones de cambios para los recursos en los servicios de Microsoft 365, incluido el identificador de Entra de Microsoft, Teams, Outlook y OneDrive. Suscribiéndote a estos eventos a través de Azure Event Grid, puedes crear aplicaciones orientadas a eventos que respondan a cambios de recursos en tiempo real.

En este artículo se explica lo siguiente:

  • Cree suscripciones de Microsoft Graph API que entreguen eventos a temas de asociados de Azure Event Grid.
  • Administrar los ciclos de vida de la suscripción con renovación automática.
  • Enruta eventos a múltiples destinos utilizando las capacidades de filtrado y enrutamiento de Event Grid.

Azure Event Grid ofrece varias ventajas sobre las suscripciones tradicionales de Microsoft Graph API basadas en webhooks:

  • Enrutamiento simplificado: use una sola suscripción de Graph API para enviar eventos a varios destinos.
  • Filtrado avanzado: enrutar tipos de eventos específicos a diferentes aplicaciones en función de las propiedades del evento.
  • Cumplimiento de estándares: reciba eventos en formato CloudEvents para mejorar la interoperabilidad.
  • Confiabilidad: La lógica de reintentos integrada y las colas de mensajes fallidos garantizan la entrega fiable de eventos.

Orígenes de eventos admitidos

La siguiente tabla enumera las fuentes de eventos para las que puedes obtener eventos a través de Graph API. Para la mayoría de los recursos, Graph API soporta eventos que anuncian su creación, actualización y eliminación. Para información detallada sobre los recursos que generan eventos para las fuentes de eventos, consulte los recursos apoyados por las notificaciones de cambios de la Microsoft Graph API.

Origen de evento de Microsoft Recursos Tipos de eventos disponibles
Microsoft Entra ID Usuario, Grupo Tipos de eventos de ID de Microsoft Entra
Microsoft Outlook Evento (reunión del calendario), Mensaje (correo electrónico), Contacto Tipos de evento de Microsoft Outlook
Equipos de Microsoft ChatMessage, CallRecord (reunión) Tipos de evento de Microsoft Teams
OneDrive DriveItem Eventos de Microsoft OneDrive
Microsoft SharePoint Lista Eventos de Microsoft SharePoint
Tareas Tarea de To Do Eventos de Microsoft ToDo
Alertas de seguridad Alerta Eventos de Alerta de seguridad de Microsoft
Impresión en la nube Impresora, Definición de tarea de impresión Eventos de Impresión en Microsoft Cloud
Conversaciones de Microsoft Conversación Eventos de conversación de grupo de Microsoft 365

Cree una suscripción de Microsoft Graph API para permitir que los eventos de Graph API fluyan a un tema de asociado. Graph API crea automáticamente el tema de socios cuando creas la suscripción. Utilice ese tema asociado para crear suscripciones de eventos y enviar sus eventos a cualquiera de los controladores de eventos admitidos que mejor cumplan sus requisitos para el procesamiento de los eventos.

Importante

Si no está familiarizado con la función Eventos de asociados, consulte la información general sobre eventos de asociados.

¿Por qué suscribirse a eventos de las fuentes de Microsoft Graph API a través de Event Grid?

Además de suscribirte a eventos de Microsoft Graph API a través de Event Grid, tienes otras opciones para recibir notificaciones similares (no eventos). Use Microsoft Graph API para entregar eventos a Event Grid si cumple al menos uno de estos requisitos:

  • Está desarrollando una solución controlada por eventos que usa eventos de Microsoft Entra ID, Outlook o Teams para reaccionar a los cambios de recursos. Necesita el sólido modelo controlado por eventos y funcionalidades de publicación y suscripción que proporciona Event Grid. Para obtener información general sobre Event Grid, consulta Conceptos de Event Grid.
  • Quieres usar Event Grid para enrutar eventos a múltiples destinos usando una única suscripción a Graph API, y quieres evitar gestionar múltiples suscripciones a Graph API.
  • Debe enrutar eventos a diferentes aplicaciones de bajada, webhooks o servicios de Azure en función de algunas propiedades del evento. Por ejemplo, puede que quiera enrutar tipos de eventos como Microsoft.Graph.UserUpdated y Microsoft.Graph.UserDeleted a una aplicación especializada que procese la incorporación y retirada de los usuarios. Por ejemplo, también puede enviar eventos Microsoft.Graph.UserUpdated a otra aplicación que sincronice la información de contactos. Puedes lograr esto usando una única suscripción a Graph API cuando uses Event Grid como destino de notificación. Para obtener más información, consulta filtrado de eventos y controladores de eventos.
  • La interoperabilidad es importante para ti. Quieres reenviar y gestionar eventos de forma estándar utilizando el estándar de especificación CloudEvents de Cloud Native Computing Foundation (CNCF).
  • Valoras el soporte de extensibilidad que proporciona CloudEvents. Por ejemplo, para realizar un seguimiento de eventos en sistemas compatibles, use la extensión CloudEvents Distributed Tracing. Obtenga más información sobre las extensiones de CloudEvents.
  • Utilizas enfoques probados y orientados a eventos que adopta el sector.

Permitir que los eventos de Graph API fluyan hacia su tema de asociado

Solicite a Microsoft Graph API que reenvíe eventos a un tema de asociado de Event Grid mediante la creación de una suscripción de Graph API mediante los Kits de desarrollo de software (SDK) de Microsoft Graph API y siga los pasos descritos en los vínculos a ejemplos proporcionados en esta sección. Consulte idiomas compatibles con el SDK de Microsoft Graph API para obtener soporte técnico del SDK disponible.

Requisitos previos generales

Antes de implementar tu aplicación para crear y renovar suscripciones a Microsoft Graph API, asegúrate de cumplir con estos requisitos generales:

Encontrará otros requisitos previos específicos del lenguaje de programación que prefiera y el entorno de desarrollo que usa en los vínculos de ejemplos de Microsoft Graph API que se encuentran en una sección siguiente.

Importante

Aunque las instrucciones detalladas para implementar tu aplicación se encuentran en la sección de ejemplos con instrucciones detalladas, lee todas las secciones de este artículo, ya que contienen información más importante relacionada con el reenvío de eventos de Microsoft Graph API usando Event Grid.

Creación de una suscripción de Microsoft Graph API

Cuando creas una suscripción a Graph API, el sistema crea un tema asociado para ti. Envía la siguiente información en el parámetro notificationUrl para especificar el tema del partner que se debe crear y asociar con la nueva suscripción a la API de Graph:

  • Nombre del tema de asociado
  • nombre del grupo de recursos para el tema del asociado
  • Región (ubicación)
  • Suscripción de Azure

Estos ejemplos de código muestran cómo crear una suscripción de Graph API. Incluyen ejemplos para crear una suscripción que permita recibir eventos de todos los usuarios de un tenant de Microsoft Entra ID cuando se crean, actualizan o eliminan.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json

{
    "changeType": "Updated,Deleted",
    "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    "resource": "users",
    "expirationDateTime": "2026-08-31T00:00:00Z",
    "clientState": "secretClientValue"
}

  • changeType: el tipo de cambios de recursos para los que desea recibir eventos. Valores válidos: Updated y Deleted (Createdno está soportado por Graph API; consulta la documentación de Graph API para más detalles). Puedes especificar uno o varios de estos valores separados por comas.

  • notificationUrl: un URI que se usa para definir el tema del asociado al que se envían eventos. Debe cumplir el siguiente patrón: EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>. Para obtener la ubicación (también conocida como región de Azure), nameejecuta el az account list-locations comando. No use un nombre para mostrar de ubicación. Por ejemplo, no use Centro-oeste de EE. UU. En su lugar, use westcentralus.

    az account list-locations

  • lifecycleNotificationUrl: un URI utilizado para definir el tema compañero al que microsoft.graph.subscriptionReauthorizationRequired se envían los eventos. Este evento indica a la aplicación que la suscripción de Graph API expira pronto. El URI sigue el mismo patrón que notificationUrl descrito anteriormente si usas Event Grid como destino para eventos del ciclo de vida. En ese caso, el tema del asociado debe ser el mismo que el especificado en notificationUrl.

  • resource: el recurso que genera eventos que anuncian cambios de estado.

  • expirationDateTime: el tiempo de caducidad en el que expira la suscripción y se detiene el flujo de eventos. Debe cumplir con el formato especificado en la Solicitud de Comentarios (RFC) 3339. Debes especificar un tiempo de caducidad que esté dentro de la duración máxima permitida por tipo de recurso.

  • clientState: utiliza esta propiedad opcional para verificar las llamadas a tu aplicación gestora de eventos durante la entrega del evento. Para obtener más información, consulta las propiedades de suscripción de Graph API.

Importante

  • El nombre del tema del asociado debe ser único dentro de la misma región de Azure. Cada combinación de id. de aplicación de inquilino puede crear hasta 10 temas de asociados únicos.

  • Tenga en cuenta ciertos límites de servicio de recursos de Graph API al desarrollar la solución.

  • Las suscripciones de Graph API existentes sin una propiedad lifecycleNotificationUrl no reciben eventos de ciclo de vida. Para añadir la lifecycleNotificationUrl propiedad, elimina la suscripción existente y crea una nueva suscripción que especifique la propiedad durante la creación de la suscripción.

Después de crear una suscripción de Graph API, tiene un tema de asociado creado en Azure.

Renovación de una suscripción de Microsoft Graph API

Renueve la suscripción de Graph API antes de que expire para evitar detener el flujo de eventos. Para ayudar a automatizar el proceso de renovación, Microsoft Graph API soporta eventos de notificación durante el ciclo de vida a los que las aplicaciones pueden suscribirse. Actualmente, todos los tipos de recursos de Microsoft Graph API soportan el microsoft.graph.subscriptionReauthorizationRequired evento, que se envía cuando se produce cualquiera de las siguientes condiciones:

  • El token de acceso está a punto de expirar.
  • La suscripción a Graph API está a punto de expirar.
  • Un administrador de inquilinos revoca los permisos de la aplicación para leer un recurso.

Si la suscripción de Graph API no se renueva después de que expire, cree una nueva suscripción de Graph API. Puede hacer referencia al mismo tema del asociado utilizado en la suscripción expirada, siempre que haya expirado hace menos de 30 días. Si la suscripción de Graph API ha expirado durante más de 30 días, no puede reutilizar el tema de asociado existente. En este caso, debes especificar el nombre de otro tema asociado. Como alternativa, puede eliminar el tema de asociado existente para crear un nuevo tema de asociado con el mismo nombre durante la creación de la suscripción de Graph API.

Cómo renovar una suscripción de Microsoft Graph API

Cuando tu aplicación recibe un microsoft.graph.subscriptionReauthorizationRequired evento, debe renovar la suscripción a Graph API:

  1. Si proporcionaste un secreto de cliente en la propiedad clientState al crear la suscripción a Graph API, el evento incluye ese secreto de cliente. Compruebe que clientState del evento coincide con el valor usado al crear la suscripción de Graph API.

  2. Asegúrese de que la aplicación tiene un token de acceso válido para realizar el paso siguiente. La sección de ejemplos con instrucciones detalladas ofrece más información.

  3. Llame a cualquiera de las dos API siguientes. Si la llamada API se realiza correctamente, el flujo de notificación de cambio se reanuda.

    • Llame a la acción /reauthorize para volver a autorizar la suscripción sin extender su fecha de expiración.

      POST  https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize

    • Realice una acción "renovar" normal para volver a autorizar y renovar la suscripción al mismo tiempo.

      PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-Type: application/json

{
   "expirationDateTime": "2026-09-30T11:00:00.0000000Z"
}

      La renovación podría fallar si la app ya no está autorizada para acceder al recurso. La aplicación podría entonces necesitar obtener un nuevo token de acceso para reautorizar una suscripción.

Los desafíos de autorización no reemplazan la necesidad de renovar una suscripción antes de que expire. Los ciclos de vida de los tokens de acceso y la expiración de la suscripción no son los mismos. Es posible que el token de acceso expire antes de la suscripción. Prepárate para reautorizar tu endpoint regularmente para actualizar tu token de acceso. Volver a autorizar el punto de conexión no renueva la suscripción. Sin embargo, la renovación de la suscripción también vuelve a autorizar el punto de conexión.

Cuando renuevas o reautorizas tu suscripción a Graph API, utiliza el mismo tema asociado que especificaste al crear la suscripción.

Cuando especifiques una nueva fecha de expiración, asegúrate de que sea al menos tres horas desde la hora actual. De lo contrario, es posible que la aplicación reciba eventos microsoft.graph.subscriptionReauthorizationRequired poco después de la renovación.

Para ejemplos de cómo reautorizar tu suscripción a Graph API utilizando cualquiera de los idiomas soportados, consulta solicitud de reautorización de suscripción.

Para ver ejemplos de cómo renovar y reautorizar tu suscripción a Graph API utilizando cualquiera de los idiomas compatibles, consulta solicitud de suscripción de actualización.

Ejemplos con instrucciones detalladas

La documentación de Microsoft Graph API proporciona ejemplos de código con instrucciones para:

  • Configure el entorno de desarrollo con instrucciones específicas según el lenguaje que use. Las instrucciones también incluyen cómo obtener un inquilino de Microsoft 365 con fines de desarrollo.
  • Crea una suscripción a Graph API. Para renovar una suscripción, llama a la Graph API utilizando los fragmentos de código en Cómo renovar una suscripción a la Graph API.
  • Obtenga tokens de autenticación para usarlos al llamar a Microsoft Graph API.

Nota:

Puedes crear tu suscripción a Graph API usando el Microsoft Graph API Explorer. Todavía debe usar los ejemplos para otros aspectos importantes de la solución, como la autenticación y la recepción de eventos.

Los ejemplos de aplicaciones web están disponibles para los siguientes idiomas:

  • Ejemplo en C#. Se trata de un ejemplo actualizado que incluye cómo crear y renovar suscripciones de Graph API y le guía por algunos de los pasos para habilitar el flujo de eventos.
  • Ejemplo de Java
  • Node.js ejemplo.

Importante

Debe activar el tema de asociado que se crea como parte de la creación de la suscripción de Graph API. También debe crear una suscripción de eventos de Event Grid a la aplicación web para recibir eventos. Para ello, usará la dirección URL configurada en la aplicación web para recibir eventos como punto de conexión de webhook en la suscripción de eventos.

Importante

¿Necesita código de ejemplo para otro lenguaje o tiene preguntas? Correo electrónico ask-graph-and-grid@microsoft.com.

Contenido relacionado

Para recibir eventos de Microsoft Graph API a través de Event Grid, completa estos dos pasos:

  • Last updated on