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

  • Artículo

En este artículo se describen los pasos para suscribirse a eventos publicados por Microsoft Graph API. 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 los recursos admitidos por las notificaciones de cambios de Microsoft Graph API.

Importante

La capacidad de Microsoft Graph API para enviar eventos a Azure Event Grid está actualmente en versión preliminar pública. Si tiene preguntas o necesita ayuda, envíe un correo electrónico a ask-graph-and-grid@microsoft.com.

Origen de evento de Microsoft Tipos de eventos disponibles
Microsoft Entra ID Tipos de eventos de Microsoft Entra
Microsoft Outlook Tipos de evento de Microsoft Outlook
Conversaciones de grupo de Microsoft 365
Equipos de Microsoft Tipos de evento de Microsoft Teams
Microsoft SharePoint y OneDrive
Microsoft SharePoint
Alertas de seguridad
Conversaciones de Microsoft
Impresión universal de Microsoft

Importante

Si no estás familiarizado con la característica Eventos de asociado, consulta Introducción a 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 la capacidad de suscribirte a eventos de Microsoft Graph API mediante Event Grid, tienes otras opciones a través de las cuales puedes recibir notificaciones similares (no eventos). Considera la posibilidad de usar Microsoft Graph API para entregar eventos a Event Grid si tienes al menos uno de los siguientes requisitos:

  • Va a desarrollar una solución controlada por eventos que necesita eventos de Microsoft Entra ID, Outlook, Teams, etc. para reaccionar ante los cambios de recursos. Necesitas el modelo de eventos sólido y las 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.
  • Es necesario enrutar eventos a diferentes aplicaciones de bajada, webhooks o servicios de Azure en función de algunas de las propiedades del evento. Por ejemplo, es posible 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 la retirada de los usuarios. También puede enviar Microsoft.Graph.UserUpdated eventos a otra aplicación que sincronice la información de contactos, por ejemplo. 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 el estándar de especificación CloudEvents de CNCF.
  • Te gusta la compatibilidad de extensibilidad que proporciona CloudEvents. Por ejemplo, si desea realizar un seguimiento de eventos en sistemas compatibles, use la extensión CloudEvents Distributed Tracing. Obtén más información sobre más extensiones de CloudEvents.
  • Quieres usar 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 SDK de Microsoft Graph API y siga los pasos descritos en los vínculos a ejemplos proporcionados en esta sección. Consulte Idiomas admitidos para el SDK de Microsoft Graph API para obtener compatibilidad con el SDK disponible.

Requisitos previos generales

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

  • Familiarícese con los pasos generales para suscribirse a eventos de asociados. Como se describe en ese artículo, antes de crear una suscripción de Graph API, debe seguir las instrucciones de:

  • Tener conocimientos prácticos sobre las notificaciones de Microsoft Graph API. Como parte del aprendizaje, puede usar el Explorador de Graph API para crear suscripciones de Graph API.

  • Descripción de los conceptos de eventos de asociados.

  • Identifique el recurso de Microsoft Graph API desde el que desea recibir eventos de cambio de estado del sistema. Consulte Notificaciones de cambios de Microsoft Graph API para obtener más información. Por ejemplo, para realizar el seguimiento de los cambios en los usuarios de Microsoft Entra ID, debe usar el recurso de usuario . Use el grupo para realizar el seguimiento de los cambios en los grupos de usuarios.

  • Tener una cuenta de administrador de inquilinos en un inquilino de Microsoft 365. Puede obtener un inquilino de desarrollo de forma gratuita si se une al Programa para desarrolladores de Microsoft 365.

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 adicional e 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 del 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. Muestran ejemplos para crear una suscripción para recibir eventos de todos los usuarios de un inquilino de Id. de Microsoft Entra 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 los 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 microsoft.graph.subscriptionReauthorizationRequiredse 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 usa Event Grid como destino para los 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: 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 RFC 3339. Debe especificar una hora de expiración que esté dentro de la 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 lifecycleNotificationUrl propiedad 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.

Nota:

Si la aplicación usa el encabezado x-ms-enable-features con la solicitud para crear una suscripción de Graph API durante la versión preliminar privada, debe quitarlo ya que ya no es necesario.

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

La aplicación debe renovar una suscripción de Graph API antes de que expire para evitar detener el flujo de eventos. Para ayudarle a automatizar el proceso de renovación, Microsoft Graph API admite eventos de notificaciones del ciclo de vida a los que la aplicación puede suscribirse. Actualmente, todos los tipos de recursos de Microsoft Graph API admiten 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 ha revocado los permisos de la aplicación para leer un recurso.

Si no ha renovado la suscripción de Graph API después de que haya expirado, debe crear una nueva suscripción de Graph API. Puede hacer referencia al mismo tema de asociado que 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, deberá 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 microsoft.graph.subscriptionReauthorizationRequired evento, 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. Se proporciona más información en la sección de ejemplos siguientes 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 /reauthorize acción 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. El token de acceso puede expirar 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 renovará la suscripción. Sin embargo, la renovación de la suscripción también volverá 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, debe ser al menos tres horas a partir de la hora actual. De lo contrario, la aplicación puede recibir microsoft.graph.subscriptionReauthorizationRequired eventos 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 actualización de la solicitud de suscripció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 anterior.
  • 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
    • GraphAPIController contiene código de ejemplo para crear, eliminar y renovar una suscripción de Graph API. Debe usarse junto con la aplicación de ejemplo de Java anterior.
  • Ejemplo de NodeJS.

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. Pasos siguientes para obtener más información.

Importante

¿Necesita código de ejemplo para otro lenguaje o tiene preguntas? Envíenos un correo electrónico a la dirección ask-graph-and-grid@microsoft.com.

Pasos siguientes

Siga las instrucciones de los dos pasos siguientes para completar la configuración para recibir eventos de Microsoft Graph API mediante Event Grid:

  • Active el tema de asociado creado como parte de la creación de Microsoft Graph API.
  • Suscríbase a eventos mediante la creación de una suscripción de eventos al tema de asociado.

Otros vínculos útiles: