Microsoft Graph を使用してチームとチャネルの変更通知を受け取る

  • [アーティクル]

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

引き続き、 チーム または チャネル リソースのシナリオに関する記事を参照してください。 または、 他のMicrosoft Teams リソースの変更通知について説明します。

注:

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

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

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

アクセス許可

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

例

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

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

特定のチームの変更をサブスクライブする

テナント内の特定のチームに関連するすべての変更の変更通知を受け取るには、/teams/{team-id} をサブスクライブします。 このリソースは、通知へのリソース データの組み込みをサポートします。

アクセス許可

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

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

例

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

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

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

テナント内の 任意のチャネル に関連するすべての変更 (作成、更新、削除) の変更通知を取得するには、 /teams/getAllChannelsをサブスクライブします。 このリソースは、通知へのリソース データの組み込みをサポートします。

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

アクセス許可

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

例

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

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

特定のチームの任意のチャネルの変更をサブスクライブする

特定のチームの任意のチャネルに関連するすべての変更の変更通知を受け取るには、/teams/{team-id}/channels をサブスクライブします。 このリソースは、通知へのリソース データの組み込みをサポートします。

このリソースの通知を生成するイベントの例を次に示します。

  • チャネルの表示名がチームで更新されます。
  • プライベート チャネルがチームに作成されます。
  • このチームが所有する共有チャネルは、別のチームと共有または共有解除されます。
  • 別のチームが所有する共有チャネルは、このチームと共有されます。
  • チャネルのプロパティ ( isFavoriteByDefault や description など) が更新されます。
  • チャネルが削除されます。

手記： 委任されたコンテキストの場合、承認されたユーザーのみがプライベート/共有チャネルの通知を受け取ります。 たとえば、チーム (ゲストを除く) に属するすべてのユーザーは、委任されたコンテキストでこのリソースをサブスクライブできますが、プライベート チャネルと共有チャネルにアクセスできるユーザーのみが、それらのチャネルで発生したイベントの通知を受け取ります。

アクセス許可

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

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

例

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

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels",
  "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": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.Team",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

注:discoverySettings と classSettings はペイロード データでは公開されません。

{
  "id": "4c533ad3-e1dd-4277-a672-92ab64ed225c",
  "createdDateTime": "2021-03-18T10:31:14.597Z",
  "displayName": "Sample name",
  "description": "Sample description",
  "internalId": "19:2077546f765a42c1ba71236f4df70aa2@thread.tacv2",
  "specialization": "none",
  "visibility": "public",
  "webUrl": "https://teams.microsoft.com/l/team/19:2077546f724a42c1ba71236f4df79aa2%40thread.tacv2/conversations?groupId=4c533ad3-e1dd-4277-a672-92ab64ed225c&tenantId=0f2e8f59-862a-483b-9ca8-82a10665e17d",
  "isArchived": false,
  "isMembershipLimitedToOwners": false,
  "memberSettings": {
    "allowCreateUpdateChannels": true,
    "allowCreatePrivateChannels": true,
    "allowDeleteChannels": true,
    "allowAddRemoveApps": true,
    "allowCreateUpdateRemoveTabs": true,
    "allowCreateUpdateRemoveConnectors": true
  },
  "guestSettings": {
    "allowCreateUpdateChannels": false,
    "allowDeleteChannels": false
  },
  "messagingSettings": {
    "allowUserEditMessages": true,
    "allowUserDeleteMessages": true,
    "allowOwnerDeleteMessages": true,
    "allowTeamMentions": true,
    "allowChannelMentions": true
  },
  "funSettings": {
    "allowGiphy": true,
    "giphyContentRating": "moderate",
    "allowStickersAndMemes": true,
    "allowCustomMemes": true
  }
}

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

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')",
        "resourceData": {
            "id": "19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2",
            "@odata.type": "#Microsoft.Graph.Channel",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

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

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

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

{
  "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')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.Teams",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')"
  }
}

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

注: チャネルのメール アドレスはペイロードに返されません。

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

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

関連コンテンツ