Microsoft Graph の Outlook リソースの通知を変更する

[アーティクル]
11/07/2024

Microsoft Graph APIを使用すると、リソースの作成、更新、削除など、リソースの変更をサブスクライブし、Webhook を介して通知を受け取ることができます。サブスクリプションでは、特定のリソースを監視するための種類の変更を指定し、それらの変更の通知を受信するエンドポイントの URL を含めます。

サブスクリプションを設定すると、別にリソースをクエリして比較する必要があるというオーバーヘッドが軽減されます。必要に応じて、サブスクリプション要求で暗号化を指定し、変更されたリソースデータを通知の一部として含めることができ、リソースペイロードを取得するための別の後続の API 呼び出しを節約することができます。

すべてのアプリケーションのメールボックスごとに、Outlook リソースのアクティブなサブスクリプションの最大数は 1,000 です。メールボックス内の連絡先、イベント、またはメッセージの変更にサブスクライブできます。

Outlook リソースの変更通知にサブスクライブするには、まずサブスクリプションを作成します。

次の Outlook リソースは、変更通知ペイロード内のリソースデータの有無にかかわらずサブスクリプションをサポートします。

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

サブスクリプションを作成するには、Outlook リソースと、通知を受け取る変更の種類 (作成、更新、または削除) を指定します。「例」を参照してください。

アクセス許可を要求する

サブスクリプションの作成と管理 (取得、更新、および削除) には、リソースの読み取りスコープが必要です。たとえば、メッセージに関する変更通知を受信するには、アプリに Mail.Read アクセス許可が必要です。 Outlook 変更通知は、委任されたアクセス許可スコープとアプリケーションアクセス許可スコープをサポートします。次の制限がある点に注意してください。

委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。たとえば、委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることはできません。
共有または委任フォルダーの Outlook 連絡先、イベント、メッセージの変更通知をサブスクライブするには、次のようにします。
- 対応するアプリケーションアクセス許可を使用して、テナントの任意のユーザーのフォルダーまたはメールボックス内にあるアイテムの変更をサブスクライブします。
- Outlook 共有アクセス許可 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared、およびその読み取り/書き込みに対応するアクセス許可) は使用しないでください。これは、共有フォルダーまたは委任されたフォルダー内のアイテムに対する通知の変更のサブスクライブをサポート していないため です。

リソースによっては、以下の表で指定された最も低い権限の権限でこの API を呼び出す。

リソース	サポートされているリソースのパス	委任 (職場または学校のアカウント)	委任 (個人用 Microsoft アカウント)	アプリケーション
連絡先	ユーザーのメールボックス内のすべての個人用連絡先に対する変更: `/me/contacts` `/users/{id}/contacts` ユーザーの contactFolder の連絡先に対する変更: `/users/{id}/contactFolders/{id}/contacts`	Contacts.Read	Contacts.Read	Contacts.Read
event	ユーザーのメールボックス内のすべてのイベントに対する変更: `/me/events` `/users/{id}/events`	Calendars.Read	Calendars.Read	Calendars.Read
メッセージ	ユーザーのメールボックス内のすべてのメッセージに対する変更: `/me/messages` `/users/{id}/messages` ユーザーの mailFolder 内のメッセージに対する変更: `/users/{id}/mailFolders/{id}/messages`	Mail.ReadBasic, Mail.Read	Mail.ReadBasic, Mail.Read	Mail.ReadBasic, Mail.Read

通知ペイロードにリソースデータを含める

変更通知にリソースデータを含めるには、サブスクリプションの作成時に通常含めるプロパティに加えて、次のプロパティを指定する 必要があります 。

includeResourceData: リソースデータを明示的に要求するには、このプロパティを true に設定します。
resource: このプロパティは、リソースの URL を指定します。 $select クエリパラメーターを使用して、通知ペイロードに含めるOutlook リソースプロパティを明示的に指定してください。

注:

