Outlook リソースのサブスクリプションと通知の喪失を減らす (プレビュー)Reduce missing subscriptions and notifications for Outlook resources (preview)

Outlook リソースの通知の受信登録をしてあるアプリでは、サブスクリプションが削除され、通知が配信されない場合があります。Apps subscribing to notifications for Outlook resources may get their subscriptions removed and miss some notifications. 通知の継続的な配信を再開させるには、そのような消失を検出し、設定を復元するためのロジックをアプリで実装する必要があります。Apps should implement logic to detect and recover from the loss, and resume a continuous notification flow.

Outlook で特定のイベントが発生すると、サブスクリプションが削除されることがあります。Certain events in Outlook can cause a subscription to be removed. これらのイベントには次のようなものがあります。These events include:

  • ユーザーのパスワードがリセットされた場合User's password has been reset
  • ユーザーのデバイスが準拠しなくなった場合User's device is out of compliance
  • ユーザーのアカウントが取り消された場合User's account has been revoked

このようなイベントが発生すると、Outlook は特殊なライフサイクル通知である subscriptionRemoved を送信します。When such an event happens, Outlook sends a special lifecycle notification, subscriptionRemoved.

通知をアプリに配信できない場合、Outlook は missed という別のライフサイクル通知を送信します。Outlook also sends another lifecycle notification, missed, if a notification cannot be delivered to an app.

メッセージイベントなどの Outlook リソースの受信登録をしてあるアプリでは、subscriptionRemovedmissed のシグナルが検出されます。An app subscribing to notifications for Outlook resources, such as message and event, should listen to the subscriptionRemoved and missed signals:

  • subscriptionRemoved 通知を受信すると、継続的な受信を維持できるよう、アプリでサブスクリプションが再作成されます。Upon receiving a subscriptionRemoved notification, the app should recreate the subscription in order to maintain a continuous flow.
  • missed 通知を受信した場合は、アプリでは Microsoft Graphを使用してリソース データが再同期されます。On receiving a missed notification, the app should resynchronize resource data using Microsoft Graph.

ライフサイクル通知を受信するには、すでにリソース通知を受信している既存の notificationUrl エンドポイントを使用するか、subscriptionRemovedmissed 通知を異なるエンドポイントで受信できるように別の lifecycleNotificationUrl を登録するかのいずれを行います。To receive lifecycle notifications, you can use the existing notificationUrl endpoint that already receives resource notifications, or you can register a separate lifecycleNotificationUrl to receive subscriptionRemoved and missed notifications in a separate endpoint.

サブスクリプションの作成Creating a subscription

サブスクリプションを作成する際は、lifecycleNotificationUrl プロパティを使用して異なる通知エンドポイントを指定できます。When creating a subscription, you can specify a separate notification endpoint using the lifecycleNotificationUrl property. エンドポイントを指定すると、現在および将来のすべてのタイプのライフサイクル通知がそのエンドポイントに配信されます。If you specify the endpoint, all current and future types of lifecycle notifications will be delivered there. 指定しない場合、既存のすべてのサブスクリプションに関連する subscriptionRemovedmissed 通知は既存の notificationUrl に配信されます。Otherwise, subscriptionRemoved and missed notifications will be delivered to the existing notificationUrl for all existing subscriptions.

注: 現時点では、lifecycleNotificationUrl プロパティの設定または読み取りは、Microsoft Graph APIの beta バージョンを使用した場合のみ行えます。Note: At the moment, the lifecycleNotificationUrl property can only be set or read using the beta version of Microsoft Graph APIs. ただし、beta を使用して作成されたサブスクリプションは v1.0と同じ運用環境に格納されるため、v1.0 の通常の他のサブスクリプションの使用に加えて、ここで説明する新しい Outlook のフローを実装できます。However, subscriptions created using beta are stored in the same production environment as v1.0 so you can implement the new Outlook flow described here in addition to your regular usage of v1.0 with other subscriptions.

サブスクリプション要求の例Subscription request example

