Поделиться через

Получение уведомлений об изменениях для взаимодействия с ИИ Copilot с помощью Microsoft Graph

  • Статья

Уведомления об изменениях позволяют подписаться на Copilot aiInteractions в Microsoft 365. Вы можете получать уведомления всякий раз, когда происходит новый запрос пользователя к Copilot или когда Copilot отвечает пользователю. Вы также можете получать данные ресурсов в уведомлениях, что позволяет избежать вызова API для получения полезных данных.

Примечание.

Если вы запрашиваете срок действия подпискиDateTime , который будет составлять более одного часа в будущем, необходимо подписаться на уведомления о жизненном цикле, включив свойство lifecycleNotificationUrl в запрос подписки. В противном случае запрос подписки завершается ошибкой со следующим сообщением об ошибке: lifecycleNotificationUrl является обязательным свойством для создания подписки на этом ресурсе, если значение expirationDateTime имеет значение больше 1 часа.

Подписка на взаимодействия Copilot AI для конкретного пользователя (предварительная версия)

Чтобы получать уведомления об изменениях взаимодействия Copilot AI, частью чего является конкретный пользователь, подпишитесь на /copilot/users/{user-id}/interactionHistory/getAllEnterpriseInteractions. Этот ресурс поддерживает включение данных ресурса в уведомление.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) AiEnterpriseInteraction.Read
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение AiEnterpriseInteraction.Read.User*, AiEnterpriseInteraction.Read.All

Примечание. Разрешения, помеченные звездочкой (*), поддерживаются в рамках согласия для конкретных ресурсов.

Требования к лицензированию

Чтобы получить доступ к этому ресурсу уведомления об изменениях, пользователь в пути к ресурсу должен иметь все следующие идентификаторы плана службы Copilot:

  • Соединители Microsoft Graph в Microsoft 365 Copilot: 82d30987-df9b-4486-b146-198b21d164c7
  • Интеллектуальный поиск: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot в Microsoft Teams: b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot в приложениях для повышения производительности: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Соединители Power Platform в Microsoft 365 Copilot: 89f1c4c8-0878-40f7-804d-869c9128ab5d

Пример. Подписка на взаимодействия ИИ Copilot для конкретного пользователя

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. Этот ресурс поддерживает включение данных ресурса в уведомление.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Не поддерживается.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение AiEnterpriseInteraction.Read.All

Требования к лицензированию

Чтобы получить доступ к этому ресурсу уведомления об изменениях, клиент должен иметь все следующие идентификаторы плана службы Copilot, подготовленные и в активном состоянии:

  • Соединители Microsoft Graph в Microsoft 365 Copilot: 82d30987-df9b-4486-b146-198b21d164c7
  • Интеллектуальный поиск: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot в Microsoft Teams: b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot в приложениях для повышения производительности: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Соединители Power Platform в Microsoft 365 Copilot: 89f1c4c8-0878-40f7-804d-869c9128ab5d

Пример. Подписка на взаимодействие ИИ Copilot в клиенте

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

Параметр запроса OData можно использовать для $filter фильтрации взаимодействий Copilot AI, которые не требуются. Например, чтобы подписаться на взаимодействие Copilot AI только для определенного приложения Microsoft 365, например Microsoft Teams, добавьте ?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams' в конец строки ресурса. Чтобы подписаться на все взаимодействия СИ, где conversationType не является Microsoft BizChat, добавьте ?$filter=conversationType ne 'bizchat'.

Примечание.

В настоящее $filter время параметр можно использовать только в свойствах верхнего уровня ресурса aiInteraction . Фильтр по вложенным свойствам не поддерживается; например, ?$filter=from/user/id eq '48902e20-56dc-48cf-ab15-0b65e15dda67' в настоящее время не поддерживается.

Примеры

Пример 1. Подписка на взаимодействие с ИИ Copilot только для Microsoft Teams

В следующем примере показано, как подписаться на взаимодействие Copilot AI только для определенного приложения Microsoft 365, например Microsoft Teams.

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

В следующем примере показано, как подписаться на все взаимодействия СИ, где conversationType не bizchatявляется .

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