URL には、$top、$skip、$orderby、$select=Body,UniqueBody、および singleValueExtendedProperties または multiValueExtendedProperties 以外の $expand を含めないでください。
encryptionCertificate: このプロパティには、リソースデータを暗号化するために Microsoft Graph で使用される公開キーのみが含まれます。コンテンツを復号するために、対応する秘密キーを保持しておきます。
encryptionCertificateId: このプロパティは、証明書用の独自の識別子です。この ID は、復号に使用する証明書を照合するために各変更通知で使用します。

メッセージ リソースのリソースデータを使用して変更通知にサブスクライブするための例を参照してください。

通知の条件を絞り込む

$filter クエリパラメーターを使用すれば、通知の条件をさらに詳細に設定することができます。「例」を参照してください。

$filter の一般的なアプリケーションの 1 つは、特定のリソースプロパティの変更時に通知を受け取る方法です。たとえば、 $filter を使用してフォルダー内の未読メッセージにサブスクライブし (isRead プロパティが false)、すべての変更の種類を含めることができます。

フォルダー内の追加されたメッセージ、または未読のマークが付けられているメッセージにより、Created 通知がトリガーされます。
フォルダー内のメッセージを閲覧すること、またはメッセージに開封済みのマークを付けることにより、Deleted 通知がトリガーされます。
フォルダー内の メッセージ リソースの isRead 以外のプロパティを変更すると、Updated 通知がトリガーされます。

サブスクリプションの作成時に $filter を使用しない場合:

フォルダーにメッセージを追加すると、結果として Created 通知が行われます。
フォルダー内のメッセージの閲覧、メッセージに開封済みのマークを付けること、またはフォルダー内のメッセージのその他のプロパティを変更することにより、結果として Updated 通知が行われます。
メッセージを削除すると、結果として Delete 通知が行われます。

Outlook 連絡先、 イベント、および メッセージ リソースは、ライフサイクル通知のサブスクライブもサポートしています。アプリがサブスクリプションを削除したり、変更通知を見逃したりした場合は、ライフサイクル通知が必要です。変更通知の継続的な配信を再開させるには、そのような消失を検出し、設定を復元するためのロジックをアプリで実装する必要があります。詳細については、「ライフサイクル通知にサブスクライブする」を参照してください。

サブスクリプションの有効期間を追跡する

有効期限が切れる前に、サブスクリプションを延長してください。 Outlook リソースデータのないサブスクリプションの最大有効期間は、サブスクリプションの有効期間テーブルにあります。

以前にサブスクリプションに対して付与されたアクセス許可を失い、サブスクリプションの有効期限が切れた場合は、新しいサブスクリプションを作成するためにもう一度アクセス許可を要求してください。

通知ペイロードの受信

サブスクリプションによっては、通知にリソースデータが含まれる場合があります。リソースデータを含むサブスクリプションを使用すると、通知と共にリソースペイロードを取得し、変更されたリソースデータを取得する別の API 呼び出しのオーバーヘッドを回避できます。

リソースデータを使用して通知を受信する

次に、メッセージ リソースのリソースデータを含む通知のペイロードの例を示します。 resource プロパティと resourceData プロパティは、通知をトリガーしたメッセージ インスタンスに対応します。リソースデータの暗号化を解除するには、encryptedContent プロパティを使用します。

{
    "value": [
      {
        "subscriptionId": "dfd11b2f-8222-4189-9545-4205c95d6235",
        "subscriptionExpirationDateTime": "2021-12-31T16:16:44.9907405+05:30",
        "changeType": "created",
        "resource": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
        "clientState": "<<--SpecifiedClientState-->>",
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
        "encryptedContent": {
          "data": "<<--EncryptedContent-->>",
          "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
          "dataSignature": "Qw/9ubWeUYJPWWXvNiGgct2FkNG2MXTRm/BLUpJM66k=",
          "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
          "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "resourceData": {
          "@odata.type": "#microsoft.graph.message",
          "@odata.id": "Users('722effaf-0433-4272-9ac4-d5ec11c3cd77')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA=')",
          "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUR8n\"",
          "id": "AAMkAGUwNjQ4ZjIxLTQ3Y2Y8AAA="
        }
      }
    ]
    "validationTokens": ["<<--ValidationTokens-->>"]
}

