次の方法で共有

Microsoft Graph を使用して Copilot AI インタラクションの変更通知を取得する

  • [アーティクル]

変更通知を使用すると、Microsoft 365 全体で Copilot aiInteractions をサブスクライブできます。 Copilot に対する新しいユーザー クエリが発生したとき、または Copilot がユーザーに応答するたびに通知を受け取ることができます。 通知でリソース データを取得することもできます。これにより、API を呼び出してペイロードを取得しないようにすることができます。

注:

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

特定のユーザーの Copilot AI 操作をサブスクライブする (プレビュー)

特定のユーザーが参加している Copilot AI インタラクションの変更通知を取得するには、 /copilot/users/{user-id}/interactionHistory/getAllEnterpriseInteractionsをサブスクライブします。 このリソースは、通知へのリソース データの組み込みをサポートします。

アクセス許可

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

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

ライセンスの要件

この変更通知リソースにアクセスするには、リソース パスのユーザーで、次のすべての Copilot サービス プラン ID が有効になっている必要があります。

  • Microsoft 365 Copilotの Microsoft Graph コネクタ: 82d30987-df9b-4486-b146-198b21d164c7
  • インテリジェント検索: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft TeamsのMicrosoft 365 Copilot: b95945de-b3bd-46db-8437-f2beb6ea2347
  • 生産性アプリのMicrosoft 365 Copilot: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Microsoft 365 Copilotの Power Platform コネクタ: 89f1c4c8-0878-40f7-804d-869c9128ab5d

例: 特定のユーザーの Copilot AI インタラクションをサブスクライブする

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

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

テナント全体で Copilot AI の対話をサブスクライブする (プレビュー)

テナント全体で Copilot AI 操作の変更通知を取得するには、 /copilot/interactionHistory/getAllEnterpriseInteractionsをサブスクライブします。 このリソースは、通知へのリソース データの組み込みをサポートします。

アクセス許可

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

ライセンスの要件

この変更通知リソースにアクセスするには、テナントに次のすべての Copilot サービス プラン ID がプロビジョニングされ、アクティブな状態である必要があります。

  • Microsoft 365 Copilotの Microsoft Graph コネクタ: 82d30987-df9b-4486-b146-198b21d164c7
  • インテリジェント検索: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft TeamsのMicrosoft 365 Copilot: b95945de-b3bd-46db-8437-f2beb6ea2347
  • 生産性アプリのMicrosoft 365 Copilot: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Microsoft 365 Copilotの Power Platform コネクタ: 89f1c4c8-0878-40f7-804d-869c9128ab5d

例: テナント全体で Copilot AI の対話をサブスクライブする

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

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/copilot/interactionHistory/getAllEnterpriseInteractions",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-08-10T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

$filterを使用して Copilot AI インタラクションのサブセットのみを通知する

$filter OData クエリ パラメーターを使用して、不要な Copilot AI の相互作用を除外できます。 たとえば、Microsoft Teamsなど、特定の Microsoft 365 アプリケーションに対してのみ Copilot AI 対話をサブスクライブするには、リソース文字列の末尾に ?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams' を追加します。 conversationType が Microsoft BizChat ではないすべての AI 操作をサブスクライブするには、?$filter=conversationType ne 'bizchat'を追加します。

注:

現在、 $filter パラメーターは aiInteraction リソースの最上位のプロパティでのみ使用できます。 入れ子になったプロパティのフィルターはサポートされていません。たとえば、 ?$filter=from/user/id eq '48902e20-56dc-48cf-ab15-0b65e15dda67' は現在サポートされていません。

例

例 1: Microsoft Teamsのみの Copilot AI インタラクションをサブスクライブする

次の例は、Microsoft Teamsなど、特定の Microsoft 365 アプリケーションに対してのみ Copilot AI の対話をサブスクライブする方法を示しています。

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

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/copilot/interactionHistory/getAllEnterpriseInteractions?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams'",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-08-10T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