POST https://graph.microsoft.com/beta/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": "2019-03-20T11:00:00.0000000Z",
  "clientState": "<secretClientState>"
}

重要: 両方の通知 URL で同じホスト名を使用します。Important: Use the same hostname for both notifications URLs.

注: 通知に関する一般的な記事で説明されているように、両方の通知エンドポイントを検証する必要があります。  Note: You need to validate both notification endpoints as described in the generic notification article. 両方のエンドポイントに同じ URL を使用することを選択した場合は、検証要求が 2 つ配信されるので、それらに応答します。If you choose to use the same URL for both endpoints you will receive and respond to two validation requests.

注: 既存のサブスクリプションを更新 (PATCH) して lifecycleNotificationUrl プロパティを追加することはできません。 Note: You cannot update (PATCH) the existing subscriptions to add the lifecycleNotificationUrl property. そのような既存のサブスクリプションは削除し、新しいサブスクリプションを作成して lifecycleNotificationUrl プロパティを指定する必要があります。You should remove such existing subscriptions, and create new subscriptions and specify the lifecycleNotificationUrl property. lifecycleNotificationUrl プロパティのない既存のサブスクリプションは、notificationUrl 経由で subscriptionRemovedmissed 通知を受け取ります。Existing subscriptions without lifecycleNotificationUrl property will receive the subscriptionRemoved and missed notifications via the notificationUrl.

SubscriptionRemoved 通知に応答するResponding to subscriptionRemoved notifications

subscriptionRemoved 通知は、サブスクリプションが削除され、通知の受信を継続するにはサブスクリプションを再作成する必要があることを通知します。The subscriptionRemoved notification informs you that a subscription has been removed and should be recreated, if you want to continue receiving notifications.

有効期限が長いサブスクリプション(例: 3 日)を作成すると、リソース データの通知の notificationUrl への送信が開始されます。You can create a long-lived subscription (e.g. 3 days), and resource data notifications will start flowing to the notificationUrl. ただし、リソース データへのアクセスの条件は時間の経過とともに変化する可能性があるので注意が必要です。However, the conditions of access to the resource data may change over time. たとえば、アプリでユーザーの再認証が必要になるイベントが Outlook サービスで発生する場合があります。For example, an event in the Outlook service may occur that requires the app to re-authenticate the user. そのような場合、フローは次のようになります。In such a case, the flow looks as follows:

  1. Outlook で、Microsoft Graph からサブスクリプションを削除する必要があることが検出されます。Outlook detects that a subscription needs to be removed from Microsoft Graph.

    1. これらのイベントは、決まった頻度で発生するわけではありません。There is no set cadence for these events. イベントが頻繁に発生するリソースもあれば、ほとんど発生しないリソースもあります。They may occur frequently for some resources, and almost never for others.
  2. Microsoft Graph が subscriptionRemoved 通知を lifecycleNotificationUrl (指定されている場合) または notificationUrl に送信します。Microsoft Graph sends a subscriptionRemoved notification to the lifecycleNotificationUrl (if specified), or the notificationUrl.

  3. この通知には、同じリソースに対して新しいサブスクリプションを作成することにより応答できます。You can respond to this notification by creating a new subscription for the same resource. これを行うには、有効なアクセス トークンを提示する必要があります。新しい有効なアクセス トークンを取得するために、アプリでユーザーを再認証する必要がある場合があります。To do this, you need to present a valid access token; in some cases this means the app needs to re-authenticate the user to obtain a new valid access token.

  4. 新しいサブスクリプションを正常に作成すると、リソース通知の配信が再開されます。If you successfully create a new subscription, resource notifications will start flowing again. 作成に失敗した場合 (たとえば、アプリが有効なアクセス トークンを取得できなかった場合)、リソース通知は送信されません。However, if you fail (for example, the app could not obtain a valid access token), resource notifications will not be sent.

  5. 新しいサブスクリプションを作成したら、喪失した変更を特定するためにリソース データを同期できます。After creating the new subscription, you can sync the resource data to identify any missing changes.

SubscriptionRemoved 通知の例subscriptionRemoved notification example

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

