Получение событий изменения API Microsoft Graph через Сетка событий Azure (предварительная версия)

  • Статья

В этой статье рассказывается, как подписаться на события, опубликованные API Microsoft Graph. В следующей таблице перечислены источники событий, для которых события доступны через API Graph. Для большинства ресурсов поддерживаются события, объявляющие о его создании, обновлении и удалении. Подробные сведения о ресурсах, для которых создаются события для источников событий, см . в поддерживаемых ресурсах уведомлениями об изменениях API Microsoft Graph.

Важно!

Возможность API Microsoft Graph отправлять события в Сетка событий Azure в настоящее время находится в общедоступной предварительной версии. Если у вас есть вопросы или нужна поддержка, отправьте нам ask-graph-and-grid@microsoft.comсообщение по электронной почте.

Источник событий Майкрософт Доступные типы событий
ИД Microsoft Entra Типы событий Microsoft Entra
Microsoft Outlook Типы событий в Microsoft Outlook
Беседы группы Microsoft 365
Microsoft Teams Типы событий в Microsoft Teams
Microsoft SharePoint и OneDrive
Microsoft SharePoint
Оповещения безопасности
Microsoft Conversations
Универсальная печать Майкрософт

Важно!

Если вы не знаете, как работают события партнеров, см. раздел Общие сведения о событиях партнеров.

Почему следует подписаться на события из источников API Microsoft Graph через сетку событий?

Помимо возможности подписываться на события API Microsoft Graph через Сетку событий доступны и другие варианты, с помощью которых можно получать аналогичные уведомления (не события). Используйте API Microsoft Graph для доставки событий в Сетку событий, если у вас выполняется хотя бы одно из следующих условий:

  • Вы разрабатываете решение на основе событий, которое требует событий от идентификатора Microsoft Entra, Outlook, Teams и т. д. для реагирования на изменения ресурсов. Вам нужна надежная модель обработки событий и возможности публикации и подписки, предоставляемые Сеткой событий. Общие сведения о Сетке событий см. в разделе Основные понятия сетки событий.
  • Вы хотите использовать Сетку событий для маршрутизации событий в несколько мест назначений с помощью одной подписки API Graph и хотите избежать управления несколькими подписками API Graph.
  • Необходимо перенаправить события в различные подчиненные приложения, веб-перехватчики или службы Azure в зависимости от некоторых свойств в событии. Например, может потребоваться маршрутизировать типы событий, такие как Microsoft.Graph.UserCreated и Microsoft.Graph.UserDeleted специализированное приложение, которое обрабатывает подключение и отключение пользователей. Также может потребоваться отправить Microsoft.Graph.UserUpdated события другому приложению, которое синхронизирует сведения о контактах, например. Это можно делать с одной подпиской API Graph, если в качестве места назначения уведомлений использовать Сетку событий. Дополнительные сведения см. в разделах о фильтрации событий и обработчиках событий.
  • Вам важно взаимодействие. Вы хотите перенаправлять и обрабатывать события стандартным способом с помощью стандарта спецификации CloudEvents CNCF.
  • Вам нужна поддержка расширяемости, которую предоставляет CloudEvents. Например, если вы хотите отслеживать события в совместимых системах, используйте распределенную трассировку расширения CloudEvents. Узнайте больше и о других расширениях CloudEvents.
  • Вы хотите использовать подходы на основе событий, проверенные на практике и принятые в этой сфере.

Включение событий API Graph для потоков в раздел партнера

Вы запрашиваете API Microsoft Graph для пересылки событий в партнерский раздел сетки событий, создав подписку API Graph с помощью пакетов SDK API Microsoft Graph и выполнив действия, описанные в ссылках на примеры, приведенные в этом разделе. Сведения о доступной поддержке пакета SDK для API Microsoft Graph см. на поддерживаемых языках.

Общие предварительные требования

Перед реализацией приложения перед созданием и продлением подписок API Microsoft Graph необходимо выполнить следующие общие предварительные требования:

Вы найдете другие предварительные требования, относящиеся к выбранному языку программирования, и среду разработки, которую вы используете в ссылках на примеры API Microsoft Graph, найденные в следующем разделе.

Важно!

