通过

使用 Microsoft Graph 获取 Copilot AI 交互的更改通知

  • 项目

更改通知使你能够跨 Microsoft 365 订阅 Copilot aiInteractions 。 每当发生对 Copilot 的新用户查询或 Copilot 响应用户时，你都可以收到通知。 还可以在通知中获取资源数据，这样可以避免调用 API 来获取有效负载。

注意

如果请求的订阅 expirationDateTime 在未来超过一小时，则必须通过在订阅请求中包含 lifecycleNotificationUrl 属性来订阅生命周期通知;否则，订阅请求失败并显示以下错误消息： 当 expirationDateTime 值设置为大于 1 小时时，lifecycleNotificationUrl 是在此资源上创建订阅所需的属性。

订阅特定用户的 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 365 应用程序（如 Microsoft Teams）的 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 365 应用程序（例如 Microsoft Teams）的 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：订阅对话类型未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 更改通知