Microsoft Graph を使用して、Teams チャネルおよびチャットのメッセージの変更通知を受け取る

[アーティクル]
09/09/2023

変更通知を使用すると、チャネルまたはチャットでメッセージへの変更 (作成、更新、および削除) をサブスクリプションできます。変更通知は、サブスクリプションを維持できるようにすることで、待ち時間の短いモデルを提供します。通知のリソースデータを取得することもできます。したがって、API を呼び出してペイロードを取得する必要はありません。

チャネルまたはチャットコンテキストでの chatMessage リソースのシナリオに関するこの記事に進みます。または、他の Microsoft Teams リソースの変更通知について説明します。

注:

今後 1 時間を超えるサブスクリプション の有効期限DateTime を要求する場合は、サブスクリプション要求に lifecycleNotificationUrl プロパティを含めることによってライフサイクル通知をサブスクライブする必要があります。それ以外の場合、サブスクリプション要求は次のエラーメッセージで失敗します。 lifecycleNotificationUrl は、expirationDateTime 値が 1 時間を超える値に設定されている場合、このリソースでサブスクリプションを作成するために必要なプロパティです。

テナント内のメッセージに関連するすべての変更を追跡するには、チャネルとチャットメッセージのテナントレベルでサブスクリプションを使用し、2 つのサブスクリプションを作成します。1 つはチャネル間のすべてのメッセージを追跡し、もう 1 つはチャット全体のすべてのメッセージを追跡するサブスクリプションです。

テナント内のチャネル間ですべてのメッセージと返信の通知を変更するには、/teams/getAllMessages をサブスクリプションします。このリソースは、通知へのリソースデータの組み込みをサポートします。

注: この API には、ライセンス要件と支払い要件があります。 model=A と model=B クエリパラメーターの両方をサポートしています。モデルが指定されていない場合は、評価モードが使用されます。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	サポートされていません。
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	ChannelMessage.Read.All

例

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

テナント内のチャット全体のすべてのメッセージの変更通知を受け取るには、/chats/getAllMessages をサブスクリプションします。このリソースは、通知へのリソースデータの組み込みをサポートします。

注: この API には、ライセンス要件と支払い要件があります。 model=A と model=B クエリパラメーターの両方をサポートしています。モデルが指定されていない場合は、評価モードが使用されます。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	サポートされていません。
委任 (個人用 Microsoft アカウント)	サポートされていません。
Application	Chat.Read.All

例

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated,deleted",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

チャネル内のメッセージと応答を追跡するには、をサブスクライブすることで、チャネルレベルで変更通知サブスクリプションを /teams/{team-id}/channels/{channel-id}/messages作成できます。このリソースは、委任モードとアプリケーション専用モードの両方において、通知のリソースデータを含めてサポートします。

チャネルレベルのサブスクリプションは、$search クエリパラメータを介したキーワードベースの検索もサポートします。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	ChannelMessage.Read.All
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	ChannelMessage.Read.Group*、ChannelMessage.Read.All

注: * でマークされた権限は、リソース固有の同意の一部としてサポートされます。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

次の要求は、含まれる Hello メッセージをサブスクライバーに送信します。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

特定のユーザーが言及されたメッセージについてのみ通知を取得するには、クエリでユーザーの ID (この例では9a6eb4d1-826b-48b1-9627-b50836c8fee9 ) を指定します。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

チャット内のメッセージを追跡するには、をサブスクライブすることで、チャットレベルで変更通知サブスクリプションを /chats/{chat-id}/messages作成できます。このリソースは、委任モードとアプリケーション専用モードの両方において、通知のリソースデータを含めてサポートします。

チャットレベルのサブスクリプションは、$search クエリパラメータを介したキーワードベースの検索もサポートしています。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	Chat.Read
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	ChatMessage.Read.Chat*、Chat.Read.All

注: * でマークされた権限は、現在、ベータ版のリソース固有の同意の一部としてのみサポートされます。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

次の要求は、含まれる Hello メッセージをサブスクライバーに送信します。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

特定のユーザーが言及されたメッセージにのみ通知を取得するには、クエリでユーザーの ID (この例では9a6eb4d1-826b-48b1-9627-b50836c8fee9 ) を指定します。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

特定のユーザーが参加しているすべてのチャットでメッセージを追跡するには、をサブスクライブすることで、ユーザーレベルで変更通知サブスクリプションを /users/{user-id}/chats/getAllMessages作成できます。このリソースは、委任モードとアプリケーション専用モードの両方において、通知のリソースデータを含めてサポートします。

ユーザーレベルのチャットメッセージサブスクリプションは、$search クエリパラメータを介したキーワードベースの検索もサポートしています。

注: この API には、ライセンス要件と支払い要件があります。 model=B クエリパラメーターがサポートされています。モデルが指定されていない場合は、評価モードが使用されます。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	Chat.Read、Chat.ReadWrite
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	Chat.Read.All、Chat.ReadWrite.All

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated,deleted",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/{user-id}/chats/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

