Получение уведомлений об изменениях с помощью веб-перехватчиков

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

Чтобы получать уведомления об изменениях через веб-перехватчики, необходимо создать подписку на ресурс, для которого вы хотите получать уведомления об изменениях. Хотя подписка действительна, Microsoft Graph отправляет в приложение уведомление при каждом обнаружении изменения в ресурсе.

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

Создание подписки

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

1. Клиентское приложение отправляет запрос на подписку для подписки на изменения в определенном ресурсе.

2. Microsoft Graph проверяет запрос.

   • Если запрос действителен, Microsoft Graph отправляет маркер проверки на URL-адрес уведомления для клиентского приложения для проверки URL-адреса уведомления.
   • Если запрос недопустим, Microsoft Graph отправляет ответ об ошибке с кодом ошибки и подробными сведениями.

3. Когда клиент получает запрос на проверку URL-адреса уведомления, клиент отвечает маркером проверки в виде обычного текста, как описано далее в этой статье.

4. Microsoft Graph проверяет ответ маркера проверки клиента и, если маркер проверки действителен, возвращает идентификатор подписки.

Запрос на подписку

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

HTTP

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}

C#

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

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new Subscription
{
	ChangeType = "created,updated",
	NotificationUrl = "https://webhook.azurewebsites.net/notificationClient",
	LifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	Resource = "/me/mailfolders('inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-20T11:00:00.0000000Z"),
	ClientState = "SecretClientState",
};
var result = await graphClient.Subscriptions.PostAsync(requestBody);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

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 := "created,updated"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/notificationClient"
requestBody.SetNotificationUrl(&notificationUrl) 
lifecycleNotificationUrl := "https://webhook.azurewebsites.net/api/lifecycleNotifications"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl) 
resource := "/me/mailfolders('inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "SecretClientState"
requestBody.SetClientState(&clientState) 

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

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Java

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

Subscription subscription = new Subscription();
subscription.changeType = "created,updated";
subscription.notificationUrl = "https://webhook.azurewebsites.net/notificationClient";
subscription.lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications";
subscription.resource = "/me/mailfolders('inbox')/messages";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-03-20T11:00:00Z");
subscription.clientState = "SecretClientState";

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

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/notificationClient',
  lifecycleNotificationUrl: 'https://webhook.azurewebsites.net/api/lifecycleNotifications',
  resource: '/me/mailfolders(\'inbox\')/messages',
  expirationDateTime: '2016-03-20T11:00:00.0000000Z',
  clientState: 'SecretClientState'
};

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

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new Subscription();
$requestBody->setChangeType('created,updated');

$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/notificationClient');

$requestBody->setLifecycleNotificationUrl('https://webhook.azurewebsites.net/api/lifecycleNotifications');

$requestBody->setResource('/me/mailfolders(\'inbox\')/messages');

$requestBody->setExpirationDateTime(new DateTime('2016-03-20T11:00:00.0000000Z'));

$requestBody->setClientState('SecretClientState');



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

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "created,updated"
	notificationUrl = "https://webhook.azurewebsites.net/notificationClient"
	lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications"
	resource = "/me/mailfolders('inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-03-20T11:00:00.0000000Z")
	clientState = "SecretClientState"
}

New-MgSubscription -BodyParameter $params

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

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

В случае успешного выполнения Microsoft Graph возвращает код 201 Created и объект подписки в теле отклика.

Каждая подписка имеет уникальный идентификатор подписки, даже если у вас есть несколько подписок, которые отслеживают один и тот же ресурс и используют один и тот же URL-адрес уведомления.

Примечание.

Любой параметр строки запроса, включенный в свойство notificationUrl , будет включен в HTTP-запрос POST при доставке уведомлений в службу.

Проверка notificationUrl

При создании подписки для получения уведомлений об изменениях с помощью веб-перехватчиков Microsoft Graph сначала проверяет конечную точку уведомления, указанную в свойстве notificationUrl запроса подписки. Проверка происходит следующим образом:

1. Microsoft Graph кодирует маркер проверки и включает его в запрос POST на URL-адрес уведомления следующим образом.

   Content-Type: text/plain; charset=utf-8
   POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
   

2. Клиент должен правильно декодировать URL-адрес, чтобы получить маркер проверки обычного текста из Microsoft Graph.

   Рекомендуется избежать любого кода HTML или JavaScript, так как злоумышленники могут использовать конечную точку уведомления для типов атак с межсайтовых сценариев. Microsoft Graph никогда не отправляет значения, содержащие код HTML или JavaScript.

   Как правило, значение маркера проверки рассматривается как непрозрачное, так как формат маркера может измениться без уведомления.

