サブスクリプションと変更通知の消失を減らす

サブスクリプションの有効期間中に、Microsoft Graph は、指定したライフサイクルに特別な種類の通知を送信 しますNotificationUrl を使用して、必要なアクションを通知します。 これらの通知は ライフサイクル通知 と呼ばれ、サブスクリプションが見つからないリスクを最小限に抑え、通知を変更するのに役立ちます。

ライフサイクル通知には、次の 3 種類があります。

• reauthorizationRequired 通知
• サブスクリプション が削除された 通知
• 見逃した 通知

これらのイベントを無視すると、変更通知フローが中断される可能性があります。イベントを処理するには、アプリにロジックを実装して継続的な変更通知フローを再開します。

この記事では、Microsoft Graph の変更通知のライフサイクル通知について説明し、通知を処理するためのガイダンスを提供します。

サポートされているリソース

任意のリソースの種類でサブスクリプションを作成するときに lifecycleNotificationUrl を 指定できますが、ライフサイクル通知は現在、次のリソースの種類でのみサポートされています。

• reauthorizationRequired 通知 - すべてのリソース
• subscriptionRemoved 通知 - Outlook メッセージ、Outlook イベント、Outlook 個人用 連絡先、Teams chatMessage
• 不在通知 - Outlook メッセージ、Outlook イベント、Outlook 個人用 連絡先

ライフサイクル通知を受信するようにサブスクリプションを構成する

ライフサイクル通知を受信するには、サブスクリプションの作成時に有効な ライフサイクルNotificationUrl エンドポイントを指定する必要があります。 次のサブスクリプション作成要求は、 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

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

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

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

プロジェクトに 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

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.subscription import Subscription
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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 プロパティを既存のサブスクリプションに追加することもできません。 lifecycleNotificationUrl プロパティを追加するには、サブスクリプションの作成時に プロパティを指定しながら、既存のサブスクリプションを削除し、新しいサブスクリプションを作成する必要があります。

Webhooks 配信チャネルを使用する場合は、lifecycleNotificationUrl エンドポイントと notificationUrl エンドポイントの両方を検証する必要があります。

ライフサイクル通知の構造

ライフサイクル通知ペイロードは、 changeNotificationCollection オブジェクトと関連する changeNotification オブジェクトの構造に従います。

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

ライフサイクル通知の種類を表す、 lifecycleEvent を subscriptionRemoved、 missed、または reauthorizationRequiredできます。

ライフサイクル通知には、特定のリソースに関する情報は含まれません。これは、リソースの変更ではなく、サブスクリプションの状態の変更に関連するためです。 変更通知と同様に、ライフサイクル通知はまとめてバッチ処理し、それぞれ異なる lifecycleEvent 値を持つコレクションとして受信できます。 バッチ内の各ライフサイクル通知を適切に処理します。

ライフサイクル通知を処理し、変更通知のフローを再開すると、変更通知は 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 に送信されます。

   変更通知のフローはしばらく続く可能性があり、追加の応答時間が与えられます。 ただし、ユーザーが必要なアクションを実行するまで、最終的には変更通知の配信は一時停止されます。 変更通知の配信が一時停止したときに発生するリソースの変更に関する通知と、アプリがサブスクリプションを正常に再作成した時刻は失われます。 このような場合、 アプリでは、差分クエリを使用するなど、これらの変更を個別にフェッチする必要があります。

reauthorizationRequire 通知に応答する

1. 応答コードを使用して POST 呼び出しに応答することで、ライフサイクル通知の受信 202 - Accepted 確認します。

2. ライフサイクル通知の真正性を検証します。

3. 次の手順に進むために有効なアクセス トークンがアプリにあることを確認します。

4. 次の 2 つの 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"
     }
     

     アプリがリソースへのアクセスを許可されなくなった場合、更新が失敗する可能性があります。 その後、アプリが新しいアクセス トークンを取得してサブスクリプションを正常に再認証することが必要になる場合があります。

     これらのアクションはいつでも再試行できます。アクセスの条件に変更があった場合は、成功する場合があります。

追加情報

• 承認チャレンジは、サブスクリプションの有効期限が切れる前にサブスクリプションを更新する必要性に取って代わるわけではありません。 アクセス トークンとサブスクリプションの有効期限のライフサイクルは同じではありません。 アクセス トークンは、サブスクリプションの前に有効期限が切れる可能性があります。 アクセス トークンを更新するために、エンドポイントを定期的に再認証する準備をすることが重要です。 エンドポイントを再認証しても、サブスクリプションは更新されません。 ただし、 サブスクリプションを更新すると 、エンドポイントも再認証されます。

• 承認チャレンジの頻度は、変更される場合があります。

  承認チャレンジの頻度を想定しないでください。 これらのライフサイクル通知では、アクションを実行するタイミングが示されるため、再認証が必要なサブスクリプションを追跡する必要はありません。 すべてのサブスクリプションに対して数分に 1 回から、一部のサブスクリプションではほとんど承認の課題に対処する準備をしてください。

subscriptionRemoved 通知

subscriptionRemoved ライフサイクル イベントは、Microsoft Graph がサブスクリプションを削除したときにアラートを生成します。 このような場合、関連リソースの変更通知を引き続き受信する場合は、サブスクリプションを再作成する必要があります。

有効期間の長いサブスクリプションがある場合でも、リソース データへのアクセス条件は時間の経過と同時に変化する可能性があります。 たとえば、アプリがユーザーを再認証する必要があるサービス内のイベントが発生する可能性があります。 このような場合、Microsoft Graph から サブスクリプションの更新通知が送信されます 。

次のフローは、 subscriptionRemoved イベントのフローを示しています。

1. サービスは、Microsoft Graph からサブスクリプションを削除する必要があることを検出します。

   これらのイベントに対して設定された頻度はありません。 イベントが頻繁に発生するリソースもあれば、ほとんど発生しないリソースもあります。

2. Microsoft Graph は subscriptionRemoved ライフサイクル通知を lifecycleNotificationUrl (指定されている場合) に送信します。

   ライフサイクル通知は、アプリがサブスクリプションを正常に再作成したときに subscriptionRemoved ライフサイクル通知が送信された期間から使用できません。 アプリは、それらの変更を独自にフェッチする必要があります。

SubscriptionRemoved 通知に応答する

1. 応答コードを使用して POST 呼び出しに応答することで、ライフサイクル通知の受信 202 - Accepted 確認します。

2. ライフサイクル通知の真正性を検証します。

3. 次の手順に進むために有効なアクセス トークンがアプリにあることを確認します。

4. 新しいサブスクリプションを作成します。

   このアクションは失敗する可能性があります。これは、システムによって実行される承認チェックによって、リソースへのアプリ アクセスが拒否される可能性があるためです。 サブスクリプションを正常に再認証するために、アプリが新しいアクセス トークンを取得することが必要な場合があります。 これらのアクションは、後でいつでも再試行できます。たとえば、アクセス条件が変更された場合などです。

5. 新しいサブスクリプションを作成した後、リソース データを同期して、見逃した変更通知を特定できます。たとえば、 デルタ クエリを使用します。

見逃した通知

missed ライフサイクル イベントは、一部の変更通知が配信されなかったことを警告します。 たとえば、 調整が原因です。

受信できなかった通知への応答

1. 応答コードを使用して POST 呼び出しに応答することで、ライフサイクル通知の受信 202 - Accepted 確認します。
2. ライフサイクル通知の真正性を検証します。
3. リソースの完全なデータ再同期を実行して、通知として配信されなかった変更を特定します。たとえば、 デルタ クエリを使用します。

関連コンテンツ

• Subscription リソースタイプ