トークンを検証してペイロードを復号化する方法の詳細については、「リソースデータを含む変更通知を設定する」を参照してください。

暗号化解除された通知ペイロードの例を次に示します。暗号化解除されたペイロードは、Outlook メッセージスキーマに準拠しています。ペイロードは、GET メッセージ操作によって返されるものと同様です。ただし、通知ペイロードには、サブスクリプションの resource プロパティの $select パラメーターで指定されたプロパティだけが含まれます。連絡先やイベントなどの他の Outlook リソースの通知ペイロードは、それぞれのスキーマに従います。

{
    "receivedDateTime@odata.type":"#DateTimeOffset",
    "receivedDateTime":"2021-12-30T10:53:35Z",
    "subject":"TEST MESSAGE FOR RICH NOTIFICATIONS",
    "bodyPreview":"Hello,\r\n\r\nWhat\u2019s up?\r\n\r\nThanks\r\nMegan",
    "importance@odata.type":"#microsoft.graph.importance",
    "importance":"normal",
    "from": {
        "@odata.type":"#microsoft.graph.recipient",
        "emailAddress": {
            "@odata.type":"#microsoft.graph.emailAddress",
            "name":"Megan Brown",
            "address":"Megan.Brown@microsoft.com"
        }
    }
}

リソースデータのない通知の受信

リソースデータを含まない通知では、GET 呼び出しを行ってメッセージのリソースを取得するために必要な情報が提供されます。リソースデータを含まない通知のサブスクリプションでは、実際のリソースデータが送信されていないので暗号化証明書は必要ありません。

次の例は、Outlook メッセージ リソースに対応する通知のペイロードを示しています。これには、resource と resourceData プロパティが含まれます。これは、通知をトリガーしたリソースを表します。 resource と @odata.id プロパティを使用して、Microsoft Graph を呼び出してリソースのペイロードを取得します。

注:

GET 呼び出しでは、常にリソースの現在の状態が返されます。通知が送信されてからリソースが取得される時刻の間にリソースが変更された場合、操作は取得時にリソースの状態を返します。

"value": [
 {
   "subscriptionId": "c6126aa3-0ed8-412f-a988-71e6cee627c4",
   "subscriptionExpirationDateTime": "2022-01-02T03:12:18.2257768+05:30",
   "changeType": "created",
   "resource": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIxAAA=",
   "resourceData": {
     "@odata.type": "#Microsoft.Graph.Message",
     "@odata.id": "Users/622eaaff-0683-4862-9de4-f2ec83c2bd98/Messages/AAMkAGUwNjQ4ZjIAAA=",
     "@odata.etag": "W/\"CQAAABYAAACQ2fKdhq8oSKEDSVrdi3lRAAGDUUXn\"",
     "id": "AAMkAGUwNjQ4ZjIxAAA="
   },
   "clientState": "<<--SpecifiedClientState-->>",
   "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
 }
]

例

例 1: ユーザーが新しいメッセージを受信するときに、リソースデータなしで変更通知を取得するサブスクリプションを作成する

次の使用例では、ユーザーのメールボックスに作成されるメッセージの通知を要求します。

要求

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "expirationDateTime": "2021-07-07T21:42:18.2257768+00:00",
    "clientState": "secretClientState"
}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "5522bd62-7c96-4530-85b0-00b916f6151a",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientState",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T21:42:18.2257768Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": null,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": null,
    "encryptionCertificateId": null,
    "notificationUrlAppId": null
}

例 2: ユーザーが新しいメッセージを受信したときにリソースデータを使用して変更通知を取得するサブスクリプションを作成する

次の使用例では、ユーザーのメールボックスに作成されるメッセージのリソースデータを含む通知にサブスクライブします。通知ペイロードに含める message リソースのプロパティは、 $select クエリパラメーターを使用して指定されます。

