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

API Microsoft Graph предоставляет уведомления об изменениях для ресурсов в службах Microsoft 365, включая идентификатор Microsoft Entra, Teams, Outlook и OneDrive. Подписавшись на эти события с помощью Службы "Сетка событий Azure", вы создаете приложения, управляемые событиями, которые реагируют на изменения ресурсов в режиме реального времени.

В статье описывается выполнение следующих задач:

• Создание подписок API Microsoft Graph, которые предоставляют события в партнерские разделы Службы "Сетка событий Azure".
• Управление жизненным циклом подписки с автоматическим продлением.
• Перенаправляйте события в несколько мест назначения с помощью возможностей фильтрации и маршрутизации Event Grid.

Azure Event Grid предлагает несколько преимуществ по сравнению с традиционными подписками для API Microsoft Graph на основе веб-перехватчиков.

• Упрощенная маршрутизация: используйте одну подписку API Graph для отправки событий в несколько мест.
• Расширенная фильтрация: маршрутизация определенных типов событий в разные приложения на основе свойств событий.
• Соответствие стандартам: получение событий в формате CloudEvents для улучшения взаимодействия.
• Надежность. Встроенная логика повторных попыток и очереди недоставленных писем обеспечивают надежную доставку событий.

Поддерживаемые источники событий

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

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

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

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

• Вы разрабатываете решение на основе событий, которое использует события из идентификатора Microsoft Entra, Outlook или Teams для реагирования на изменения ресурсов. Вам нужна надёжная событие-ориентированная модель и возможности публикации и подписки, которые предоставляет Event Grid. Общие сведения о Сетке событий см. в разделе Основные понятия сетки событий.
• Вы хотите использовать Сетку событий для маршрутизации событий в несколько мест назначений с помощью одной подписки 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 Graph, следуйте инструкциям в следующих статьях:

  • Регистрация поставщика ресурсов Сетки событий в подписке Azure.

  • Авторизация API Microsoft Graph (партнера) для создания раздела партнера в группе ресурсов.

• У вас есть рабочие знания о уведомлениях API Microsoft Graph. В рамках обучения вы можете использовать обозреватель API Graph для создания подписок API Graph.

• Общие сведения о событиях партнеров.

• Определите ресурс API Microsoft Graph, из которого требуется получать события изменения состояния системы. Дополнительные сведения см . в уведомлениях об изменении API Microsoft Graph. Например, для отслеживания изменений пользователей в идентификаторе Microsoft Entra следует использовать ресурс пользователя . Используйте группу для отслеживания изменений в группах пользователей.

• У вас есть учетная запись администратора клиента в клиенте Microsoft 365. Получите клиент разработки бесплатно, присоединившись к программе разработчика Microsoft 365.

Вы найдете другие предварительные требования, относящиеся к выбранному языку программирования и среде разработки, используемой в ссылках на примеры 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"
}

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ChangeType = "updated,deleted,created",
	NotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    LifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
	Resource = "users",
	ExpirationDateTime = DateTimeOffset.Parse("2024-03-31T18:23:45.9356913Z"),
	ClientState = "secretClientValue",
};

// To initialize your graphClient, see `https://learn.microsoft.com/graph/sdks/create-client?from=snippets&tabs=csharp`
var result = await graphClient.Subscriptions.PostAsync(requestBody);

mgc subscriptions create --body '{\
   "changeType": "updated,deleted,created",\
   "notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=youPartnerTopic&location=theNameOfAzureRegionFortheTopic",\
   "lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",\
   "resource": "users",\
   "expirationDateTime":"2024-03-31T18:23:45.9356913Z",\
   "clientState": "secretClientValue"\
}\
'

import (
	  "context"
	  "time"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewSubscription()
changeType := "updated,deleted,created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
requestBody.SetNotificationUrl(&notificationUrl)
lifecycleNotificationUrl := "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl)
resource := "users"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2024-03-31T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 

subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "updated,deleted,created";
subscription.notificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic";
subscription.lifecycleNotificationUrl = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic";
subscription.resource = "users";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2024-03-31T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";

graphClient.subscriptions()
	.buildRequest()
	.post(subscription);

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   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-31T18:23:45.9356913Z',
   clientState: 'secretClientValue'
};

await client.api('/subscriptions')
	.post(subscription);

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Subscription();
$requestBody->setChangeType('updated,deleted,created');
$requestBody->setNotificationUrl('EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic');
$requestBody->setLifecycleNotificationUrl('EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic');
$requestBody->setResource('users');
$requestBody->setExpirationDateTime(new \DateTime('2024-03-31T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');

$result = $graphServiceClient->subscriptions()->post($requestBody)->wait();

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	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 = [System.DateTime]::Parse("2024-03-31T18:23:45.9356913Z")
	clientState = "secretClientValue"
}

New-MgSubscription -BodyParameter $params

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	change_type = "updated,deleted,created",
	notification_url = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
    lifecycle_notification_url = "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
	resource = "users",
	expiration_date_time = "2024-03-31T18:23:45.9356913Z",
	client_state = "secretClientValue"
)

result = await graph_client.subscriptions.post(request_body)

• 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.

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

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

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

Связанный контент

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

• Активируйте раздел партнера , созданный во время установки API Microsoft Graph.
• Подпишитесь на события, создав подписку на события для вашего партнерского раздела.