リソースデータの変更に関する通知を設定する

  • [アーティクル]

Microsoft Graph APIでは、Webhook メカニズムを使用して、変更通知をクライアントに配信します。 クライアントは、変更通知を受信するように独自の URL を構成する Web サービスです。 クライアントアプリは、変更時に変更通知を使って状態を更新します。

Microsoft Graph はサブスクリプション要求を受け入れると、サブスクリプションで指定された URL に変更通知をプッシュします。 アプリはその後、そのビジネス ロジックに従ってアクションを実行します。 たとえば、詳細データのフェッチ、そのキャッシュやビューの更新などです。

トレーニング モジュール: Microsoft Graph で変更通知を使用し、変更を追跡する

既定では、変更通知には id 以外のリソース データは含まれません。 アプリでリソース データが必要な場合、アプリは Microsoft Graph API を呼び出して完全なリソースを取得することができます。 この記事では、変更通知をコントロールする例として ユーザー リソースを使用します。

アプリは、データにアクセスするために追加の API 呼び出しを行う必要がなくなるよう、リソース データを含む変更通知をサブスクライブすることもできます。 そようなアプリでは、そうした通知の要件 (具体的には、サブスクリプションのライフサイクル通知への応答、通知の真正性の検証、およびリソース データの解読) を満たすための追加のコードを実装する必要があります。 これらの通知を取り扱う方法の詳細については、「リソース データを含む変更通知を設定する」を参照してください。

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

アプリは、表に示されている Microsoft Graph リソースの変更をサブスクライブできます。これは、リソースへのサブスクリプションに適用される制限も示します。 制限を超えると、サブスクリプションを作成しようとするとエラー応答が 403 Forbidden 発生します。 エラー応答の message プロパティは、超過した制限について説明します。

注:

アスタリスク (*) でマークされたリソースへのサブスクリプションは、エンドポイントでのみ使用できます /beta 。

リソース サポートされているリソース パス 制限事項
クラウド印刷の printer 印刷ジョブをダウンロードする準備ができたときに変更されます (jobFetchable イベント): /print/printers/{id}/jobs -
クラウド印刷の printTaskDefinition キューに有効なジョブがある場合の変更 (jobStarted イベント): /print/printtaskdefinition/{id}/tasks -
OneDrive (個人用) の driveItem 任意のフォルダーの階層内のコンテンツに対する変更:/users/{id}/drive/root -
OneDrive for Business の driveItem ルート フォルダーの階層内のコンテンツに対する変更: /drives/{id}/root 、/users/{id}/drive/root -
group すべてのグループに対する変更: /groups

特定のグループに対する変更: /groups/{id}

特定のグループの所有者に対する変更: /groups/{id}/owners

