Уменьшение количества пропущенных уведомлений о подписках и изменениях

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

Существует три типа событий жизненного цикла:

• reauthorizationRequired notifications
• Уведомления об удалении подписки
• пропущенные уведомления

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

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

Поддерживаемые ресурсы

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

• reauthorizationRequired notifications — All resources
• Уведомления об удалении подписки — сообщение Outlook, событие Outlook, личный контакт Outlook, чат TeamsMessage
• Пропущенные уведомления — сообщение Outlook, событие Outlook, личный контакт Outlook

Настройка подписки для получения уведомлений о жизненном цикле

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

Следующий запрос на создание подписки определяет конечные точки notificationUrl и lifecycleNotificationUrl .

HTTP

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/users/{id}/messages",
  "expirationDateTime": "2020-03-20T11:00:00.0000000Z",
  "clientState": "<secretClientState>"
}

C#

// 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/api/resourceNotifications",
	LifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	Resource = "/users/{id}/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2020-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);

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc subscriptions create --body '{\
  "changeType": "created,updated",\
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",\
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",\
  "resource": "/users/{id}/messages",\
  "expirationDateTime": "2020-03-20T11:00:00.0000000Z",\
  "clientState": "<secretClientState>"\
}\
'

Дополнительные сведения о добавлении пакета 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/api/resourceNotifications"
requestBody.SetNotificationUrl(&notificationUrl) 
lifecycleNotificationUrl := "https://webhook.azurewebsites.net/api/lifecycleNotifications"
requestBody.SetLifecycleNotificationUrl(&lifecycleNotificationUrl) 
resource := "/users/{id}/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2020-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "<secretClientState>"
requestBody.SetClientState(&clientState) 

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

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

Java

// 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/api/resourceNotifications");
subscription.setLifecycleNotificationUrl("https://webhook.azurewebsites.net/api/lifecycleNotifications");
subscription.setResource("/users/{id}/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2020-03-20T11:00:00.0000000Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("<secretClientState>");
Subscription result = graphClient.subscriptions().post(subscription);

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

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/api/resourceNotifications',
  lifecycleNotificationUrl: 'https://webhook.azurewebsites.net/api/lifecycleNotifications',
  resource: '/users/{id}/messages',
  expirationDateTime: '2020-03-20T11:00:00.0000000Z',
  clientState: '<secretClientState>'
};

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

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

PHP

<?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/api/resourceNotifications');
$requestBody->setLifecycleNotificationUrl('https://webhook.azurewebsites.net/api/lifecycleNotifications');
$requestBody->setResource('/users/{id}/messages');
$requestBody->setExpirationDateTime(new \DateTime('2020-03-20T11:00:00.0000000Z'));
$requestBody->setClientState('<secretClientState>');

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

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

PowerShell

Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	changeType = "created,updated"
	notificationUrl = "https://webhook.azurewebsites.net/api/resourceNotifications"
	lifecycleNotificationUrl = "https://webhook.azurewebsites.net/api/lifecycleNotifications"
	resource = "/users/{id}/messages"
	expirationDateTime = [System.DateTime]::Parse("2020-03-20T11:00:00.0000000Z")
	clientState = "<secretClientState>"
}

New-MgSubscription -BodyParameter $params

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

Python

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/api/resourceNotifications",
	lifecycle_notification_url = "https://webhook.azurewebsites.net/api/lifecycleNotifications",
	resource = "/users/{id}/messages",
	expiration_date_time = "2020-03-20T11:00:00.0000000Z",
	client_state = "<secretClientState>",
)

result = await graph_client.subscriptions.post(request_body)

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

Конечная точка lifecycleNotificationUrl может совпадать с notificationUrl.

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

При использовании канала доставки веб-перехватчиков необходимо проверить обе конечные точки.

Структура уведомления жизненного цикла

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

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2019-03-20T11:00:00.0000000Z",
      "tenantId": "<tenant_guid>",
      "clientState":"<secretClientState>",
      "lifecycleEvent": "subscriptionRemoved or missed or reauthorizationRequired"
    }
  ]
}

Жизненный циклEvent может быть subscriptionRemoved, missedили reauthorizationRequired, представляющий типы уведомлений о жизненном цикле.

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

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

Реагирование на уведомления reauthorizationRequired

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

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

Перед выполнением любого из этих условий Microsoft Graph отправляет запрос авторизации в lifecycleNotificationUrl.

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

    //The following code is for illustrative purposes only
    var TokenTimeToExpirationInMinutes=(TokenExpirationTime-CurrentTime)/4;

    if((TokenTimeToExpirationInMinutes)<=180 && TokenTimeToExpirationInMinutes>60){
        //Microsoft Graph will send reauthorizationRequired notification
        TokenTimeToExpirationInMinutes=TokenTimeToExpirationInMinutes/2;
    }
    elseif(TokenTimeToExpirationInMinutes<60 && TokenTimeToExpirationInMinutes>=0){
            //Microsoft Graph will send reauthorizationRequired notification every 15 mins
            TokenTimeToExpirationInMinutes=TokenTimeToExpirationInMinutes-15;
    } else {
      //Microsoft Graph will stop sending reauthorizationRequired notifications
    }

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

1. Microsoft Graph требует повторной авторизации подписки.

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

2. Microsoft Graph отправляет уведомление о запросе авторизации в lifecycleNotificationUrl

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

Выполняемые действия

1. Подтвердите получение уведомления о жизненном цикле, ответив на вызов POST с 202 - Accepted кодом ответа.

2. Проверьте подлинность уведомления жизненного цикла.

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

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

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

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

   • Выполняйте регулярное действие "обновить", чтобы одновременно повторно авторизовать и продлить подписку.

     PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
     Content-Type: application/json
     
     {
        "expirationDateTime": "2019-09-21T11:00:00.0000000Z"
     }
     

     Обновление может завершиться ошибкой, если приложение больше не имеет прав доступа к ресурсу. Затем приложению может потребоваться получить новый маркер доступа для успешной повторной проверки подлинности подписки.

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

Дополнительные сведения

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

• Частота запросов авторизации может изменяться.

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

Ответ на уведомления subscriptionRemoved

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

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

В следующем потоке показан поток события subscriptionRemoved :

1. Служба определяет, что подписка должна быть удалена из Microsoft Graph.

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

2. Microsoft Graph отправляет уведомление жизненного цикла subscriptionRemoved для lifecycleNotificationUrl (если указано).

   Уведомления о жизненном цикле не доступны с момента subscriptionRemoved отправки уведомления о жизненном цикле, когда приложение успешно воссоздает подписку. Приложение должно получить эти изменения самостоятельно.

Выполняемые действия

1. Подтвердите получение уведомления о жизненном цикле, ответив на вызов POST с 202 - Accepted кодом ответа.

2. Проверьте подлинность уведомления жизненного цикла.

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

4. Создайте подписку.

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

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

Реагирование на пропущенные уведомления

missed События жизненного цикла предупреждают вас о том, что некоторые уведомления об изменениях, возможно, не были доставлены. Например, из-за регулирования.

Выполняемые действия

1. Подтвердите получение уведомления о жизненном цикле, ответив на вызов POST с 202 - Accepted кодом ответа.
2. Проверьте подлинность уведомления жизненного цикла.
3. Выполните полную повторную синхронизацию данных ресурса, чтобы определить изменения, которые не были доставлены в виде уведомлений; например, с помощью разностного запроса.

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

• Тип ресурса subscription