ユーザー データの変更に関する通知の設定Set up notifications for changes in user data

Microsoft Graph の API は、webhook メカニズムを使用して、クライアントに変更通知を配信します。クライアントは、変更通知を受信するために自身の URL を構成する Web サービスです。クライアント アプリは通知を使用して、変更時に状態を更新します。The Microsoft Graph API uses a webhook mechanism to deliver change notifications to clients. A client is a web service that configures its own URL to receive change notifications. Client apps use change notifications to update their state upon changes.

Microsoft Graph はサブスクリプション要求を受け入れると、サブスクリプションで指定された URL に変更通知をプッシュします。After Microsoft Graph accepts the subscription request, it pushes change notifications to the URL specified in the subscription. アプリはその後、そのビジネス ロジックに従ってアクションを実行します。The app then takes action according to its business logic. たとえば、詳細データのフェッチ、そのキャッシュやビューの更新などです。For example, it fetches more data, updates its cache and views, and so on.

チュートリアル: Microsoft Graph で変更通知と変更追跡を使用するTutorial: Use Change Notifications and Track Changes with Microsoft Graph

既定では、変更通知には id 以外のリソース データは含まれません。By default, change notifications do not contain resource data, other than the id. アプリでリソース データが必要な場合、アプリは Microsoft Graph API を呼び出して完全なリソースを取得することができます。If the app requires resource data, it can make calls to Microsoft Graph APIs to get the full resource. この記事では、変更通知をコントロールする例として ユーザー リソースを使用します。This article uses the user resource as an example for working with change notifications.

アプリは、データにアクセスするために追加の API 呼び出しを行う必要がなくなるよう、リソース データを含む変更通知をサブスクライブすることもできます。An app can also subscribe to change notifications that include resource data, to avoid having to make additional API calls to access the data. そようなアプリでは、そうした通知の要件 (具体的には、サブスクリプションのライフサイクル通知への応答、通知の真正性の検証、およびリソース データの解読) を満たすための追加のコードを実装する必要があります。Such apps will need to implement extra code to handle the requirements of such notifications, specifically: responding to subscription lifecycle notifications, validating the authenticity of notifications, and decrypting the resource data. 今後は、このような種類の通知をサポートするリソースの種類が増えます。More resource types will support this type of notifications in the future. これらの通知を取り扱う方法の詳細については、「リソース データを含む変更通知を設定する (プレビュー)」を参照してください。For details about how to work with these notifications, see Set up change notifications that include resource data (preview).

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

Microsoft Graph の API を使用すると、アプリは次のリソースに変更を登録できます。Using the Microsoft Graph API, an app can subscribe to changes on the following resources:

受信トレイなど特定の Outlook フォルダーに対してのサブスクリプションを作成できます: me/mailFolders('inbox')/messagesYou can create a subscription to a specific Outlook folder such as the Inbox: me/mailFolders('inbox')/messages

最上位レベルのリソースへの場合は次のようになります：/me/messages、/me/contacts、/me/events、users、groups、/communications/callRecordsOr to a top-level resource: /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}Or to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations, sites/{site-id}/lists/{list-id}, /communications/presences/{id}

または、ユーザーの個人用 OneDrive 内の任意のフォルダー: /drives/{id}/root /drives/{id}/root/subfolderOr to any folder in a user's personal OneDrive: /drives/{id}/root /drives/{id}/root/subfolder

あるいは、Sharepoint/OneDrive for Business ドライブのルート フォルダー: /drive/rootOr to the root folder of a SharePoint/OneDrive for Business drive: /drive/root

または、新しいセキュリティ API の警告: /security/alerts?$filter=status eq 'newAlert'、/security/alerts?$filter=vendorInformation/provider eq 'ASC'Or to a new Security API alert: /security/alerts?$filter=status eq 'newAlert', /security/alerts?$filter=vendorInformation/provider eq 'ASC'

Azure AD リソースの制限Azure AD resource limitations

Azure AD ベースのリソース (ユーザー、グループ) には一定の制限が適用され、超過するとエラーが発生します。Certain limits apply to Azure AD based resources (users, groups) and will generate errors when exceeded:

注: これらの制限は、Azure AD 以外のサービスのリソースには適用されません。Note: These limits do not apply to resources from services other than Azure AD. たとえば、アプリは message または event リソースに対して、より多くのサブスクリプションを作成できます。これらは Microsoft Graph の一部として Exchange Online サービスでサポートされているものです。For example, an app can create many more subscriptions to message or event resources, which are supported by the Exchange Online service as part of Microsoft Graph.

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

    • アプリ 1 つあたり (すべてのテナントでの合計): 合計サブスクリプション数 50,000Per app (for all tenants combined): 50,000 total subscriptions
    • テナント 1 つあたり (すべてのアプリケーションの合計): すべてのアプリケーションでの合計サブスクリプション数 1,000Per tenant (for all applications combined): 1000 total subscriptions across all apps
    • アプリ 1 つあたりとテナント 1 つあたりを組わせた場合: 合計サブスクリプション数 100Per app and tenant combination: 100 total subscriptions

制限を超えた場合、サブスクリプションを作成しようとするとエラー応答 - 403 Forbidden が発生します。When any limit is exceeded, attempts to create a subscription will result in an error response - 403 Forbidden. message プロパティは、どの制限が超過しているかを説明します。The message property will explain which limit has been exceeded.

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

  • ユーザー エンティティの変更通知は、個人用 Microsoft アカウントではサポートされていません。Change notification for user entities are not supported for personal Microsoft accounts.

  • ユーザーとグループのサブスクリプションには、既知の問題があります。A known issue exists with user and group subscriptions.

Outlook リソースの制限Outlook resource limitations

メッセージ、イベント、連絡先などの Outlook リソースをサブスクライブするときに、リソース パスでユーザー プリンシパル名 UPN を使用することを選択した場合、UPN にアポストロフィが含まれていると、サブスクリプション要求が失敗することがあります。When subscribing to Outlook resources such as messages, events or contacts, if you choose to use the user principal name UPN in the resource path, the subscription request might fail if the UPN contains an apostrophe. この問題を回避するには、UPN の代わりに GUID ユーザー ID を使用することを検討してください。Consider using GUID user IDs instead of UPNs to avoid running into this problem. たとえば、リソース パスを使用する代わりに:For example, instead of using resource path:

/users/sh.o'neal@contoso.com/messages

次のコマンドを使用します:Use:

/users/{guid-user-id}/messages

Teams リソースの制限Teams resource limitations

各 Teams リソースには、異なるサブスクリプション クォータがあります。Each Teams resource has different subscription quotas.

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

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

  • chatMessages のサブスクリプションの場合 (チャネルまたはチャット) (プレビュー):For subscriptions to chatMessages (channels or chats) (preview):

    • アプリとチャンネルまたはチャットの組み合わせごと: 1 サブスクリプションPer app and channel or chat combination: 1 subscription
    • 組織あたり: 合計 10,000 サブスクリプションPer organization: 10,000 total subscriptions

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

サブスクリプションのライフタイムには制限があります。Subscriptions have a limited lifetime. アプリは、有効期限が切れる前にサブスクリプションを更新する必要があります。Apps need to renew their subscriptions before the expiration time. そうしない場合、新しいサブスクリプションを作成する必要があります。Otherwise, they need to create a new subscription. 最長有効期限の一覧については、「リソースの種類別のサブスクリプションの最大の長さ」をご覧ください。For a list of maximum expiration times, see Maximum length of subscription per resource type.

また、アプリはいつでも登録を解除して、変更通知の受信を停止できます。Apps can also unsubscribe at any time to stop getting change notifications.

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

クライアントは、サブスクリプションを作成したり、サブスクリプションを更新したり、サブスクリプションを削除したりできます。Clients can create subscriptions, renew subscriptions, and delete subscriptions.

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

リソースの変更通知の受信を開始するための最初の手順は、サブスクリプションを作成することです。Creating a subscription is the first step to start receiving change notifications for a resource. サブスクリプション プロセスは、次のようになります。The subscription process is as follows:

  1. クライアントは、特定のリソースのサブスクリプション要求 (POST) を送信します。The client sends a subscription (POST) request for a specific resource.

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

    • 要求が有効な場合、Microsoft Graph は検証トークンを通知 URL に送信します。If the request is valid, Microsoft Graph sends a validation token to the notification URL.
    • 要求が無効である場合、Microsoft Graph は、エラー コードと詳細の付いたエラー応答を送信します。If the request is invalid, Microsoft Graph sends an error response with code and details.

  3. クライアントは、Microsoft Graph に検証トークンを返送します。The client sends the validation token back to Microsoft Graph.

  4. Microsoft Graph からクライアントに応答が送信されます。The Microsoft Graph sends a response back to the client.