3. Клиент должен ответить следующими характеристиками в течение 10 секунд после шага 1:

   • Код состояния HTTP 200 OK.
   • Тип контента text/plain.
   • Текст, содержащий маркер проверки простого текста с декодированием URL-адреса .

   Важно!

   Маркер проверки должен быть возвращен в виде обычного текста. Если клиент возвращает зашифрованный маркер проверки, проверка завершается ошибкой.

4. Если проверка конечной точки завершается сбоем, Microsoft Graph не создает подписку.

Кроме того, можно использовать коллекцию Microsoft Graph Postman, чтобы убедиться в правильности реализации запроса проверки в вашей конечной точке. Запрос на проверку notificationUrl в папке Misc предоставляет модульные тесты, которые проверяют ответ, предоставленный конечной точкой.

Получение уведомлений

Хотя подписка действительна и есть изменения в ресурсе, на который вы подписаны POST , Microsoft Graph отправляет запрос на notificationUrl с подробными сведениями об изменениях. Эти полезные данные являются уведомлением об изменении.

Для большинства подписок Microsoft Graph не откладывает отправку уведомлений, но доставляет все уведомления в рамках соглашения об уровне обслуживания, если в службе не произошло инцидента.

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

Пример уведомления об изменениях

Когда пользователь получает сообщение электронной почты, Microsoft Graph отправляет объект уведомления об изменении в клиентское приложение, как показано в следующем примере. Сведения о полезных данных уведомления см. в разделе changeNotificationCollection и связанное с ним изменениеNotification .

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

{
  "value": [
    {
      "id": "lsgTZMr9KwAAA",
      "subscriptionId":"{subscription_guid}",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@{tenant_guid}/messages/{long_id_string}",
      "tenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@{tenant_guid}/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"{long_id_string}"
      }
    }
  ]
}

Обработка уведомлений об изменениях

Служба должна обрабатывать каждое получаеме уведомление об изменениях. Ниже перечислены основные задачи, которые приложение должно выполнить для обработки таких уведомлений.

1. После получения уведомления об изменении отправьте код класса 2xx обратно в Microsoft Graph. Если Microsoft Graph не получает код класса 2xx в течение 3 секунд, он пытается повторно отправить уведомление об изменении несколько раз в течение 4 часов. Если Microsoft Graph по-прежнему не получает код 2xx в течение периода, уведомление об изменении отклоняется. Если клиентское приложение не отвечает в течение 3 секунд, уведомления могут регулироваться.

   Если служба может обработать уведомление об изменениях более 3 секунд, она должна сохранить уведомление, вернуть 202 - Accepted код состояния в ответ microsoft Graph, а затем обработать уведомления в своей емкости. Если уведомление не сохраняется, верните код класса 5xx, указывающий на ошибку, чтобы Microsoft Graph смог повторить отправку уведомления.

   Если ожидается, что служба займет менее 3 секунд, она должна обработать уведомления и вернуть 200 - OK код состояния в Microsoft Graph. Если уведомление обработано неправильно, верните код класса 5xx, указывающий на ошибку, чтобы Microsoft Graph смог повторить попытку уведомления.

2. Проверьте свойство clientState. Оно должно соответствовать значению, отправленному с запросом на создание подписки.

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

3. Обновите клиентское приложение на основе бизнес-логики.

Продление подписки

Существует множество причин, по которым может потребоваться продлить подписку. Дополнительные сведения см. в разделе Уведомления о жизненном цикле.

Когда вы подписываетесь на уведомления жизненного цикла, Microsoft Graph оповещает вас о том, что подписка почти истекает и ее следует продлить. Если вы не подписаны на уведомления жизненного цикла, вы можете использовать subscriptionExpirationDateTime , чтобы отслеживать, когда приложение должно отправлять запрос на продление подписки.

Для продления подписки требуется свойство expirationDateTime . Если вы не продлеваете подписку вовремя, Microsoft Graph удаляет подписку, и приложение не будет получать уведомления об изменениях в будущем для подписки.

Запрос на продление подписки

HTTP

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

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}

C#

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

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new Subscription
{
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-22T11:00:00.0000000Z"),
};
var result = await graphClient.Subscriptions["{subscription-id}"].PatchAsync(requestBody);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

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()
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-22T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 