例 2: conversationType が Microsoft BizChat ではないすべての AI インタラクションをサブスクライブする

次の例は、 conversationType が bizchatされていないすべての AI 操作をサブスクライブする方法を示しています。

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

{
  "changeType": "created,deleted,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/copilot/interactionHistory/getAllEnterpriseInteractions?$filter=conversationType ne 'bizchat'",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-08-10T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

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

リソース データを含む通知の場合、ペイロードは次のようになります。

{
  "value": [
    {
      "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
      "changeType": "created",
      "clientState": "<<--SpecifiedClientState-->>",
      "subscriptionExpirationDateTime": "2025-02-02T10:30:34.9097561-08:00",
      "resource": "copilot/interactionHistory/interactions('1731701801008')",
      "resourceData": {
        "id": "1731701801008",
        "@odata.type": "#Microsoft.Graph.aiInteraction",
        "@odata.id": "copilot/interactionHistory/interactions('1731701801008')"
      },
      "encryptedContent": {
        "data": "<<--EncryptedContent-->",
        "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
        "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
        "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
      },
      "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }
  ],
  "validationTokens": [
    "<<--ValidationTokens-->>"
  ]
}

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

復号化された通知のペイロードは次のようになります。 ペイロードは aiInteraction スキーマに準拠しています。

{
  "id": "1731701801008",
  "sessionId": "19:icg2t_AWPYJyJ2oDLB_CZyh29QXpZvbdpljKf7qKotk1@thread.v2",
  "requestId": "7336770c-fb25-48ac-8303-4493ad11ed71",
  "appClass": "IPM.SkypeTeams.Message.Copilot.Teams",
  "interactionType": "aiResponse",
  "conversationType": "appchat",
  "etag": "1731701801008",
  "createdDateTime": "2024-11-15T20:16:41.008Z",
  "locale": "en-us",
  "contexts": [
    {
      "contextReference": "https://microsoft.teams.com/threads/19:meeting_YjQ4NThlNzUtMjEyNC00MjFlLTk0ODMtZTc2M2Q5MDVlNTE4@thread.v2",
      "displayName": "Teams Meeting Copilot",
      "contextType": "TeamsMeeting"
    }
  ],
  "from": {
    "@odata.type": "#microsoft.graph.chatMessageFromIdentitySet",
    "device": null,
    "user": null,
    "application": {
      "@odata.type": "#microsoft.graph.teamworkApplicationIdentity",
      "id": "fb8d773d-7ef8-4ec0-a117-179f88add510",
      "displayName": "Copilot in Teams",
      "applicationIdentityType": "bot"
    }
  },
  "body": {
    "contentType": "text",
    "content": "I use the transcript to generate insights, and need to hear more discussion before I can get to work. Please try again in a few minutes.<attachment id=\"19:meeting_YjQ4NThlNzUtMjEyNC00MjFlLTk0ODMtZTc2M2Q5MDVlNTE4@thread.v2\"></attachment>"
  },
  "attachments": [
    {
      "attachmentId": "19:meeting_YjQ4NThlNzUtMjEyNC00MjFlLTk0ODMtZTc2M2Q5MDVlNTE4@thread.v2",
      "contentType": "reference",
      "contentUrl": "https://microsoft.teams.com/threads/19:meeting_YjQ4NThlNzUtMjEyNC00MjFlLTk0ODMtZTc2M2Q5MDVlNTE4@thread.v2",
      "content": null,
      "name": "Teams Meeting Copilot"
    }
  ],
  "links": [],
  "mentions": []
}

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

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

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

{
  "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
  "changeType": "created",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2025-02-02T10:30:34.9097561-08:00",
  "resource": "copilot/interactionHistory/interactions('1731701801008')",
  "resourceData": {
    "id": "1731701801008",
    "@odata.type": "#Microsoft.Graph.aiInteraction",
    "@odata.id": "copilot/interactionHistory/interactions('1731701801008')"
  }
}

関連コンテンツ

Microsoft Graph の変更通知