クライアントは、サブスクリプションに変更通知を関連付けるために、サブスクリプション ID を格納する必要があります。The client must store the subscription ID to correlate change notifications with the subscription.

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

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 は必須です。The changeType, notificationUrl, resource, and expirationDateTime properties are required. プロパティの定義と値については、「サブスクリプション リソースの種類」をご覧ください。See subscription resource type for property definitions and values.

resource プロパティは、変更の監視対象となるリソースを指定します。The resource property specifies the resource that will be monitored for changes. たとえば、特定のメール フォルダーへサブスクリプションを作成できます: me/mailFolders('inbox')/messagesまたは、管理者の同意を得たユーザーの代わりに作成できます: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages。For example, you can create a subscription to a specific mail folder: me/mailFolders('inbox')/messages or on behalf of a user given by an administrator consent: users/john.doe@onmicrosoft.com/mailFolders('inbox')/messages.

clientState は必須ではありませんが、推奨される変更通知の処理プロセスに準拠するには含める必要があります。Although clientState is not required, you must include it to comply with our recommended change notification handling process. このプロパティを設定すると、受け取る変更通知が Microsoft Graph サービスから来たものであることを確認することができます。Setting this property will allow you to confirm that change notifications you receive originate from the Microsoft Graph service. その理由で、このプロパティの値は機密として保たなければならず、使用はアプリケーションと Microsoft Graph サービスのためにのみ限るようにしてください。For this reason, the value of the property should remain secret and known only to your application and the Microsoft Graph service.

処理が正常に終了すると、Microsoft Graph は 201 Created コードおよび本文内に サブスクリプション オブジェクトを返します。If successful, Microsoft Graph returns a 201 Created code and a subscription object in the body.

注: notificationUrl プロパティに含まれるクエリ文字列パラメータは、通知が配信されるときに HTTP POST 要求に含まれます。Note: any query string parameter included in the notificationUrl property will be included in the HTTP POST request when notifications are being delivered.

通知エンドポイントの検証Notification endpoint validation

Microsoft Graph により、サブスクリプション作成の前にサブスクリプション要求の notificationUrl プロパティの中で提供される通知エンドポイントが検証されます。Microsoft Graph validates the notification endpoint provided in the notificationUrl property of the subscription request before creating the subscription. 検証プロセスは、次のようになります。The validation process occurs as follows:

  1. Microsoft Graph は検証トークンをエンコードし、この検証トークンを通知 URL への POST 要求に含めます。Microsoft Graph encodes a validation token and includes it in a POST request to the notification URL:

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

  2. クライアントは、前の手順で提供された validationToken を正しくデコードし、HTML/JavaScript があれば、それをエスケープする必要があります。The client must properly decode the validationToken provided in the preceding step, and escape any HTML/JavaScript.

    エスケープが推奨される理由は、悪意のある行為者は、クロスサイト スクリプティングの種類の攻撃に通知エンドポイントを利用できるためです。Escaping is a good practice because malicious actors can use the notification endpoint for cross-site scripting type of attacks.

    一般的に、トークンの形式は多くの場合通知なしに変更できるため、検証トークンの値は不透明として扱ってください。In general, treat the validation token value as opaque, as the token format can generally change without notice. Microsoft Graph が HTML または JavaScript コードを含む値を送信することはありません。Microsoft Graph never sends any value containing HTML or JavaScript code.

  3. クライアントは、手順 1 から 10 秒以内に次の特性を持つ応答を提供する必要があります。The client must provide a response with the following characteristics within 10 seconds of step 1:

    • 状態コード HTTP 200 OK。A status code of HTTP 200 OK.
    • コンテンツ タイプ text/plain。A content type of text/plain.
    • _デコード済み_検証トークンを含む 本文。A body that includes the decoded validation token.

    クライアントは、検証トークンを応答で提供した後は、検証トークンを破棄する必要があります。The client should discard the validation token after providing it in the response.

    重要: クライアントがエンコードされた検証トークンを返した場合、検証は失敗します。Important: If the client returns an encoded validation token, the validation will fail.

