Compartir a través de

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. Al suscribirse a estos eventos a través de Azure Event Grid, se crean aplicaciones controladas por eventos que responden a los 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.
  • Enrutar eventos a varios destinos mediante las funcionalidades 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

En la tabla siguiente se enumeran los orígenes de eventos para los que los eventos están disponibles a través de Graph API. Para la mayoría de los recursos, se admiten eventos que anuncian su creación, actualización y eliminación. Para obtener información detallada sobre los recursos para los que se generan eventos para orígenes de eventos, consulte recursos admitidos por las notificaciones de cambios de 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. El tema de asociado se crea automáticamente como parte de la creación de la suscripción de Graph API. 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é debo suscribirme a eventos de orígenes de Microsoft Graph API a través de Event Grid?

Además de suscribirse a eventos de Microsoft Graph API a través de Event Grid, tiene 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 varios destinos mediante una sola suscripción de Graph API y quieres evitar la administración de varias suscripciones de 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.UserCreated 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 conseguirlo utilizando una única suscripción a la Graph API cuando utilices Event Grid como destino de las notificaciones. Para obtener más información, consulta filtrado de eventos y controladores de eventos.
  • La interoperabilidad es importante para ti. Quiere reenviar y controlar eventos de forma estándar mediante Cloud Native Computing Foundation (CNCF) CloudEvents estándar de especificación.
  • 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.
  • Use enfoques probados controlados por eventos adoptados por 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

Cumpla estos requisitos previos generales antes de implementar la aplicación para crear y renovar suscripciones de Microsoft Graph API:

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 se encuentran instrucciones detalladas para implementar la aplicación en la sección ejemplos con instrucciones detalladas , debe leer 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 mediante Event Grid.

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

Al crear una suscripción de Graph API, se crea automáticamente un tema de asociado. Pase la siguiente información en el parámetro notificationUrl para especificar qué tema de asociado se va a crear y asociar a la nueva suscripción de Graph API:

  • Nombre del tema de asociado
  • Nombre del grupo de recursos en el que se crea 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,Created",
    "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": "2024-03-31T00:00:00Z",
    "clientState": "secretClientValue"
}
  • changeType: el tipo de cambios de recursos para los que desea recibir eventos. Valores válidos: Updated, Deleted y Created. 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>. La ubicación (también conocida como región de Azure) name se puede obtener al ejecutar el comando az account list-locations. 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 que se usa para definir el tema del asociado al que se envían eventos microsoft.graph.subscriptionReauthorizationRequired. 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 usa Event Grid como destino para eventos de ciclo de vida. En ese caso, el tema del asociado debe ser el mismo que el especificado en notificationUrl.
  • Recurso: el recurso que genera eventos que anuncian cambios de estado.
  • expirationDateTime: la hora de expiración en la que expira la suscripción y el flujo de eventos se detienen. Debe ajustarse al formato especificado en Request for Change (RFC) 3339. Debe especificar una hora de expiración que esté dentro de longitud máxima de suscripción permitida por tipo de recurso.
  • estado del cliente. Esta propiedad es opcional. Se usa para comprobar las llamadas a la aplicación del controlador de eventos durante la entrega de eventos. 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 agregar la propiedad lifecycleNotificationUrl, debe eliminar la suscripción existente y crear 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 admite eventos de notificaciones del ciclo de vida a los que las aplicaciones pueden suscribirse. Actualmente, todos los tipos de recursos de Microsoft Graph API admiten el microsoft.graph.subscriptionReauthorizationRequired, que se envía cuando se produce alguna de las condiciones siguientes:

  • El token de acceso está a punto de expirar.
  • La suscripción de 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. Haga referencia al mismo tema de asociado que se usó en la suscripción expirada siempre que haya expirado durante 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, debe especificar otro nombre de tema de 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

Al recibir un evento de microsoft.graph.subscriptionReauthorizationRequired, la aplicación debe renovar la suscripción de Graph API mediante estas acciones:

  1. Si proporcionó un secreto de cliente en la propiedad clientState al crear la suscripción de Graph API, ese secreto de cliente incluido con el evento. 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. Encontrará más información en la próxima sección muestras con instrucciones detalladas.

  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": "2024-04-30T11:00:00.0000000Z"
}

      La renovación podría producir un error si la aplicación ya no está autorizada para acceder al recurso. A continuación, es posible que sea necesario que la aplicación obtenga un nuevo token de acceso para volver a autorizar correctamente 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. Es importante estar preparado para volver a autorizar periódicamente el punto de conexión para actualizar el 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.

Al renovar o volver a autorizar la suscripción de Graph API, se especifica el mismo tema de asociado especificado al crear la suscripción.

Al especificar un valor expirationDateTime nuevo, asegúrese de que es al menos tres horas a partir de 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 obtener ejemplos sobre cómo volver a autorizar la suscripción de Graph API mediante cualquiera de los idiomas admitidos, consulte solicitud de reautorización de la suscripción.

Para obtener ejemplos sobre cómo renovar y volver a autorizar la suscripción de Graph API mediante cualquiera de los idiomas admitidos, consulte 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.
  • Cree una suscripción de Graph API. Para renovar una suscripción, puede llamar a Graph API mediante los fragmentos de código de Cómo renovar una suscripción de Graph API.
  • Obtenga tokens de autenticación para usarlos al llamar a Microsoft Graph API.

Nota:

Es posible crear la suscripción de Graph API mediante el Explorador de Api de Microsoft Graph. 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

Siga estos dos pasos para configurar la recepción de eventos de Microsoft Graph API mediante Event Grid:

  • Last updated on