Хотя подробные инструкции по реализации приложения находятся в примерах с подробными инструкциями , вы должны прочитать все разделы этой статьи, так как они содержат дополнительные важные сведения, связанные с пересылкой событий API Microsoft Graph с помощью сетки событий.

Создание подписки API Microsoft Graph

При создании подписки API Graph для вас создается партнерский раздел. Вы передаете следующие сведения в уведомлении параметраUrl, чтобы указать, какой раздел партнера нужно создать и связать с новой подпиской API Graph:

  • Имя раздела партнера
  • Имя группы ресурсов, в которой создается раздел партнера
  • регион (расположение)
  • Подписка Azure.

В этих примерах кода показано, как создать подписку API Graph. В них показаны примеры создания подписки для получения событий от всех пользователей в клиенте идентификатора Microsoft Entra ID при создании, обновлении или удалении.

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: тип изменений в ресурсах, события по которым вы хотите получать. Допустимые значения: Updated, Deleted и Created. Можно указать одно или несколько этих значений через запятую.
  • notificationUrl: универсальный код ресурса (URI), используемый для определения темы партнера, в которую отправляются события. Он должен соответствовать следующему шаблону: 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> Расположение (также известное как регион Azure) name можно получить, выполнив команду az account list-location . Не используйте отображаемое имя расположения. Например, не используйте "Западная центральная часть США". Вместо этого используйте westcentralus. 
      az account list-locations
  • lifecycleNotificationUrl: универсальный код ресурса (URI), используемый для определения темы партнера, в которую microsoft.graph.subscriptionReauthorizationRequiredотправляются события. Это событие сигнализирует приложению о том, что срок действия подписки API Graph истекает в ближайшее время. Универсальный код ресурса (URI) следует тому же шаблону, что и notificationUrl , описанное выше, если используется сетка событий в качестве назначения для событий жизненного цикла. В этом случае партнерский раздел должен совпадать с тем, который указан в notificationUrl.
  • ресурс: ресурс, который создает события, которые объявляют изменения состояния.
  • dateDateTime: время окончания срока действия, в течение которого истекает подписка, и поток событий останавливается. Время должно соответствовать формату, указанному в RFC 3339. Необходимо указать время окончания срока действия, допустимое в пределах максимальной длины подписки для каждого типа ресурса.
  • состояние клиента: Это необязательное свойство. Он используется для проверки вызовов приложения обработчика событий во время доставки событий. Дополнительные сведения см. в разделе Свойства подписки API Graph.

Важно!

  • Имя раздела партнера должно быть уникальным в одном регионе Azure. Каждое сочетание идентификатора приложения и арендатора может создавать до 10 уникальных партнерских разделов.

  • При разработке своего решения учитывайте некоторые ограничения службы ресурсов API Graph.

  • Существующие подписки API Graph без lifecycleNotificationUrl свойства не получают событий жизненного цикла. Чтобы добавить свойство lifecycleNotificationUrl, необходимо удалить существующую подписку и создать новую подписку, указывающую свойство во время создания подписки.

Примечание.

Если приложение использует заголовок x-ms-enable-features с запросом на создание подписки API Graph во время частной предварительной версии, ее следует удалить, так как она больше не нужна.

После создания подписки API Graph у вас есть партнерский раздел, созданный в Azure.

Продление подписки НА API Microsoft Graph

Подписка API Graph должна быть продлена приложением до истечения срока действия, чтобы избежать остановки потока событий. Чтобы автоматизировать процесс продления, API Microsoft Graph поддерживает события уведомлений жизненного цикла, на которые может подписаться ваше приложение. В настоящее время все типы ресурсов API Microsoft Graph поддерживают microsoft.graph.subscriptionReauthorizationRequiredто, что отправляется при возникновении любого из следующих условий:

  • Срок действия маркера доступа истекает.
  • Срок действия подписки API Graph истекает.
  • Администратор клиента отозвал разрешения приложения на чтение ресурса.

Если вы не обновили подписку API Graph после истечения срока его действия, необходимо создать новую подписку API Graph. Вы можете ссылаться на тот же раздел партнера, который использовался в подписке с истекшим сроком действия, если срок действия истек менее 30 дней. Если срок действия подписки API Graph истек более 30 дней, вы не сможете повторно использовать существующий раздел партнера. В этом случае необходимо указать другое имя раздела партнера. Кроме того, можно удалить существующий раздел партнера, чтобы создать новый раздел партнера с тем же именем во время создания подписки API Graph.