このタイプの通知にはいくつかの注意点があります。A few things to note about this type of notification:

  • "lifecycleEvent": "subscriptionRemoved" フィールドは、この通知はサブスクリプションの削除に関連したものであることを示します。The "lifecycleEvent": "subscriptionRemoved" field designates this notification as related to subscription removal. 他の種類のライフサイクル通知が配信される可能性もあり、今後は新しい通知が導入される予定です。Other types of lifecycle notifications are also possible, and new ones will be introduced in the future.
  • 通知には特定のリソースに関する情報は含まれていません。通知はサブスクリプションの状態の変更に関するもので、リソースの変更とは関係がないためです。The notification does not contain any information about a specific resource, because it is not related to a resource change, but to the subscription state change.
  • リソース通知と同様に、ライフサイクル通知はバッチ処理でき (value 配列内で)、それぞれの通知は異なる lifecycleEvent 値を持つことができます。Similar to resource notifications, lifecycle notifications may be batched together (in the value array), each with a possibly different lifecycleEvent value. バッチ内の各通知を適切に処理します。Process each notification in the batch accordingly.

必要なアクションActions to take

  1. POST 呼び出しに 202 - Accepted で応答し、通知の受信を確認通知します。Acknowledge the receipt of the notification, by responding to the POST call with 202 - Accepted.
  2. 通知の信頼性を検証しますValidate the authenticity of the notification.
  3. 次のステップに進むために必要な有効なアクセス トークンがアプリにあることを確認します。Ensure the app has a valid access token to take the next step.

注: いずれかの認証ライブラリを使用している場合、その認証ライブラリは、有効なキャッシュされたトークンを再利用するか、ユーザーに再度ログイン (新しいパスワードなどで) するよう要求するなどして新しいトークンを取得することにより、トークンを処理します。Note: If you are using one of the authentication libraries they will handle this for you by either reusing a valid cached token, or obtaining a new token, including asking the user to login again (e.g. with a new password). アクセスの状況の変化などの理由により呼び出し側がリソース データへのアクセス許可を失っている場合があるため、新しいトークンの取得が失敗する可能性があることに注意してください。Note that obtaining a new token may fail, since the conditions of access may have changed, and the caller may no longer be allowed access to the resource data.

  1. こちらに記載されている標準的な手順に従って、新しいサブスクリプションを作成します。Create a new subscription using the standard process described here.

注: システムが実行する承認チェックによりアプリまたはユーザーのリソースへのアクセスが拒否される可能性があるため、このアクションは失敗する可能性があります。Note: This action may fail, because the authorization checks performed by the system may deny the app or the user access to the resource. サブスクリプションを正常に再認証するには、アプリはユーザーから新しいアクセス トークンを取得する必要がある場合があります。It may be necessary for the app to obtain a new access token from the user to successfully reauthorize a subscription. アクセス条件に変更があった場合などは、これらのアクションはいつでも再試行できます。You may retry these actions later, at any time, for example when the conditions of access have change. ライフサイクル通知が送信されてからアプリがサブスクリプションを正常に再作成するまでの間に発生したリソースの変更は、すべて失われます。Any resource changes in the time period from when the lifecycle notification was sent, to when the app re-creates the subscription successfully, will be lost. アプリは、それらの変更を独自に取得する必要があります。The app will need to fetch those changes on its own.

  1. 新しいサブスクリプションを作成した後、このリソースに関する通知を受け取った最後の既知の時間以降の受信できなかったリソース データを同期します。 例: GET https://graph.microsoft.com/v1.0/users/{id}/messages?$filter=createdDateTime+ge+{LastTimeNotificationWasReceived}After creating the new subscription, sync any missing resource data from the last known time you received a notification for this resource; for example: GET https://graph.microsoft.com/v1.0/users/{id}/messages?$filter=createdDateTime+ge+{LastTimeNotificationWasReceived}

受信できなかった通知への応答Responding to missed notifications

