フィードバック 編集

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

  • [アーティクル]

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

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

チュートリアル: Microsoft Graph で変更通知と変更追跡を使用する

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

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

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

Microsoft Graph の API を使用すると、アプリは次のリソースに変更を登録できます。

サンプル シナリオ

次のシナリオのサブスクリプションを作成できます。

シナリオ Query
受信トレイなどの特定の Outlook フォルダへ me/mailFolders('inbox')/messages
最上位のリソースへ　 /me/messages
/me/contacts
/me/events
/users
/groups
/communications/callRecords
特定のリソース インスタンスへ /users/{id}
/groups/{id}
/groups/{id}/conversations
/sites/{site-id}/lists/{list-id}
/communications/presences/{id}
/communications/onlinemeeting/{meeting-id}
ユーザーの個人用 OneDrive 内の任意のフォルダーへ /drives/{id}/root
/drives/{id}/root/subfolder
SharePoint / OneDrive for Business ドライブのルート フォルダーへ /drive/root
または、新しいセキュリティ API アラートに /security/alerts?$filter=status eq 'newAlert'
/security/alerts?$filter=vendorInformation/provider eq 'ASC'
ユーザーの To Do リストのタスクへ /me/todo/lists/{todoTaskListId}/tasks

Azure AD リソースの制限

Azure AD ベースのリソース (ユーザー、グループ) には一定の制限が適用され、超過するとエラーが発生します。

注意

これらの制限は、Azure AD 以外のサービスのリソースには適用されません。 たとえば、アプリは message または event リソースに対して、より多くのサブスクリプションを作成できます。これらは Microsoft Graph の一部として Exchange Online サービスでサポートされているものです。

  • 最大サブスクリプションのクォータ:

    • アプリ 1 つあたり (すべてのテナントでの合計): 合計サブスクリプション数 50,000
    • テナント 1 つあたり (すべてのアプリケーションの合計): すべてのアプリケーションでの合計サブスクリプション数 1,000
    • アプリ 1 つあたりとテナント 1 つあたりを組わせた場合: 合計サブスクリプション数 100

制限を超えた場合、サブスクリプションを作成しようとするとエラー応答 - 403 Forbidden が発生します。 message プロパティは、どの制限が超過しているかを説明します。

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

  • ユーザー エンティティの変更通知は、個人用 Microsoft アカウントではサポートされていません。

  • ユーザーとグループのサブスクリプションには、既知の問題があります。

Outlook リソースの制限

すべてのアプリケーションにおいてメールボックスあたりのアクティブなサブスクリプションの最大数は 1,000 です。

Teams リソースの制限

各 Teams リソースには、異なるサブスクリプション クォータがあります。

  • callRecords のサブスクリプションの場合:

    • 組織あたり: 合計 100 サブスクリプション

  • chatMessages のサブスクリプションの場合 (チャネルまたはチャット):

    • アプリとチャンネルまたはチャットの組み合わせごと: 1 サブスクリプション
    • 組織あたり: 合計 10,000 サブスクリプション

  • channels のサブスクリプションの場合:

    • アプリごとの組み合わせとチームの組み合わせ: 1 つのサブスクリプション
    • 組織あたり: 合計 10,000 サブスクリプション

  • チャット のサブスクリプションの場合:

    • アプリとチャンネルまたはチャットの組み合わせごと: 1 サブスクリプション
    • 組織あたり: 合計 10,000 サブスクリプション

  • チーム のサブスクリプションの場合:

    • アプリごとの組み合わせとチームの組み合わせ: 1 つのサブスクリプション
    • 組織あたり: 合計 10,000 サブスクリプション

  • conversationMembers のサブスクリプションの場合:

    • アプリごとの組み合わせとチームの組み合わせ: 1 つのサブスクリプション
    • 組織あたり: 合計 10,000 サブスクリプション

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

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

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

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

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

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

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

  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 分

注意

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

関連項目