特定のグループのメンバーに対する変更: /groups/{id}/members		 最大サブスクリプションのクォータ:
  • アプリごと (すべてのテナントを組み合わせた場合): 合計サブスクリプション数 50,000。
  • テナントごと (すべてのアプリケーションを組み合わせた場合): すべてのアプリで合計 1,000 個のサブスクリプション。
  • アプリとテナントの組み合わせごとに:100 の合計サブスクリプション。

    Azure AD B2C テナントではサポートされていません。

    サブスクリプションの changeType に関する既知の問題。
    		•
    SharePoint サイトのリスト リスト内のコンテンツに対する変更:/sites/{site-id}/lists/{list-id} -
    Microsoft 365 グループ会話 グループの会話に対する変更: groups/{id}/conversations -
    Outlook メッセージ ユーザーのメールボックス内のすべてのメッセージに対する変更: /users/{id}/messages 、 /me/messages

    ユーザーの受信トレイ内のメッセージの変更: /users/{id}/mailFolders('inbox')/messages 、 /me/mailFolders('inbox')/messages    		 すべてのアプリケーションに対して、メールボックスあたり最大 1,000 個のアクティブなサブスクリプションが許可されます。
    Outlook イベント ユーザーのメールボックス内のすべてのイベントに対する変更: /users/{id}/events 、 /me/events すべてのアプリケーションに対して、メールボックスあたり最大 1,000 個のアクティブなサブスクリプションが許可されます。
    Outlook 個人用連絡先 ユーザーのメールボックス内のすべての個人用連絡先に対する変更: /users/{id}/contacts 、 /me/contacts すべてのアプリケーションに対して、メールボックスあたり最大 1,000 個のアクティブなサブスクリプションが許可されます。
    セキュリティの警告 特定のアラートに対する変更: /security/alerts/{id}

    フィルター処理されたアラートに対する変更: /security/alerts/?$filter={parameters}    		 -
    Teams callRecord すべての通話レコードを変更する: /communications/callRecords 最大サブスクリプションのクォータ:
  • 組織ごとに:100 の合計サブスクリプション。
    		•
    Teams チャット テナント内のすべてのチャットに対する変更: /chats

    特定のチャットに対する変更: /chats/{id}    		 最大サブスクリプションのクォータ:
  • アプリとチャットの組み合わせごとに:1 つのサブスクリプション。
  • 組織ごとに:合計 10,000 個のサブスクリプション。
    		•
    Teams chatMessage すべてのチームのすべてのチャネルでチャット メッセージに対する変更: /teams/getAllMessages

    特定のチャネルでのチャット メッセージの変更: /teams/{id}/channels/{id}/messages

    すべてのチャットでのチャット メッセージの変更: /chats/getAllMessages

    特定のチャット内のチャット メッセージに対する変更: /chats/{id}/messages

    特定のユーザーが含まれるすべてのチャット内のチャット メッセージに対する変更: /users/{id}/chats/getAllMessages    		 最大サブスクリプションのクォータ:
  • アプリとチャネルまたはチャットの組み合わせごとに:1 つのサブスクリプション。
  • 組織ごとに:合計 10,000 個のサブスクリプション。
    		•
    Teams チャネル すべてのチームのチャネルに対する変更: /teams/getAllChannels

    特定のチームのチャネルに対する変更: /teams/{id}/channels    		 最大サブスクリプションのクォータ:
  • アプリとチームの組み合わせごとに:1 つのサブスクリプション。
  • 組織ごとに:合計 10,000 個のサブスクリプション。
    		•
    Teams conversationMember 特定のチームのメンバーシップの変更: /teams/{id}/members

    特定のチームのすべてのチャネルのメンバーシップに対する変更: teams/{id}/channels/getAllMembers

    特定のチャットでのメンバーシップの変更: /chats/{id}/members

    すべてのチャットのメンバーシップに対する変更: /teams/getAllMembers    		 最大サブスクリプションのクォータ:
  • アプリとチームの組み合わせごとに:1 つのサブスクリプション。
  • 組織ごとに:合計 10,000 個のサブスクリプション。
    		•
    Teams onlineMeeting * オンライン会議の変更: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    Teams プレゼンス * 1 人のユーザーのプレゼンスに対する変更: /communications/presences/{id}

    複数のユーザー プレゼンスに対する変更: /communications/presences?$filter=id in ({id},{id}...)
    Teams チーム テナント内の任意のチームに対する変更: /teams

    特定のチームへの変更: /teams/{id}    		 最大サブスクリプションのクォータ:
  • アプリとチームの組み合わせごとに:1 つのサブスクリプション。
  • 組織ごとに:合計 10,000 個のサブスクリプション。
    		•
    todoTask 特定のタスク リスト内のすべてのタスクに対する変更: /me/todo/lists/{todoTaskListId}/tasks -
    user すべてのユーザーに対する変更: /users

    特定のユーザーに対する変更: /users/{id}    		 最大サブスクリプションのクォータ:
  • アプリごと (すべてのテナントを組み合わせた場合): 合計サブスクリプション数 50,000。
  • テナント 1 つあたり (すべてのアプリケーションの合計): すべてのアプリケーションでの合計サブスクリプション数 1,000
  • アプリとテナントの組み合わせごとに:合計 100 個のサブスクリプション。

    outlook.com などの個人の Microsoft アカウントではサポートされていません。

    Azure AD B2C テナントではサポートされていません。

    サブスクリプションの changeType に関する既知の問題。
    		•

    次のリソースは、リッチ通知 (リソース データを含む通知) をサポートしています。

    サブスクリプション ライフタイム

    サブスクリプションのライフタイムには制限があります。 アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。 そうしない場合、新しいサブスクリプションを作成する必要があります。 最長有効期限の一覧については、「リソースの種類別のサブスクリプションの最大の長さ」をご覧ください。

    また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。

    サブスクリプションの管理

    クライアントは、サブスクリプションを作成したり、サブスクリプションを更新したり、サブスクリプションを削除したりできます。

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

    リソースの変更通知の受信を開始するための最初の手順は、サブスクリプションを作成することです。 サブスクリプション プロセスは、次のようになります。

    1. クライアントは、特定のリソースのサブスクリプション要求 (POST) を送信します。

    2. Microsoft Graph が要求を確認します。

      • 要求が有効な場合、Microsoft Graph は検証トークンを通知 URL に送信します。
      • 要求が無効である場合、Microsoft Graph は、エラー コードと詳細の付いたエラー応答を送信します。

    3. クライアントは、Microsoft Graph に検証トークンを返送します。

    4. Microsoft Graph からクライアントに応答が送信されます。

    クライアントは、サブスクリプションに変更通知を関連付けるために、サブスクリプション ID を格納する必要があります。

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

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

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

    プロパティの changeType、notificationUrl、resource、および expirationDateTime は必須です。 プロパティの定義と値については、「サブスクリプション リソースの種類」をご覧ください。

    resource プロパティは、変更の監視対象となるリソースを指定します。 たとえば、特定のメール フォルダーme/mailFolders('inbox')/messagesへのサブスクリプションを作成できます。または、管理者の同意によって指定されたユーザーの代わりに を作成できます。 users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages

    clientState は必須ではありませんが、推奨される変更通知の処理プロセスに準拠するには含める必要があります。 このプロパティを設定すると、受け取る変更通知が Microsoft Graph サービスから来たものであることを確認することができます。 その理由で、このプロパティの値は機密として保たなければならず、使用はアプリケーションと Microsoft Graph サービスのためにのみ限るようにしてください。

    処理が正常に終了すると、Microsoft Graph は 201 Created コードおよび本文内に サブスクリプション オブジェクトを返します。

    注:

    notificationUrl プロパティに含まれるクエリ文字列パラメータは、通知が配信されるときに HTTP POST 要求に含まれます。

    通知エンドポイントの検証

    Microsoft Graph により、サブスクリプション作成の前にサブスクリプション要求の notificationUrl プロパティの中で提供される通知エンドポイントが検証されます。 検証プロセスは、次のようになります。

    1. Microsoft Graph は検証トークンをエンコードし、この検証トークンを通知 URL への POST 要求に含めます。

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

    2. クライアントは、前の手順で提供された validationToken クエリ パラメーターを正しく URL デコードし、HTML/JavaScript があればそれをエスケープする必要があります。

      エスケープが推奨される理由は、悪意のある行為者は、クロスサイト スクリプティングの種類の攻撃に通知エンドポイントを利用できるためです。

      一般的に、トークンの形式は多くの場合通知なしに変更できるため、検証トークンの値は不透明として扱ってください。 Microsoft Graph が HTML または JavaScript コードを含む値を送信することはありません。

    3. クライアントは、手順 1 から 10 秒以内に次の特性を持つ応答を提供する必要があります。

      • 状態コード HTTP 200 OK。
      • コンテンツ タイプ text/plain。
      • URL デコード済み検証トークンを含む本文。 validationTokenクエリ パラメーターで送信された同じ文字列を反映します。

      クライアントは、検証トークンを応答で提供した後は、検証トークンを破棄する必要があります。

      重要

      クライアントがエンコードされた検証トークンを返した場合、検証は失敗します。

    さらに、Microsoft Graph Postman コレクションを使用して、エンドポイントが検証リクエストを適切に実装していることを確認できます。 Misc フォルダー内のサブスクリプションの検証リクエストは、エンドポイントによって提供される応答を検証する単体テストを提供します。

    検証応答のテスト結果

    サブスクリプションの更新

    クライアントは、要求時から最大 3 日間の特定の有効期限日を持つサブスクリプションを更新できます。 expirationDateTime プロパティは必須です。

    サブスクリプションの更新の例

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

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

    処理が正常に終了すると、Microsoft Graph は 200 OK コードおよび本文内に サブスクリプション オブジェクトを返します。 サブスクリプション オブジェクトには、新しい expirationDateTime 値が含まれます。

    サブスクリプションの削除

    クライアントは、その ID を使用してサブスクリプションを削除することにより、変更通知の受信を停止できます。

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

    処理が正常に終了すると、Microsoft Graph は 204 No Content コードを返します。

    変更通知

    クライアントがリソースの変更に関するサブスクリプションを行っている状態になると、リソースの変更が発生するたびに Microsoft Graph が通知 URL に POST 要求を送信するようになります。 created など、サブスクリプションで指定されている種類の変更についてのみ通知が送信されます。

    注:

    同じリソースを監視する複数のサブスクリプションがクライアントにあり、これらのサブスクリプションで同じ通知 URL が使用されている場合、Microsoft Graph は 異なるサブスクリプションに対応する複数の変更通知を送信する場合があり、それぞれの通知では対応するサブスクリプション ID が表示されます。 その POST 要求のすべての通知が単一のサブスクリプションに属すものであるという保証はありません。

    変更通知の例

    このセクションでは、メッセージ作成に関する通知の例を示します。 ユーザーがメールを受信すると、Microsoft Graph は次の例に示すように変更通知を送信します。 通知は value フィールドに表らせれるコレクションの中にあります。 通知ペイロードの詳細については、「changeNotificationCollection」を参照してください。

    変更が多数発生した場合は、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 が 2xx クラス コードを 3 秒以内に受信しない場合、約 4 時間にわたって変更通知を何度も発行を試みます。その後、変更通知は中断され、配信されません。 プロセスが 3 秒以内に一貫して応答しない場合、通知は調整の対象になる場合があります。

      処理に 3 秒以上かかると予想される場合は、通知を保持し、Microsoft Graph への応答で 202 - Accepted の状態コードを返し、通知を処理する必要があります。 通知が保持されない場合は、5xx クラス コードを返してエラーを示すと、通知が再試行されます。

      3 秒未満で処理できると予想される場合は、通知を処理し、Microsoft Graph への応答で状態コード 200 - OK を返します。 通知が正しく処理されない場合は、5xx クラス コードを返してエラーを示すと、通知が再試行されます。

    2. clientState プロパティを検証します。 これは、サブスクリプション作成要求で当初送られた値に一致していなければなりません。

      注:

      そうでない場合、これを有効な変更通知と見なすべきではありません。 変更通知が Microsoft Graph に由来するものでなく、悪意のある者が偽って送った可能性があります。 また、変更通知の送信元を調査し、適切なアクションを実行する必要があります。

    3. ビジネス ロジックに基づいて、アプリケーションを更新します。

    要求内の他の変更通知について、これらの手順を繰り返します。

    調整

    真正性を検証する前であっても、変更通知を受け取ったらすぐに状態コード 202 - Accepted を送信します。 これは、変更通知の受信を確認し、不必要な再試行を防止することのみが目的です。 ほとんどのサブスクリプションでは、サービスでインシデントが発生していない限り、通知の発行中に追加の遅延の対象にはならず、すべての通知が SLA 内で配信されます。 ただし、サブスクリプション通知 URL が低速である場合や応答に失敗した場合は、サブスクリプションに関連付けられているホストへの通知が調整される可能性があります。 調整されたエンドポイントを調整するタイミングと処理方法を決定するには、次のプロセスを使用します。

    通知は、3 秒のタイムアウトで HTTP クライアントを使用して発行されます。 結果に関係なく、通知の発行が完了すると、通知 URL に関連付けられたホストに対して、ネットワーク待機時間を含む発行の試行に費やされた合計時間が追跡されます。 発行時間が 2,900 ミリ秒を超える場合、応答は低速とみなされます。 応答はホストに累積され、低速応答の割合は 100 件の通知を受信した後に計算されます。 低速応答の割合が 10% に達すると、通知 URL に関連付けられたホストに低速エンドポイントとしてフラグが設定されます。 低速エンドポイントは通知 URL 内のホストに関連付けられているため、ホストに関連付けられているすべてのサブスクリプションへの通知はすべて評価対象であり、調整の対象であるとみなされます。

    評価はリアルタイムで続行されます。 ホストの発行時間が 2,900ms を下回った場合、この低速でない応答は応答の合計数に含まれ、低速応答の割合が再計算されて、エンドポイントが再評価されます。 さらに、応答の蓄積は 10 分ごとにフラッシュされ、もう一度評価が開始され、エンドポイントを評価するまでの 100 件の通知を待機します。 したがって、ネットワーク待機時間や発行の遅延の一時的な急増は、遅延が軽減された後に修復されます。 2,900 ミリ秒を超える永続的なネットワーク待機時間や発行の遅延は、10 分ごとに継続的に再評価されます。

    エンドポイントが調整されている間、次の追加の遅延が通知の対象になります。

    • 通知は、失敗した通知と調整された調整された通知の一連のワーカーに自動的にオフロードされ、さらに 10 分の遅延が発生します。
    • 調整されたエンドポイントの低速 % が 15% の場合、通知は >削除されます。
    • HTTP 呼び出しの失敗によって配信に失敗した通知は、10 分後にもう一度再試行されます。

    コード サンプル

    GitHub では、次のコード サンプルを利用できます。

    ファイアウォール構成

    オプションとして、通知 URL を保護するファイアウォールを構成して、Microsoft Graph からのインバウンド接続のみを許可することができます。 これにより、通知 URL に送信される無効な変更通知がさらされる可能性をさらに減らすことができます。 これらの無効な変更通知は、実装したカスタム ロジックをトリガーしようとしている可能性があります。 Microsoft Graph が変更通知を配信するために使用する IP アドレスの完全なリストについては、「Microsoft 365 の追加のエンドポイント」をご覧ください。

    注:

    変更通知の配信に使用される一覧に記載されている IP アドレスは、予告なしにいつでも更新できます。

    遅延

    次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。

    リソース 平均遅延時間 最大遅延時間
    警告 3 分未満 5 分
    callRecord 15 分未満 60 分
    channel 10 秒未満 60 分
    チャット 10 秒未満 60 分
    chatMessage 10 秒未満 1 分
    contact 不明 不明
    会話 不明 不明
    conversationMember 10 秒未満 60 分
    driveItem 1 分未満 5 分
    イベント 不明 不明
    グループ 2 分未満 15 分
    リスト 1 分未満 5 分
    メッセージ 不明 不明
    onlineMeeting 10 秒未満 1 分
    プレゼンス 10 秒未満 1 分
    printer 1 分未満 5 分
    printTaskDefinition 1 分未満 5 分
    team 10 秒未満 60 分
    [todoTask][] 2 分未満 15 分
    ユーザー 2 分未満 15 分

    注:

    警告 リソースに指定された遅延時間は、警告自体が作成された後にのみ適用されます。 ルールがデータから通知を作成するのにかかる時間は含まれません。

    関連項目