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

• 2020/01/17
• • 
  • 

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

Microsoft Graph はサブスクリプション要求を受け入れると、サブスクリプションで指定された URL に通知をプッシュします。After Microsoft Graph accepts the subscription request, it pushes 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.

既定では、変更通知には 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 notifications.

アプリは、データにアクセスするために追加の API 呼び出しを行う必要がなくなるよう、リソース データを含む変更通知をサブスクライブすることもできます。An app can also subscribe to change notifications that include resource data, to avoid having to make additonal 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 notificatios, 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 メッセージOutlook message
• Outlook イベントOutlook event
• Outlook 個人用[連絡先][]Outlook personal contact
• ユーザーuser
• グループgroup
• Office 365 グループ会話Office 365 group conversation
• ユーザーの個人用 OneDrive 上の_任意のフォルダーの_ driveItem 階層内のコンテンツContent within the hierarchy of any folder driveItem on a user's personal OneDrive
• OneDrive for Business 上の_ルート フォルダーの _ driveItem 階層内のコンテンツContent within the hierarchy of the root folder driveItem on OneDrive for Business
• セキュリティの警告Security alert

受信トレイなど特定の 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、または groupsOr to a top-level resource: me/messages, me/contacts, me/events, users, or groups

あるいは、特定のリソース インスタンス: users/{id}、groups/{id}、groups/{id}/conversationsOr to a specific resource instance: users/{id}, groups/{id}, groups/{id}/conversations

または、ユーザーの個人用 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:

  • アプリあたり: 合計 50,000 サブスクリプションPer app: 50,000 total subscriptions
  • テナントあたり: すべてのアプリで合計 1000 サブスクリプションPer tenant: 1000 total subscriptions across all apps
  • アプリとテナントの組み合わせ: 合計 100 サブスクリプションPer app and tenant combination: 100 total subscriptions

制限を超えると、サブスクリプションを作成しようとして、エラー応答 - 403 Forbidden が発生します。When the limits are 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 アカウントではサポートされていません。Notification for user entities are not supported for personal Microsoft accounts.

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

サブスクリプション ライフタイム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 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 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 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 notification handling process. このプロパティを設定すると、受け取る通知が Microsoft Graph サービスから来たものであることを確認することができます。Setting this property will allow you to confirm that 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.

通知エンドポイントの検証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 sends a POST request to the notification URL:

   POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}
   

   重要: validationToken はクエリ パラメーターであるため、クライアントが HTTP コーディング プラクティスに従って適切にデコードする必要があります。Important: Since the validationToken is a query parameter it must be properly decoded by the client, as per HTTP coding practices. クライアントがトークンをデコードせず、代わりに次の手順で示すエンコードされた値 (応答) を使用する場合、検証は失敗します。If the client does not decode the token, and instead uses the encoded value in the next step (response), validation will fail. また、トークンの形式は将来予告なしに変更される可能性があるため、クライアントはトークン値を曖昧なものとして処理する必要があります。Also, the client should treat the token value as opaque since the token format may change in the future, without notice.

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

   • 200 (OK) 状態コード。A 200 (OK) status code.
   • コンテンツ タイプは text/plain でなければなりません。The content type must be text/plain.
   • 本文には Microsoft Graph が提供した検証トークンを含める必要があります。The body must include the validation token provided by Microsoft Graph.

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

サブスクリプションの更新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 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.

通知Notifications

クライアントはサブスクリプションを作成した後、通知の受信を開始します。The client starts receiving notifications after creating the subscription. Microsoft Graph は、リソースに変更が発生すると通知 URL に POST 要求を送信します。Microsoft Graph sends a POST request to the notification URL when the resource changes. 通知が送信されるのは、created など、サブスクリプションで指定されているタイプの変更についてのみです。Notification are sent only for the changes of the type specified in the subscription, for example, created.

