Partage via

Recevoir des notifications de modification pour les interactions Copilot AI à l’aide de Microsoft Graph

  • Article

Les notifications de modification vous permettent de vous abonner à Copilot aiInteractions dans Microsoft 365. Vous pouvez recevoir une notification chaque fois qu’une nouvelle requête utilisateur sur Copilot se produit ou lorsque Copilot répond à l’utilisateur. Vous pouvez également obtenir les données de ressource dans les notifications, ce qui vous permet d’éviter d’appeler l’API pour obtenir la charge utile.

Remarque

Si vous demandez un expirationDateTime d’abonnement de plus d’une heure à l’avenir, vous devez vous abonner aux notifications de cycle de vie en incluant une propriété lifecycleNotificationUrl dans votre demande d’abonnement . Sinon, votre demande d’abonnement échoue avec le message d’erreur suivant : lifecycleNotificationUrl est une propriété obligatoire pour la création d’abonnement sur cette ressource lorsque la valeur expirationDateTime est définie sur plus d’une heure.

S’abonner aux interactions Copilot AI pour un utilisateur particulier (préversion)

Pour obtenir des notifications de modification pour les interactions Copilot AI dont un utilisateur particulier fait partie, abonnez-vous à /copilot/users/{user-id}/interactionHistory/getAllEnterpriseInteractions. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) AiEnterpriseInteraction.Read
Déléguée (compte Microsoft personnel) Non prise en charge.
Application AiEnterpriseInteraction.Read.User*, AiEnterpriseInteraction.Read.All

Remarque : les autorisations marquées d’un * sont prises en charge dans le cadre du consentement spécifique à la ressource.

Conditions d'octroi de licence

Pour accéder à cette ressource de notification de modification, l’utilisateur dans le chemin d’accès à la ressource doit avoir tous les ID de plan de service Copilot suivants activés :

  • Connecteurs Microsoft Graph dans Microsoft 365 Copilot : 82d30987-df9b-4486-b146-198b21d164c7
  • Recherche intelligente : 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot dans Microsoft Teams : b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot dans les applications de productivité : a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat : 3f30311c-6b1e-48a4-ab79-725b469da960
  • Connecteurs Power Platform dans Microsoft 365 Copilot : 89f1c4c8-0878-40f7-804d-869c9128ab5d

Exemple : S’abonner aux interactions Copilot AI pour un utilisateur particulier

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

S’abonner aux interactions Copilot AI dans le locataire (préversion)

Pour obtenir des notifications de modification pour les interactions Copilot AI dans le locataire, abonnez-vous à /copilot/interactionHistory/getAllEnterpriseInteractions. Cette ressource prend en charge la fonction y compris les données de ressources dans la notification.

Autorisations

Type d’autorisation Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)
Déléguée (compte professionnel ou scolaire) Non prise en charge.
Déléguée (compte Microsoft personnel) Non prise en charge.
Application AiEnterpriseInteraction.Read.All

Conditions d'octroi de licence

Pour accéder à cette ressource de notification de modification, le locataire doit avoir tous les ID de plan de service Copilot suivants approvisionnés et dans un état actif :

  • Connecteurs Microsoft Graph dans Microsoft 365 Copilot : 82d30987-df9b-4486-b146-198b21d164c7
  • Recherche intelligente : 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot dans Microsoft Teams : b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot dans les applications de productivité : a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat : 3f30311c-6b1e-48a4-ab79-725b469da960
  • Connecteurs Power Platform dans Microsoft 365 Copilot : 89f1c4c8-0878-40f7-804d-869c9128ab5d

Exemple : S’abonner aux interactions Copilot AI sur le locataire

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

L’utilisation de $filter d’être averti d’un sous-ensemble d’interactions Copilot AI

Vous pouvez utiliser le $filter paramètre de requête OData pour filtrer les interactions Copilot AI qui ne sont pas nécessaires. Par exemple, pour vous abonner aux interactions Copilot AI pour une application Microsoft 365 particulière, telle que Microsoft Teams, ajoutez ?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams' à la fin de la chaîne de ressource. Pour vous abonner à toutes les interactions IA où conversationType n’est pas Microsoft BizChat, ajoutez ?$filter=conversationType ne 'bizchat'.

Remarque

Actuellement, le $filter paramètre ne peut être utilisé que sur les propriétés de niveau supérieur de la ressource aiInteraction . Le filtre sur les propriétés imbriquées n’est pas pris en charge ; par exemple, ?$filter=from/user/id eq '48902e20-56dc-48cf-ab15-0b65e15dda67' n’est pas pris en charge actuellement.

Exemples

Exemple 1 : S’abonner aux interactions Copilot AI pour Microsoft Teams uniquement

L’exemple suivant montre comment s’abonner aux interactions Copilot AI pour une application Microsoft 365 particulière, telle que 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}"
}

Exemple 2 : S’abonner à toutes les interactions IA pour lesquelles conversationType n’est pas Microsoft BizChat

L’exemple suivant montre comment s’abonner à toutes les interactions IA où conversationType n’est pas 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}"
}

Notifications avec des données de ressource

Pour les notifications avec des données de ressource, la charge utile se présente comme suit.

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

Pour plus d’informations sur la validation des jetons et le déchiffrement de la charge utile, consultez Configurer des notifications de modification comprenant des données de ressource.

La charge utile de la notification déchiffrée se présente comme suit. La charge utile est conforme au schéma 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": []
}

Notifications sans les données de ressource

Les notifications sans les données de ressource vous donnent suffisamment d’informations pour passer des appels GET pour obtenir le contenu du message. Les abonnements pour les notifications sans données de ressource ne nécessitent pas de certificat de chiffrement (car Microsoft Graph n’envoie pas les données de ressource réelles).

La charge utile déchiffrée suivante décrit les informations envoyées dans une demande de notifications sans données de ressource. Cette charge utile particulière signifie qu’une nouvelle interaction a été créée.

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

Contenu connexe

Notifications de modifications Microsoft Graph