要求

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "178eec5f-cf3c-4e7e-8a9c-8640deb5b5c5",
    "resource": "users/622eaaff-0683-4862-9de4-f2ec83c2bd98/messages?$select=Subject,bodyPreview,importance,receivedDateTime,from",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-01T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

例 3: 条件に基づいてメッセージのリソースデータを使用して変更通知を取得するサブスクリプションを作成する

次の使用例では、1 つ以上の添付ファイルを含み、重要度が高く、下書きフォルダーで作成されているメッセージのリソースデータを含む通知にサブスクライブします。

要求

POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
    "changeType": "created",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "expirationDateTime": "2022-01-01T21:42:18.2257768+00:00",
    "clientState": "secretClientValue",
    "includeResourceData": true,
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId"
}

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
    "id": "239dbc5f-cf3c-4e7e-8c9c-3340abc5b5c5",
    "resource": "me/mailfolders('Drafts')/messages?$select=Subject,bodyPreview&$filter=hasAttachments eq true AND importance eq 'High'",
    "applicationId": "507c3b9a-67b8-463d-88a2-15a8cefb2111",
    "changeType": "created",
    "clientState": "secretClientValue",
    "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
    "notificationQueryOptions": null,
    "notificationContentType": null,
    "lifecycleNotificationUrl": null,
    "expirationDateTime": "2022-01-20T12:32:35.1582696Z",
    "creatorId": "a4c7bd34-4f3b-46b7-a25d-b63c1e2a2842",
    "includeResourceData": true,
    "latestSupportedTlsVersion": "v1_2",
    "encryptionCertificate": "MIIDMzCCAhugAwIBAgIQE7D+++Dk1hKQBqWA==",
    "encryptionCertificateId": "testCertificateId",
    "notificationUrlAppId": null
}

次の方法で共有

Microsoft Graph の Outlook リソースの通知を変更する

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

アクセス許可を要求する

通知ペイロードにリソースデータを含める

通知の条件を絞り込む

サブスクリプションの有効期間を追跡する

通知ペイロードの受信

リソースデータを使用して通知を受信する

リソースデータのない通知の受信

例

例 1: ユーザーが新しいメッセージを受信するときに、リソースデータなしで変更通知を取得するサブスクリプションを作成する

要求

応答

例 2: ユーザーが新しいメッセージを受信したときにリソースデータを使用して変更通知を取得するサブスクリプションを作成する

要求

応答

例 3: 条件に基づいてメッセージのリソースデータを使用して変更通知を取得するサブスクリプションを作成する

要求

応答

フィードバック

その他のリソース

次の方法で共有

Microsoft Graph の Outlook リソースの通知を変更する

連絡先、予定表、メールの変更にサブスクライブする

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

アクセス許可を要求する

通知ペイロードにリソース データを含める

通知の条件を絞り込む

ライフサイクル通知にサブスクライブする

サブスクリプションの有効期間を追跡する

通知ペイロードの受信

リソース データを使用して通知を受信する

リソース データのない通知の受信

例

例 1: ユーザーが新しいメッセージを受信するときに、リソース データなしで変更通知を取得するサブスクリプションを作成する

要求

応答

例 2: ユーザーが新しいメッセージを受信したときにリソース データを使用して変更通知を取得するサブスクリプションを作成する

要求

応答

例 3: 条件に基づいてメッセージのリソース データを使用して変更通知を取得するサブスクリプションを作成する

要求

応答

関連コンテンツ

フィードバック

その他のリソース

通知ペイロードにリソースデータを含める

リソースデータを使用して通知を受信する

リソースデータのない通知の受信

例 1: ユーザーが新しいメッセージを受信するときに、リソースデータなしで変更通知を取得するサブスクリプションを作成する

例 2: ユーザーが新しいメッセージを受信したときにリソースデータを使用して変更通知を取得するサブスクリプションを作成する

例 3: 条件に基づいてメッセージのリソースデータを使用して変更通知を取得するサブスクリプションを作成する