さらに、Microsoft Graph Postman コレクションを使用して、エンドポイントが検証リクエストを適切に実装していることを確認できます。Additionally, you can use the Microsoft Graph Postman collection to confirm that your endpoint properly implements the validation request. Misc フォルダー内のサブスクリプションの検証リクエストは、エンドポイントによって提供される応答を検証する単体テストを提供します。The Subscription Validation request in the Misc folder provides unit tests that validate the response provided by your endpoint.

検証応答のテスト結果

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

クライアントは、要求時から最大 3 日間の特定の有効期限日を持つサブスクリプションを更新できます。The client can renew a subscription with a specific expiration date of up to three days from the time of request. expirationDateTime プロパティは必須です。The expirationDateTime property is required.

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

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

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

処理が正常に終了すると、Microsoft Graph は 200 OK コードおよび本文内に サブスクリプション オブジェクトを返します。If successful, Microsoft Graph returns a 200 OK code and a subscription object in the body. サブスクリプション オブジェクトには、新しい expirationDateTime 値が含まれます。The subscription object includes the new expirationDateTime value.

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

クライアントは、その ID を使用してサブスクリプションを削除することにより、変更通知の受信を停止できます。The client can stop receiving change notifications by deleting the subscription using its ID.

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

処理が正常に終了すると、Microsoft Graph は 204 No Content コードを返します。If successful, Microsoft Graph returns a 204 No Content code.

変更通知Change notifications

クライアントがリソースの変更に関するサブスクリプションを行っている状態になると、リソースの変更が発生するたびに Microsoft Graph が通知 URL に POST 要求を送信するようになります。With a client subscribing to changes to a resource, Microsoft Graph sends a POST request to the notification URL whenever the resource changes. created など、サブスクリプションで指定されている種類の変更についてのみ通知が送信されます。It sends notifications only for changes of the type that's specified in the subscription, for example, created.

注:、同じリソースを監視する複数のサブスクリプションがクライアントにあり、これらのサブスクリプションで同じ通知 URL が使用されている場合、Microsoft Graph は 異なるサブスクリプションに対応する複数の変更通知を送信する場合があり、それぞれの通知では対応するサブスクリプション ID が表示されます。Note: If a client has multiple subscriptions that monitor the same resource and use the same notification URL, Microsoft Graph can send multiple change notifications that correspond to different subscriptions, each showing the corresponding subscription ID. その POST 要求のすべての通知が単一のサブスクリプションに属すものであるという保証はありません。There is no guarantee that all change notifications in the POST request belong to a single subscription.

変更通知の例Change notification example

このセクションでは、メッセージ作成に関する通知の例を示します。This section shows an example of a notification for a message creation. ユーザーがメールを受信すると、Microsoft Graph は次の例に示すように変更通知を送信します。When the user receives an email, Microsoft Graph sends a change notification as shown in the following example. 通知は value フィールドに表らせれるコレクションの中にあります。Note that the notification is in a collection represented in the value field. 通知ペイロードの詳細については、「changeNotificationCollection」を参照してください。See changeNotificationCollection for details of the notification payload.

変更が多数発生した場合は、Microsoft Graph　は異なるサブスクリプションに対応する複数の通知を同一の POST 要求で送信する場合があります。When many changes occur, Microsoft Graph may send multiple notifications that correspond to different subscriptions in the same POST request.

{
  "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}"
      }
    }
  ]
}

変更通知の処理Processing the change notification