これらのシグナルは、配信されなかった可能性がある通知があることを知らせます。These signals inform you that some notifications may have not been delivered. これらのシグナルを無視するか対処するかを決めます。You should decide if you ignore or handle these signals.

通知の例Notification example

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

このタイプの通知にはいくつかの注意点があります。A few things to note about this type of notification:

  • この"lifecycleEvent": "missed" フィールドは、この通知は "missed" (受信出来なかった) 通知に関するシグナルであることを示します。The "lifecycleEvent": "missed" field designates this as a signal about missed notifications. 他の種類のライフサイクル通知が配信される可能性もあり、今後は新しい通知が導入される予定です。Other types of lifecycle notifications are also possible, and new ones will be introduced in the future.
  • 通知には特定のリソースに関する情報は含まれていません。通知はサブスクリプションの状態の変更に関するもので、リソースの変更とは関係がないためです。The notification does not contain any information about a specific resource, because it is not related to a resource change, but to the subscription state change
  • リソース通知と同様に、ライフサイクル通知はバッチ処理でき (value 配列内で)、それぞれの通知は異なる lifecycleEvent 値を持つことができます。Similar to resource notifications, lifecycle notifications may be batched together (in the value array), each with a possibly different lifecycleEvent value. バッチ内の各通知を適切に処理します。Process each notification in the batch accordingly.

必要なアクションActions to take

  1. POST 呼び出しに 202 - Accepted で応答し、通知の受信を確認通知します。Acknowledge the receipt of the notification, by responding to the POST call with 202 - Accepted.
    • シグナルを無視する場合は、特に操作は必要ありません。If you ignore these, signals, do nothing else. 無視しない場合は:Otherwise:
  2. 通知の信頼性を検証しますValidate the authenticity of the notification.
  3. 通知として配信されなかった変更を特定するために、すべてのデータを対象にリソースの再同期を実行します。Perform a full data resync of the resource to identify the changes that were not delivered as notifications.

コードが今後もライフサイクル通知を処理できるようにするFuture-proof the code handling lifecycle notifications

Microsoft Graph では今後、より多くの種類のサブスクリプション ライフサイクル通知が追加される予定です。In the future Microsoft Graph will add more types of subscription lifecycle notifications. これらの通知はこれまでと同じエンドポイント (lifecycleNotificationUrl) にポストされますが、通知の lifecycleEvent の値が変更され、通知を発行する目的のシナリオに固有の、これまでとはわずかに異なるスキーマとプロパティが含まれる可能性があります。They will be posted to the same endpoint: lifecycleNotificationUrl, but they will have a different value under lifecycleEvent and may contain a slightly different schema and properties, specific to the scenario for which they will be issued.

Microsoft Graph に新しい種類のライフサイクル通知が導入された場合でもコードが正常に動作するよう、コードは将来を見込んだ方法で実装する必要があります。You should implement your code in a future-proof way so it does not break when Microsoft Graph introduces new types of lifecycle notifications. 次のようなアプローチをお勧めします。We recommend the following approach:

  1. lifecycleEvent プロパティを使用して、サポートするイベントとして各通知を明示的に識別します。Explicitly identify each notification as an event that you support, using the lifecycleEvent property. たとえば、特定のイベントを識別するために "lifecycleEvent": "subscriptionRemoved" プロパティを探し、それを処理します。For example, look for the "lifecycleEvent": "subscriptionRemoved" property to identify a specific event, and handle it.

  2. 今後より多くの種類のライフサイクル通知が導入される可能性があるため、新しいシナリオの通知の発表を見まもるようにします。Watch for announcements of notifications for new scenarions, as there may be more types of lifecycle notifications in the future.

  3. アプリでは、アプリが認識しないすべてのライフサイクル イベントを無視するようにしますが、今後の参考にするために記録を残します。In your app, ignore any lifecycle events that the app does not recognize, and log them to gain awareness.

  4. 必要と判断する場合は、新しいライフサイクル通知に関連する資料を確認し、適切なサポートを実装します。At your discretion, look up the related documentation for new lifecycle notifications and implement support for them as appropriate.

関連項目See also