Microsoft Graph を使用して、チャット向けメッセージの変更通知を受け取る

変更通知を使用するとチャットへの変更 (作成および更新) を購読できます。 チャットが作成または更新されるたびに通知を受け取ることができます。 通知のリソース データを取得することもできます。したがって、API を呼び出してペイロードを取得する必要はありません。

チャット リソースのシナリオについては、この記事に進んでください。 または、 他のMicrosoft Teams リソースの変更通知について説明します。

注:

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

テナント レベルで任意のチャットの変更をサブスクライブする

テナント内の任意のチャットに関連するすべての変更 (作成および更新) の変更通知を受け取るには、/chats をサブスクライブします。 このリソースは、通知へのリソース データの組み込みをサポートします。

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	サポートされていません。
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	Chat.ReadBasic.All、 Chat.Read.All、 Chat.ReadWrite.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",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

特定のチャットの変更をサブスクライブする

特定のチャットに関連するすべての変更の変更通知を受け取るには、/chats/{id} をサブスクライブします。 このリソースは、通知にリソース データを含め、ユーザー コンテキストで notifyOnUserSpecificProperties クエリ文字列パラメーターを提供することをサポートします。

アクセス許可

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

注: * でマークされた権限は、リソース固有の同意を使用します。

例 1: 特定のチャットの変更をサブスクライブする

次の例は、特定のチャットで変更の通知を受信するためにサブスクライブする方法を示しています。

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

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

例 2: notifyOnUserSpecificProperties クエリ パラメーターを使用して、特定のチャットの変更をサブスクライブする

次の例は、 notifyOnUserSpecificProperties クエリ パラメーターを指定して、特定のチャットの変更の通知を受信するためにサブスクライブする方法を示しています。

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

{
  "changeType": "updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{id}?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

ユーザー レベルでチャットの変更をサブスクライブする (プレビュー)

特定のユーザーが参加しているすべてのチャットのすべての変更に関する変更通知を取得するには、 をサブスクライブします /users/{user-id}/chats。 このリソースは、通知にリソース データを含め、ユーザー コンテキストで notifyOnUserSpecificProperties クエリ文字列パラメーターを提供することをサポートします。

アクセス許可

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

例 1: ユーザー レベルのチャットの変更をサブスクライブする

次の例は、特定のユーザーが参加しているすべてのチャットで変更の通知を受信するためにサブスクライブする方法を示しています。

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

例 2: パスを使用してユーザー レベルのチャットの変更をサブスクライブするme

次の例は、サインインしているユーザーが参加しているすべてのチャットで変更の通知を受信するためにサブスクライブする方法を示しています。

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/me/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

例 3: notifyOnUserSpecificProperties クエリ パラメーターを使用して、ユーザー レベルのチャットの変更をサブスクライブする

次の例では、 notifyOnUserSpecificProperties クエリ パラメーターを指定して、特定のユーザーが参加しているすべてのチャットで変更の通知を受信するようにサブスクライブする方法を示します。

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

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

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

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

アクセス許可

アクセス許可の種類	アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント)	サポートされていません。
委任 (個人用 Microsoft アカウント)	サポートされていません。
アプリケーション	Chat.ReadBasic.WhereInstalled、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",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

通知のペイロード

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

リソース データを含む通知の場合、ペイロードは次のようになります。 このペイロードは、チャットのプロパティ変更用です。