Продление подписки НА API Microsoft Graph

После получения microsoft.graph.subscriptionReauthorizationRequired события приложение должно продлить подписку API Graph, выполнив следующие действия:

  1. Если вы предоставили секрет клиента в свойстве clientState при создании подписки API Graph, этот секрет клиента включен в событие. Убедитесь, что clientState события соответствует значению, используемому при создании подписки API Graph.

  2. Убедитесь, что приложение имеет допустимый маркер доступа, чтобы выполнить следующий шаг. Дополнительные сведения приведены в следующих примерах с подробными инструкциями .

  3. Вызовите любой из следующих двух API. Если вызов API выполнен успешно, поток уведомлений об изменении возобновляется.

    • /reauthorize Вызовите действие для повторной проверки подлинности подписки без продления срока действия.

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

    • Регулярное действие "продление" для повторной проверки подлинности и продления подписки одновременно.

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

{
   "expirationDateTime": "2024-04-30T11:00:00.0000000Z"
}

      Продление может завершиться ошибкой, если приложение больше не авторизовано для доступа к ресурсу. Для получения нового маркера доступа может потребоваться для успешной повторной проверки подлинности подписки.

Проблемы авторизации не заменяют необходимость продления подписки до истечения срока его действия. Жизненный цикл маркеров доступа и срока действия подписки не совпадают. Срок действия маркера доступа истекает до подписки. Важно подготовиться к регулярной повторной аутентификации конечной точки, чтобы обновить маркер доступа. Повторная проверка подлинности конечной точки не будет обновлять подписку. Однако продление подписки также будет повторно выполнять проверку подлинности конечной точки.

При возобновлении и (или) повторной проверки подлинности подписки API Graph, указанной в той же партнерской статье, указанной при создании подписки.

При указании нового срока действияDateTime должно быть не менее трех часов с текущего времени. В противном случае приложение может получать microsoft.graph.subscriptionReauthorizationRequired события вскоре после продления.

Примеры повторной проверки подлинности подписки API Graph с помощью любого из поддерживаемых языков см . в запросе повторной проверки подлинности подписки.

Примеры возобновления и повторной проверки подлинности подписки API Graph с помощью любого из поддерживаемых языков см. в запросе на обновление подписки.

Примеры с подробными инструкциями

Документация по API Microsoft Graph содержит примеры кода с инструкциями по следующим инструкциям:

  • Настройте среду разработки с определенными инструкциями в соответствии с используемым языком. Инструкции также включают в себя получение клиента Microsoft 365 для целей разработки.
  • Создание подписок API Graph. Чтобы продлить подписку, можно вызвать API Graph с помощью фрагментов кода, описанных выше в разделе "Как обновить подписку API Graph".
  • Получение маркеров проверки подлинности для их использования при вызове API Microsoft Graph.

Примечание.

Вы можете создать подписку API Graph с помощью Обозреватель API Microsoft Graph. Примеры по-прежнему следует использовать для других важных аспектов решения, таких как проверка подлинности и получение событий.

Примеры веб-приложений доступны для следующих языков:

  • Пример C#. Это актуальный пример, включающий создание и продление подписок API Graph и пошаговое руководство по включению потока событий.
  • Пример Java
    • GraphAPIController содержит пример кода для создания, удаления и продления подписки API Graph. Он должен использоваться вместе с примером приложения Java выше.
  • Пример NodeJS.

Важно!

Вам необходимо активировать раздел партнера, созданный в рамках создания подписки API Graph. Для получения событий необходимо также создать подписку на события Сетки событий в веб-приложении. Для этого вы используете URL-адрес, настроенный в веб-приложении, для получения событий в качестве конечной точки веб-перехватчика в подписке на события. Дополнительные сведения см. в следующих шагах .

Важно!

Вам нужен пример кода для другого языка или вопросы? Напишите нам по адресу ask-graph-and-grid@microsoft.com.

Следующие шаги

Выполните инструкции, описанные в следующих двух шагах, чтобы завершить настройку для получения событий API Microsoft Graph с помощью сетки событий:

Другие полезные ссылки: