Compartir vía

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

  • 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 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 Microsoft Entra
Microsoft Outlook Evento (reunión del calendario), Mensaje (correo electrónico), Contacto Tipos de evento de Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (reunión) Tipos de evento de Microsoft Teams
OneDrive DriveItem Eventos de Microsoft OneDrive
Microsoft SharePoint List Eventos de Microsoft SharePoint
To Do 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. Use ese tema de asociado para crear suscripciones de eventos para enviar los eventos a cualquiera de los controladores de eventos admitidos que cumplan mejor sus requisitos para procesar los eventos.

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. Necesita el sólido modelo controlado por eventos 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.
  • Debes enrutar eventos a diferentes aplicaciones de bajada, webhooks o servicios de Azure en función de algunas de las 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.
  • Te gusta la compatibilidad de extensibilidad que proporciona CloudEvents. Por ejemplo, si desea rastrear eventos a través de sistemas compatibles, utilice la extensión CloudEvents Seguimiento distribuido. 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

Puede solicitar 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 siguiendo 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

Debe cumplir 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 las instrucciones detalladas para implementar su aplicación se encuentran en la sección ejemplos con instrucciones detalladas, debería 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 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. 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 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

La aplicación debe renovar la 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 de ciclo de vida a los que la aplicación puede 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 no ha renovado la suscripción de Graph API después de que expire, 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, 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 nuevo expirationDateTime, debe ser 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 Explorador de Microsoft Graph API. 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:

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:

Otros vínculos útiles: