Compartir a través de

Obtención de notificaciones de cambio para interacciones de IA de Copilot mediante Microsoft Graph

  • Artículo

Las notificaciones de cambio le permiten suscribirse a Copilot aiInteractions en Microsoft 365. Puede recibir una notificación cada vez que se produzca una nueva consulta de usuario a Copilot o cuando Copilot responda al usuario. También puede obtener los datos de recursos en las notificaciones, lo que le permite evitar llamar a la API para obtener la carga.

Nota:

Si solicita una expiración de suscripciónDateTime que tenga más de una hora en el futuro, debe suscribirse a las notificaciones de ciclo de vida mediante la inclusión de una propiedad lifecycleNotificationUrl en la solicitud de suscripción; De lo contrario, se produce un error en la solicitud de suscripción con el siguiente mensaje de error: lifecycleNotificationUrl es una propiedad necesaria para la creación de suscripciones en este recurso cuando el valor expirationDateTime se establece en mayor que 1 hora.

Suscribirse a interacciones de IA de Copilot para un usuario determinado (versión preliminar)

Para obtener notificaciones de cambio para las interacciones de IA de Copilot de las que forma parte un usuario determinado, suscríbase a /copilot/users/{user-id}/interactionHistory/getAllEnterpriseInteractions. Este recurso permite incluir datos de recursos en la notificación.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) AiEnterpriseInteraction.Read
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación AiEnterpriseInteraction.Read.User*, AiEnterpriseInteraction.Read.All

Nota: Los permisos marcados con * se admiten como parte del consentimiento específico del recurso.

Requisitos de licencias

Para acceder a este recurso de notificación de cambios, el usuario de la ruta de acceso del recurso debe tener habilitados todos los siguientes identificadores de plan de servicio de Copilot:

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

Ejemplo: Suscribirse a interacciones de IA de Copilot para un usuario determinado

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

Suscribirse a interacciones de IA de Copilot en el inquilino (versión preliminar)

Para obtener notificaciones de cambio para las interacciones de IA de Copilot en el inquilino, suscríbase a /copilot/interactionHistory/getAllEnterpriseInteractions. Este recurso permite incluir datos de recursos en la notificación.

Permisos

Tipo de permiso Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa) No admitida.
Delegado (cuenta personal de Microsoft) No admitida.
Aplicación AiEnterpriseInteraction.Read.All

Requisitos de licencias

Para acceder a este recurso de notificación de cambios, el inquilino debe tener todos los siguientes identificadores de plan de servicio de Copilot aprovisionados y en estado activo:

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

Ejemplo: Suscripción a interacciones de IA de Copilot en el 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}"
}

Uso de $filter para recibir una notificación de solo un subconjunto de interacciones de IA de Copilot

Puede usar el $filter parámetro de consulta OData para filtrar las interacciones de IA de Copilot que no son necesarias. Por ejemplo, para suscribirse a interacciones de IA de Copilot solo para una aplicación de Microsoft 365 determinada, como Microsoft Teams, anexe ?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams' al final de la cadena de recursos. Para suscribirse a todas las interacciones de IA en las que conversationType no es Microsoft BizChat, anexe ?$filter=conversationType ne 'bizchat'.

Nota:

Actualmente, el $filter parámetro solo se puede usar en las propiedades de nivel superior del recurso aiInteraction . No se admite el filtrado de propiedades anidadas; por ejemplo, ?$filter=from/user/id eq '48902e20-56dc-48cf-ab15-0b65e15dda67' no se admite actualmente.

Ejemplos

Ejemplo 1: Suscribirse a interacciones de IA de Copilot solo para Microsoft Teams

En el ejemplo siguiente se muestra cómo suscribirse a las interacciones de IA de Copilot solo para una aplicación determinada de Microsoft 365, como 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}"
}

Ejemplo 2: Suscribirse a todas las interacciones de IA en las que conversationType no es Microsoft BizChat

En el ejemplo siguiente se muestra cómo suscribirse a todas las interacciones de IA en las que conversationType no bizchates .

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

Notificaciones con datos de recursos

Para las notificaciones con datos de recursos, la carga es similar a la siguiente.

{
  "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 obtener más información sobre cómo validar tokens y descifrar la carga, consulte Configurar notificaciones de cambio que incluyan datos de recursos.

La carga de notificación descifrada es similar a la siguiente. La carga se ajusta al 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": []
}

Notificaciones con datos de recursos

Las notificaciones sin datos de recursos le proporcionarán suficiente información para realizar llamadas GET y obtener el contenido del mensaje. Las suscripciones para notificaciones sin datos de recursos no requieren un certificado de cifrado (porque Microsoft Graph no envía los datos de recursos reales).

La siguiente carga descifrada describe la información enviada en una solicitud de notificaciones sin datos de recursos. Esta carga concreta significa que se ha creado una nueva interacción.

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

Contenido relacionado

Notificaciones de cambios en Microsoft Graph