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

  • Статья

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

Источник событий Майкрософт Ресурсы Доступные типы событий
Microsoft Entra ID Пользователь, Группа Типы событий Microsoft Entra
Microsoft Outlook Событие (собрание в календаре), Сообщение (электронная почта), Контакт Типы событий в Microsoft Outlook
Microsoft Teams ChatMessage, CallRecord (собрание) Типы событий в Microsoft Teams
OneDrive DriveItem События Microsoft OneDrive
Microsoft SharePoint Список События Microsoft SharePoint
Необходимо выполнить задача Список дел События Microsoft ToDo
Оповещения безопасности Alert События оповещений системы безопасности Майкрософт
Облачная печать Определение задачи "Принтер", "Определение задачи печати" События Microsoft Cloud Printing
Microsoft Conversations Разговор События групповой беседы Microsoft 365

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

Внимание

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

Почему следует подписаться на события из источников 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, если в качестве места назначения уведомлений использовать Сетку событий. Дополнительные сведения см. в разделах о фильтрации событий и обработчиках событий.
  • Вам важно взаимодействие. Вы хотите пересылать и обрабатывать события стандартным способом с помощью спецификации Cloud Native Computing Foundation (CNCF) CloudEvents .
  • Вам нужна поддержка расширяемости, которую предоставляет 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, необходимо удалить существующую подписку и создать новую подписку, указывающую свойство во время создания подписки.

После создания подписки 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
  • Пример NodeJS.

Внимание

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

Внимание

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

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

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

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