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

Статья
01/03/2024

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

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

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

Дополнительные сведения о создании уведомлений об изменениях см. в статье Уведомления об изменениях API Microsoft Graph.

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

Важно!

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

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

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

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

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

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"
}


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

// Dependencies
using Microsoft.Graph.Models;

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",
};

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



mgc subscriptions create --body '{\
  "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"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

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

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) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created,updated");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/notificationClient");
subscription.setLifecycleNotificationUrl("https://webhook.azurewebsites.net/api/lifecycleNotifications");
subscription.setResource("/me/mailfolders('inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-03-20T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("SecretClientState");
Subscription result = graphClient.subscriptions().post(subscription);


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);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$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)->wait();


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


from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	change_type = "created,updated",
	notification_url = "https://webhook.azurewebsites.net/notificationClient",
	lifecycle_notification_url = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	resource = "/me/mailfolders('inbox')/messages",
	expiration_date_time = "2016-03-20T11:00:00.0000000Z",
	client_state = "SecretClientState",
)

result = await graph_client.subscriptions.post(request_body)

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

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

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

Примечание.

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

Дублирование подписок запрещено. Если запрос подписки содержит те же значения для changeType и ресурса , что и существующая подписка, запрос завершается ошибкой с кодом 409 ConflictHTTP и сообщением Subscription Id <> already exists for the requested combinationоб ошибке .

Проверка notificationUrl

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

Примечание.

Если вы также подписываетесь на уведомления жизненного цикла , служба подписки также проверяет жизненный циклNotificationUrl.

При запросе подписки Microsoft Graph кодирует маркер проверки и включает его в запрос POST на URL-адрес уведомления, как показано ниже.
```
Content-Type: text/plain; charset=utf-8
POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
```
Клиент должен правильно декодировать URL-адрес, чтобы получить маркер проверки обычного текста из Microsoft Graph.

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

Как правило, значение маркера проверки следует рассматривать как непрозрачное, так как формат маркера может измениться без уведомления.
Клиент должен ответить следующими характеристиками в течение 10 секунд после шага 1:
- Код состояния HTTP 200 OK.
- Тип контента text/plain.
- Текст, содержащий маркер проверки простого текста с декодированием URL-адреса .
Важно!

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

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

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

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

При получении уведомления об изменении:

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

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

Жизненный цикл подписки

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

Самый простой способ продолжить получать уведомления — продолжить продление запроса на подписку. Каждое уведомление содержит свойство subscriptionExpirationDateTime . Вы можете использовать его, чтобы узнать, когда следует продлевать подписку.

Каждая подписка также включает маркер доступа, предоставленный конечной точке. Срок действия этого маркера доступа может произойти до истечения срока действия подписки. Вы можете управлять истечением срока действия маркера доступа с помощью уведомлений о жизненном цикле подписки.

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

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

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


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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Subscription
{
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-22T11:00:00.0000000Z"),
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Subscriptions["{subscription-id}"].PatchAsync(requestBody);



mgc subscriptions patch --subscription-id {subscription-id} --body '{\
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

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

requestBody := graphmodels.NewSubscription()
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-22T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
subscriptions, err := graphClient.Subscriptions().BySubscriptionId("subscription-id").Patch(context.Background(), requestBody, nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-03-22T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
Subscription result = graphClient.subscriptions().bySubscriptionId("{subscription-id}").patch(subscription);


const options = {
	authProvider,
};

const client = Client.init(options);

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

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


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Subscription;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

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

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


Import-Module Microsoft.Graph.ChangeNotifications

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

Update-MgSubscription -SubscriptionId $subscriptionId -BodyParameter $params


from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription

graph_client = GraphServiceClient(credentials, scopes)

request_body = Subscription(
	expiration_date_time = "2016-03-22T11:00:00.0000000Z",
)

result = await graph_client.subscriptions.by_subscription_id('subscription-id').patch(request_body)

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

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

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

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


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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Subscriptions["{subscription-id}"].DeleteAsync();



mgc subscriptions delete --subscription-id {subscription-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

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


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Subscriptions().BySubscriptionId("subscription-id").Delete(context.Background(), nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

graphClient.subscriptions().bySubscriptionId("{subscription-id}").delete();


const options = {
	authProvider,
};

const client = Client.init(options);

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


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


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


Import-Module Microsoft.Graph.ChangeNotifications

Remove-MgSubscription -SubscriptionId $subscriptionId


from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


await graph_client.subscriptions.by_subscription_id('subscription-id').delete()

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

Уведомления жизненного цикла для подписки

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

При подписке на уведомления жизненного цикла Microsoft Graph оповещает вас:

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

Примечание.

Если срок действия маркера доступа истек, уведомления не будут доставляться конечной точке. Но Microsoft Graph будет продолжать повторять отправку каждого уведомления в течение 4 часов. Таким образом, если маркер доступа обновляется в течение 4 часов после истечения срока действия, будут доставлены неотправленные уведомления.

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

Сводка

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

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

Тип ресурса подписки
Тип ресурса changeNotificationCollection
Уведомления жизненного цикла

Поделиться через

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

Рекомендации по использованию конечной точки веб-перехватчика

Коды HTTP и логика повторных попыток

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

Проверка подлинности

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

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

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

Проверка notificationUrl

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

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

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

Жизненный цикл подписки

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

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

Уведомления жизненного цикла для подписки

Сводка

Обратная связь

Обратная связь

Дополнительные ресурсы

Поделиться через

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

Рекомендации по использованию конечной точки веб-перехватчика

Коды HTTP и логика повторных попыток

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

Проверка подлинности

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

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

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

Проверка notificationUrl

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

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

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

Жизненный цикл подписки

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

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

Уведомления жизненного цикла для подписки

Сводка

Связанные материалы

Обратная связь

Обратная связь

Дополнительные ресурсы