Compartilhar via

Obter notificações de alteração para interações de IA do Copilot com o Microsoft Graph

  • Artigo

As notificações de alteração permitem-lhe subscrever copilot aiInteractions no Microsoft 365. Pode ser notificado sempre que ocorrer uma nova consulta de utilizador à Copilot ou quando o Copilot responder ao utilizador. Também pode obter os dados de recursos nas notificações, o que lhe permite evitar chamar a API para obter o payload.

Observação

Se pedir uma subscrição expirationDateTime que seja mais de uma hora no futuro, terá de subscrever notificações de ciclo de vida ao incluir uma propriedade lifecycleNotificationUrl no pedido de subscrição; caso contrário, o pedido de subscrição falha com a seguinte mensagem de erro: lifecycleNotificationUrl é uma propriedade necessária para a criação da subscrição neste recurso quando o valor expirationDateTime está definido como superior a 1 hora.

Subscrever interações de IA do Copilot para um determinado utilizador (pré-visualização)

Para obter notificações de alteração para interações de IA do Copilot de que um determinado utilizador faz parte, subscreva ./copilot/users/{user-id}/interactionHistory/getAllEnterpriseInteractions Este recurso oferece suporte a incluindo dados de recursos na notificação.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) AiEnterpriseInteraction.Read
Delegado (conta pessoal da Microsoft) Sem suporte.
Application AiEnterpriseInteraction.Read.User*, AiEnterpriseInteraction.Read.All

Nota: As permissões marcadas com * são suportadas como parte do consentimento específico do recurso.

Requisitos de licenciamento

Para aceder a este recurso de notificação de alteração, o utilizador no caminho do recurso tem de ter todos os seguintes IDs do plano de serviço Copilot ativados:

  • Conectores do Microsoft Graph no Microsoft 365 Copilot: 82d30987-df9b-4486-b146-198b21d164c7
  • Pesquisa inteligente: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot no Microsoft Teams: b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot em aplicações de produtividade: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Conectores do Power Platform no Microsoft 365 Copilot: 89f1c4c8-0878-40f7-804d-869c9128ab5d

Exemplo: Subscrever interações de IA do Copilot para um determinado utilizador

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}"
}

Subscrever interações de IA do Copilot no inquilino (pré-visualização)

Para obter notificações de alteração para interações de IA do Copilot no inquilino, subscreva /copilot/interactionHistory/getAllEnterpriseInteractions. Este recurso oferece suporte a incluindo dados de recursos na notificação.

Permissões

Tipo de permissão Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante) Sem suporte.
Delegado (conta pessoal da Microsoft) Sem suporte.
Application AiEnterpriseInteraction.Read.All

Requisitos de licenciamento

Para aceder a este recurso de notificação de alteração, o inquilino tem de ter todos os seguintes IDs do plano de serviço Copilot aprovisionados e num estado ativo:

  • Conectores do Microsoft Graph no Microsoft 365 Copilot: 82d30987-df9b-4486-b146-198b21d164c7
  • Pesquisa inteligente: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot no Microsoft Teams: b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot em aplicações de produtividade: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Conectores do Power Platform no Microsoft 365 Copilot: 89f1c4c8-0878-40f7-804d-869c9128ab5d

Exemplo: Subscrever interações de IA do Copilot no inquilino

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}"
}

Utilizar $filter para ser notificado apenas de um subconjunto de interações de IA do Copilot

Pode utilizar o $filter parâmetro de consulta OData para filtrar interações de IA do Copilot que não são necessárias. Por exemplo, para subscrever interações de IA do Copilot apenas para uma determinada aplicação do Microsoft 365, como o Microsoft Teams, acrescente ?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams' ao fim da cadeia de recursos. Para subscrever todas as interações de IA em que o conversationType não é o Microsoft BizChat, acrescente ?$filter=conversationType ne 'bizchat'.

Observação

Atualmente, o $filter parâmetro só pode ser utilizado nas propriedades de nível superior do recurso aiInteraction . O filtro de propriedades aninhadas não é suportado; por exemplo, ?$filter=from/user/id eq '48902e20-56dc-48cf-ab15-0b65e15dda67' não é atualmente suportado.

Exemplos

Exemplo 1: subscrever interações de IA do Copilot apenas para o Microsoft Teams

O exemplo seguinte mostra como subscrever interações de IA do Copilot apenas para uma determinada aplicação do Microsoft 365, como o 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}"
}

Exemplo 2: subscrever todas as interações de IA em que o conversationType não é o Microsoft BizChat

O exemplo seguinte mostra como subscrever todas as interações de IA em que o conversationType não 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}"
}

Notificações com dados de recursos

Para notificações com dados de recursos, a carga se parece com a seguinte.

{
  "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-->>"
  ]
}

Para obter detalhes sobre como validar tokens e descriptografar a carga útil, consulte Definir notificações de alteração que incluem dados de recursos.

A carga de notificação descriptografada parece com a seguinte. O payload está em conformidade com o esquema 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": []
}

Notificações sem dados de recursos

Notificações sem dados de recursos dão informações suficientes para fazer chamadas GET para obter o conteúdo da mensagem. As subscrições para notificações sem dados de recursos não necessitam de um certificado de encriptação (porque o Microsoft Graph não envia os dados de recursos reais).

O payload desencriptado seguinte descreve as informações enviadas num pedido de notificações sem dados de recursos. Este payload específico significa que foi criada uma nova interação.

{
  "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')"
  }
}

Conteúdo relacionado

Notificações de alteração do Microsoft Graph