特定の Teams アプリがインストールされているテナント内のチャット全体のすべてのメッセージの変更通知を取得するには、をサブスクライブします /appCatalogs/teamsApps/{teams-app-id}/installedToChats/getAllMessages。このリソースは、通知へのリソースデータの組み込みをサポートします。

注: この API には、ライセンス要件と支払い要件があります。 model=B クエリパラメーターがサポートされています。モデルが指定されていない場合は、評価モードが使用されます。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	サポートされていません。
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled

例

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/appCatalogs/teamsApps/386bbcdb-1e1c-4f3f-b7d0-ad7b9ea6cf7c/installedToChats/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

通知のペイロード

購読内容に応じて、リソースデータを使用して通知を受け取ることも、受け取らないこともできます。リソースデータを購読すると、通知とともにメッセージペイロードを取得できるため、コールバックしてコンテンツを取得する必要がなくなります。

リソースデータを使用した通知

リソースデータを含む通知の場合、ペイロードは次のようになります。このペイロードは、チャットで送信されるメッセージ用です。

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.chatMessage",
            "@odata.id": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

復号化された通知のペイロードは次のようになります。ペイロードが chatMessage スキーマに準拠しています。ペイロードは、GET 操作によって返されるものと同様です。

{
  "id": "1612289992105",
  "replyToId": null,
  "etag": "1612289992105",
  "messageType": "message",
  "createdDateTime": "2021-02-02T18:19:52Z",
  "lastModifiedDateTime": "2021-02-02T18:19:52.105Z",
  "lastEditedDateTime": null,
  "deletedDateTime": null,
  "subject": null,
  "summary": null,
  "chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces",
  "importance": "normal",
  "locale": "en-us",
  "webUrl": null,
  "from": {
    "application": null,
    "device": null,
    "user": {
      "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
      "displayName": "Ramjot Singh",
      "userIdentityType": "aadUser"
    },
    "conversation": null
  },
  "body": {
    "contentType": "text",
    "content": "test"
  },
  "channelIdentity": null,
  "attachments": [],
  "mentions": [],
  "policyViolation": null,
  "reactions": [],
  "replies": [],
  "hostedContents": []
}

リソースデータを使用しない通知

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

ペイロードは次のようになります。このペイロードは、チャネルで送信されるメッセージ用です。

 {
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.chatMessage",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')"
  }
}

resource および @odata.id プロパティを使用して、Microsoft Graph を呼び出し、メッセージのペイロードを取得できます。 GET 呼び出しは常にメッセージの現在の状態を返します。通知が送信されてからメッセージが取得されてからメッセージが変更された場合、操作は更新されたメッセージを返します。

Microsoft Graph を使用して、Teams チャネルおよびチャットのメッセージの変更通知を受け取る

アクセス許可

例

アクセス許可

例

アクセス許可

アクセス許可

アクセス許可

アクセス許可

例

通知のペイロード

リソースデータを使用した通知

リソースデータを使用しない通知

フィードバック

フィードバック

その他のリソース

Microsoft Graph を使用して、Teams チャネルおよびチャットのメッセージの変更通知を受け取る

テナント レベルで変更をサブスクリプションする

すべてのチャネル間でメッセージをサブスクリプションする

アクセス許可

例

すべてのチャット全体でメッセージをサブスクリプションする

アクセス許可

例

チャネル内のメッセージをサブスクリプションする

アクセス許可

例 1: チャネル内のすべてのメッセージ (および返信) をサブスクリプションする

例 2: 特定のテキストを含むチャネルでメッセージ (および返信) をサブスクリプションする

例 3: リソース データのないチャネルでメッセージ (および返信) をサブスクリプションする

例 4: 特定のユーザーについて記述するチャネルでメッセージ (および返信) をサブスクリプションする

チャットでメッセージをサブスクリプションする

アクセス許可

例 1: チャットでメッセージをサブスクリプションする

例 2: 特定のテキストを含むチャットのメッセージをサブスクリプションする

例 3: リソース データなしのチャットのメッセージ (および返信) をサブスクリプションする

例 4: 特定のユーザーが言及されているチャットのメッセージをサブスクリプションする

ユーザー レベルで変更をサブスクリプションする

アクセス許可

例: 特定のユーザーが参加しているすべてのチャットでメッセージを購読する

特定の Teams アプリがインストールされているテナント内のチャットのメッセージをサブスクライブする

アクセス許可

例

通知のペイロード

リソース データを使用した通知

リソース データを使用しない通知

関連コンテンツ

フィードバック

フィードバック

その他のリソース

テナントレベルで変更をサブスクリプションする

例 3: リソースデータのないチャネルでメッセージ (および返信) をサブスクリプションする

例 3: リソースデータなしのチャットのメッセージ (および返信) をサブスクリプションする

ユーザーレベルで変更をサブスクリプションする

リソースデータを使用した通知

リソースデータを使用しない通知