プロセスでは、受信したすべての変更通知が処理されることになっています。Your process should process every change notification it receives. 変更通知を処理するためにアプリが実行する必要がある最小限のタスクは、次のようになります。The following are the minimum tasks that your app must perform to process a change notification:

  1. Microsoft Graph への応答で、状態コード 202 - Accepted を送信します。Send a 202 - Accepted status code in your response to Microsoft Graph. Microsoft Graph が 2xx クラス コードを受信しない場合、約 4 時間にわたって変更通知を何度も発行を試みます。その後、変更通知は中断され、配信されません。If Microsoft Graph doesn't receive a 2xx class code, it will try to publishing the change notification a number of times, for a period of about 4 hours; after that, the change notification will be dropped and won't be delivered.

    注: 真正性を検証する前であっても、変更通知を受け取ったらすぐに状態コード 202 - Accepted を送信します。Note: Send a 202 - Accepted status code as soon as you receive the change notification, even before validating its authenticity. これは、変更通知の受信を確認し、不必要な再試行を防止することのみが目的です。You are simply acknowledging the receipt of the change notification and preventing unnecessary retries. 現在のタイムアウトは 30 秒ですが、サービスのパフォーマンスを最適化するため、将来的に短縮される可能性があります。The current timeout is 30 seconds, but it might be reduced in the future to optimize service performance. 変更 URL が 10 分間の間に Microsoft Graph からの要求の 10% 以上に対して 30 秒以内に応答しないことがあった場合、次のすべての通知は遅延し、4 時間に渡って再試行されます。If the notification URL doesn't reply within 30 seconds for more than 10% of the requests from Microsoft Graph over a 10 minute period, all following notifications will be delayed and retried for a period of 4 hours. 変更 URL が 10 分間の間に Microsoft Graph からの要求の 20% 以上に対して 30 秒以内に応答しないことがあった場合、次のすべての通知は停止されます。If a notification URL doesn't reply within 30 seconds for more than 20% of the requests from Microsoft Graph over a 10 minute period, all following notifications will be dropped.

  2. clientState プロパティを検証します。Validate the clientState property. これは、サブスクリプション作成要求で当初送られた値に一致していなければなりません。It must match the value originally submitted with the subscription creation request.

    注: そうでない場合、これを有効な変更通知と見なすべきではありません。Note: If this isn't true, you should not consider this a valid change notification. 変更通知が Microsoft Graph に由来するものでなく、悪意のある者が偽って送った可能性があります。It is possible that the change notification has not originated from Microsoft Graph and may have been sent by a rogue actor. また、変更通知の送信元を調査し、適切なアクションを実行する必要があります。You should also investigate where the change notification comes from and take appropriate action.

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

要求内の他の変更通知について、これらの手順を繰り返します。Repeat for other change notifications in the request.

コード サンプルCode samples

GitHub では、次のコード サンプルを利用できます。The following code samples are available on GitHub.

ファイアウォール構成Firewall configuration

オプションとして、通知 URL を保護するファイアウォールを構成して、Microsoft Graph からのインバウンド接続のみを許可することができます。You can optionally configure the firewall that protects your notification URL to allow inbound connections only from Microsoft Graph. これにより、通知 URL に送信される無効な変更通知がさらされる可能性をさらに減らすことができます。This allows you to reduce further exposure to invalid change notifications that are sent to your notification URL. これらの無効な変更通知は、実装したカスタム ロジックをトリガーしようとしている可能性があります。These invalid change notifications can be trying to trigger the custom logic that you implemented. Microsoft Graph が変更通知を配信するために使用する IP アドレスの完全なリストについては、「Microsoft 365 の追加のエンドポイント」をご覧ください。For a complete list of IP addresses used by Microsoft Graph to deliver change notifications, see additional endpoints for Microsoft 365.

注: 変更通知の配信に使用される一覧に記載されている IP アドレスは、予告なしにいつでも更新できます。Note: The listed IP addresses that are used to deliver change notifications can be updated at any time without notice.

遅延Latency

次の表は、サービスで発生するイベントと変更通知の配信との間で予想される待ち時間を示しています。The following table lists the latency to expect between an event happening in the service and the delivery of the change notification.

リソースResource 平均遅延時間Average latency 最大遅延時間Maximum latency
callRecordcallRecord 15 分未満Less than 15 minutes 60 分60 minutes
chatMessage (プレビュー)chatMessage (preview) 10 秒未満Less than 10 seconds 1 分1 minute
contactcontact 不明Unknown 不明Unknown
driveItemdriveItem 1 分未満Less than 1 minute 5 分5 minutes
イベントevent 不明Unknown 不明Unknown
グループgroup 2 分未満Less than 2 minutes 15 分15 minutes
会話conversation 不明Unknown 不明Unknown
[リスト][]list 1 分未満Less than 1 minute 5 分5 minutes
メッセージmessage 不明Unknown 不明Unknown
警告alert 3 分未満Less than 3 minutes 5 分5 minutes
プレゼンス (プレビュー)presence (preview) 10 秒未満Less than 10 seconds 1 分1 minute
ユーザーuser 2 分未満Less than 2 minutes 15 分15 minutes

注: 警告 リソースに指定された遅延時間は、警告自体が作成された後にのみ適用されます。Note: The latency provided for the alert resource is only applicable after the alert itself has been created. ルールがデータから通知を作成するのにかかる時間は含まれません。It does not include the time it takes for a rule to create an alert from the data.

関連項目See also