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

• 2019/04/12
• 共同作成者
  • 
  • 

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, etc.

サポートされているリソース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 ‘New’、/security/alerts?$filter=vendorInformation/provider eq ‘ASC’Or to a new Security API alert: /security/alerts?$filter=status eq ‘New’, /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 may generate errors when exceeded:

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

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

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

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

サブスクリプション ライフタイム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. 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.

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

3. Microsoft Graph への応答で、202 - Accepted ステータス コードを送信します。Send a 202 - Accepted status code in your response to Microsoft Graph. Microsoft Graph が 2xx クラス コードを受信しない場合は、通知を何回でも再試行します。If Microsoft Graph doesn't receive a 2xx class code, it will retry the notification a number of times.

   注: clientStateプロパティがサブスクリプション要求のものと一致しない場合でも、202 - Accepted ステータス コードを送信する必要があります。Note: You should send a 202 - Accepted status code even if the clientState property doesn't match the one submitted with the subscription request. これは、偽通知が信頼されていないかもしれないという事実を悪意のある者が検出し、それを利用して clientState プロパティの値を類推するのを防ぐことになるため、優れた方法と言えます。This is a good practice as it prevents a potential rogue actor from discovering the fact that you may not trust their notifications, and perhaps using that information to guess the value of the clientState property.

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

コード サンプルCode samples

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

• 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