result, err := graphClient.Subscriptions().BySubscriptionId("subscription-id").Patch(context.Background(), requestBody, nil)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Java

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

Subscription subscription = new Subscription();
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-03-22T11:00:00Z");

graphClient.subscriptions("{id}")
	.buildRequest()
	.patch(subscription);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  expirationDateTime: '2016-03-22T11:00:00.0000000Z'
};

await client.api('/subscriptions/{id}')
	.update(subscription);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new Subscription();
$requestBody->setExpirationDateTime(new DateTime('2016-03-22T11:00:00.0000000Z'));



$result = $graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->patch($requestBody);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	expirationDateTime = [System.DateTime]::Parse("2016-03-22T11:00:00.0000000Z")
}

Update-MgSubscription -SubscriptionId $subscriptionId -BodyParameter $params

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Если запрос на продление подписки выполнен успешно, Microsoft Graph возвращает 200 OK код ответа и объект подписки в тексте ответа. Объект подписки включает новое значение expirationDateTime .

Удаление подписки

Если клиентскому приложению больше не нужны уведомления об изменениях, оно может удалить подписку с помощью идентификатора подписки следующим образом:

HTTP

DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}

C#

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

var graphClient = new GraphServiceClient(requestAdapter);

await graphClient.Subscriptions["{subscription-id}"].DeleteAsync();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



graphClient.Subscriptions().BySubscriptionId("subscription-id").Delete(context.Background(), nil)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Java

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

graphClient.subscriptions("{id}")
	.buildRequest()
	.delete();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/subscriptions/{id}')
	.delete();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$graphServiceClient->subscriptions()->bySubscriptionId('subscription-id')->delete();

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

Remove-MgSubscription -SubscriptionId $subscriptionId

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

В случае успешного выполнения Microsoft Graph возвращает код 204 No Content.

Регулирование

Если URL-адрес уведомления о подписке работает медленно или не отвечает, а Microsoft Graph не получает код класса 2xx в течение 3 секунд, Microsoft Graph пытается повторно отправить уведомление об изменениях несколько раз в течение 4 часов. В этом случае Microsoft Graph может регулировать уведомления для конечной точки уведомлений, связанной с подпиской.

Как Microsoft Graph обрабатывает регулирование для уведомлений об изменениях с помощью веб-перехватчиков

Уведомления публикуются с помощью HTTP-клиента с 3-секундным тайм-аутом.

1. Если время публикации превышает 2900 мс, отклик считается медленным.
2. Затем служба уведомлений об изменениях вычисляет процент медленных ответов после того, как конечная точка получит 100 уведомлений.
3. Если процент медленных ответов достигает 10 %, конечная точка, связанная с URL-адресом уведомления, помечается как медленная конечная точка. Все уведомления для всех подписок, связанных с конечной точкой, подлежат регулированию.
4. Оценка продолжается в режиме реального времени, и накопление ответов сбрасывается каждые 10 минут.

Когда Microsoft Graph регулирует конечную точку, уведомления подвергаются задержке в 10 минут и выгружаются в рабочие роли, предназначенные для уведомлений, которые не удалось и регулировать. Уведомления, которые не удалось доставить из-за неудачного вызова HTTP, повторяются через 10 минут. Уведомления удаляются, если медленный процент регулирования конечной точки превышает или равен 15 %.

Конфигурация брандмауэра

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

Примечание.

Указанные IP-адреса, которые используются для доставки уведомлений об изменениях, можно обновлять в любое время без предупреждения.

Сводка

Из этой статьи вы узнали, как получать уведомления об изменениях с помощью веб-перехватчиков.

1. Создайте подписку, отправив запрос POST к конечной точке /subscriptions .
2. Microsoft Graph проверит конечную точку уведомления веб-перехватчика перед завершением процесса создания подписки. С подпиской связан уникальный идентификатор подписки .
3. Пока подписка по-прежнему действительна и в ресурсе с подпиской происходят изменения, Microsoft Graph будет отправлять уведомления об изменениях в конечную точку notificationUrl .
4. Регулярно продлевать подписку, чтобы сохранить ее действительность и продолжать получать обновления об изменениях, на которые подписана подписка.

См. также

• Учебный модуль. Использование уведомлений об изменениях и отслеживание изменений с помощью Microsoft Graph
• Тип ресурса подписки
• Тип ресурса changeNotificationCollection
• Уведомления жизненного цикла