{
    "value": [{
        "subscriptionId": "352887e3-9be0-4b6f-a4e6-dec118d857db",
        "changeType": "Created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-06-03T09:50:37.719033+00:00",
        "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
        "resourceData": {
            "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
            "@odata.type": "#microsoft.graph.chat",
            "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
        },
        "EncryptedContent": {
            "data": "<<--EncryptedContent-->>",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        }
            "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
        }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

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

{
  "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
  "topic": null,
  "createdDateTime": "2021-06-03T14:25:04+05:30",
  "lastUpdatedDateTime": "2021-06-03T14:25:04.387Z",
  "chatType": "oneOnOne",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438%40unq.gbl.spaces/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyM5NzZmNGIzMS1mZDAxLTRlMGItOTE3OC0yOWNjNDBjMTQ0Mzg=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    },
    {
      "userId": "ee723d3d-22d0-4394-9c32-5764d68f4672",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyNlZTcyM2QzZC0yMmQwLTQzOTQtOWMzMi01NzY0ZDY4ZjQ2NzI=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

ユーザー固有のプロパティの通知ペイロード

サブスクリプションの作成時にクエリ文字列パラメーター notifyOnUserSpecificProperties に値 true を指定すると、異なる情報セットを持つ 2 種類のペイロードがサブスクライバーに送信されます。 1 つの型には、ユーザー固有のプロパティが含まれています。もう 1 つのプロパティには、ユーザー固有のプロパティは含まれません。

注: クエリ文字列パラメーター notifyOnUserSpecificProperties は、ユーザー コンテキストのチャット サブスクリプション (特に特定のチャットまたはユーザー レベルのサブスクリプション) でのみサポートされます。

次のペイロードは、ユーザー固有のプロパティを含む通知の要求で送信される情報について説明します。 ペイロードには、サブスクライブしているユーザーに固有の null 以外の値を持つ viewpoint プロパティなど、チャット スキーマのプロパティのサブセットが含まれています。 チャット スキーマからの他のプロパティの省略は、値の変更を意味するものではありません。

注: ユーザーが Teams クライアントでチャットを非表示にすると、ビューポイント プロパティで のisHidden: true通知を受け取ります。ただし、新しいメッセージが到着した後にチャットが再び表示されると、 のisHidden: false通知は送信されません。 チャットが非表示でなくなったかどうかを判断するには、サブスクライバーは、viewpoint プロパティの lastMessageReadDateTime を新しいメッセージの createdDateTime と比較する必要があります。 createdDateTime が lastMessageReadDateTime より後の場合、チャットが表示されます。 サブスクライバーは、非表示のチャットで新しいメッセージが通知されるように、チャット内のメッセージに関する 変更通知を受信 するアクティブなサブスクリプションを持っている必要があります。 ユーザーがチャットを開き、新しいメッセージを読み取ると、通知が送信され、viewpoint プロパティに lastMessageReadDateTime が更新されますisHidden: false。

{
  "id": "19:a1d516d162d441f38cd474916913c806@thread.v2",
  "topic": "Feature Crew",
  "createdDateTime": "2024-04-22T15:14:04.624Z",
  "lastUpdatedDateTime": "2024-04-23T14:37:53.87Z",
  "chatType": "group",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "viewpoint": {
    "isHidden": false,
    "lastMessageReadDateTime": "2024-04-22T15:18:59.228Z"
  }
}

次のペイロードは、ユーザー固有のプロパティを含まない通知の要求で送信される情報について説明します。 ペイロードには 、viewpoint プロパティは含まれません。ただし、この状況は、ユーザーの値の変更を意味するものではありません。

{
  "id": "19:2a81219665e6448da23022ddb949f693@thread.v2",
  "topic": "Group chat",
  "createdDateTime": "2024-04-22T15:02:57Z",
  "lastUpdatedDateTime": "2024-04-23T14:55:20.545Z",
  "chatType": "group",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A2a81219665e6448da23022ddb949f693%40thread.v2/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "4595d2f2-7b31-446c-84fd-9b795e63114b",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "7d898072-792c-4006-bb10-5ca9f2590649",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "c27c1b19-3904-4822-9813-4f6bdaab2eae",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

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

次の復号化されたペイロードは、リソース データを含まない通知の要求で送信される情報について説明します。 この特別なペイロードは、新しいチャットが作成されたことを示します。

{
  "subscriptionId": "8d85051d-779d-45bc-be92-e433f0a5d8ac",
  "changeType": "Created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-06-03T10:26:09.8959595+00:00",
  "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
  "resourceData": {
    "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
    "@odata.type": "#microsoft.graph.chat",
    "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
  }
}

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

関連コンテンツ

• Microsoft Graph の変更通知
• Microsoft Graph を使用してチームとチャネルの変更通知を受け取る
• Microsoft Graph を使用して、チームおよびチャネルのメンバーシップの変更に関する変更通知を受け取る
• Microsoft Graph を使用して、Teams チャネルおよびチャットのメッセージの変更通知を受け取る
• Microsoft Graph を使用して、チャット メンバー向けメッセージの変更通知を受け取る
• Microsoft Teams API の概要
• 通知チームまたはチャネルの C# サンプルを変更する
• 通知チームまたはチャネル Node.js サンプルを変更する