注: 同じリソース タイプを監視し、同じ通知 URL を使用する複数のサブスクリプションを使用している場合、サブスクリプション ID が異なる複数の通知が含まれる POST が送信されることがあります。Note: When using multiple subscriptions that monitor the same resource type and use the same notification URL, a POST can be sent that will contain multiple notifications with different subscription IDs. その POST に含まれるすべての通知が、単一のサブスクリプションに属しているという保証はありません。There is no guarantee that all notifications in the POST will belong to a single subscription.

通知のプロパティNotification properties

通知オブジェクトには、次のプロパティがあります。The notification object has the following properties:

たとえば、Outlook リソースの場合、resourceData には次のフィールドが含まれています:For example, for Outlook resources, resourceData contains the following fields:

注: resourceData で提供される id 値は、通知生成時に有効だったものです。Note: The id value provided in resourceData is valid at the time the notification was generated. メッセージを別のフォルダーに移動するなど、アクションによっては、通知処理時に id が有効でなくなるという結果になる場合があります。Some actions, such as moving a message to another folder, may result in the id no longer being valid when the notification is processed.

通知の例Notification example

ユーザーが電子メールを受信すると、Microsoft Graph は次のように通知を送信します。When the user receives an email, Microsoft Graph sends a notification like the following:

{
  "value": [
    {
      "subscriptionId":"<subscription_guid>",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@<tenant_guid>/messages/{long_id_string}",
      "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>"
      }
    }
  ]
}

value フィールドはオブジェクトの配列であることに注意してください。Note the value field is an array of objects. キューに多数の通知が入っている場合、Microsoft Graph から、単一の要求の中で複数の項目が送信されることがあります。When there are many queued notifications, Microsoft Graph may send multiple items in a single request. 同じ通知要求の中に、異なる複数のサブスクリプションからの通知が含まれることがあります。Notifications from different subscriptions can be included in the same notification request.

通知の処理Processing the notification

アプリの受け取る通知を、それぞれ処理する必要があります。Each notification received by your app should be processed. アプリが通知を処理するために必要な最小限のタスクは、次のようになります。The following are the minimum tasks that your app must perform to process a 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 notification a number of times, for a period of about 4 hours; after that, the notification will be dropped and won't be delivered.

   注: 真正性を検証する前であっても、通知を受け取ったらすぐに 202 - Accepted 状態コードを送信します。Note: Send a 202 - Accepted status code as soon as you receive the notification, even before validating its authenticity. 通知の受信を確認し、不必要な再試行を防止しているだけです。You are simply acknowledging the receipt of the notification and preventing unnecessary retries. 現在のタイムアウトは 30 秒ですが、サービスのパフォーマンスを最適化するため、将来的に短縮される可能性があります。The current timeout is 30 seconds, but it might be reduced in the future to optimize service performance.

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 notification. 通知が Microsoft Graph に由来するものでなく、悪意のある者が偽って送った可能性があります。It is possible that the notification has not originated from Microsoft Graph and may have been sent by a rogue actor. また、通知の送信元を調査し、適切なアクションを実行する必要があります。You should also investigate where the notification comes from and take appropriate action.

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

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

コード サンプルCode samples

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

• Microsoft Graph トレーニング モジュール - Microsoft Graph で変更通知と変更履歴を使用するMicrosoft Graph Training Module - Using Change Notifications and Track Changes with Microsoft Graph
• Node.js 用 Microsoft Graph Webhooks のサンプルMicrosoft Graph Webhooks Sample for Node.js
• ASP.NET 用 Microsoft Graph Webhooks のサンプルMicrosoft Graph Webhooks Sample for ASP.NET
• WebJobs SDK を使用した Microsoft Graph ユーザー Webhook のサンプルMicrosoft Graph User Webhooks Sample using WebJobs SDK

関連項目See also

• Subscription リソースタイプSubscription resource type
• サブスクリプションを取得するGet subscription
• サブスクリプションを作成するCreate subscription
• 変更通知チュートリアルChange notifications tutorial