Freigeben über

Abrufen von Änderungsbenachrichtigungen für Copilot KI-Interaktionen mithilfe von Microsoft Graph

  • Artikel

Mit Änderungsbenachrichtigungen können Sie Copilot aiInteractions in Microsoft 365 abonnieren. Sie können benachrichtigt werden, wenn eine neue Benutzerabfrage an Copilot erfolgt oder wenn Copilot dem Benutzer antwortet. Sie können die Ressourcendaten auch in den Benachrichtigungen abrufen, sodass Sie vermeiden können, die API zum Abrufen der Nutzlast aufzurufen.

Hinweis

Wenn Sie ein Abonnement anfordern, das länger als eine Stunde in der Zukunft ist, müssen Sie Lebenszyklusbenachrichtigungen abonnieren, indem Sie eine lifecycleNotificationUrl-Eigenschaft in Ihre Abonnementanforderung einschließen. Andernfalls schlägt Ihre Abonnementanforderung mit der folgenden Fehlermeldung fehl: lifecycleNotificationUrl ist eine erforderliche Eigenschaft für die Abonnementerstellung für diese Ressource, wenn der wert expirationDateTime auf größer als 1 Stunde festgelegt ist.

Abonnieren von Copilot KI-Interaktionen für einen bestimmten Benutzer (Vorschau)

Um Änderungsbenachrichtigungen für Copilot KI-Interaktionen zu erhalten, zu denen ein bestimmter Benutzer gehört, abonnieren Sie /copilot/users/{user-id}/interactionHistory/getAllEnterpriseInteractions. Diese Ressource unterstützt das Einbeziehen von Ressourcendaten in die Benachrichtigung.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) AiEnterpriseInteraction.Read
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung AiEnterpriseInteraction.Read.User*, AiEnterpriseInteraction.Read.All

Hinweis: Mit * markierte Berechtigungen werden als Teil der ressourcenspezifischen Zustimmung unterstützt.

Lizenzierungsanforderungen

Für den Zugriff auf diese Änderungsbenachrichtigungsressource müssen für den Benutzer im Ressourcenpfad alle folgenden Copilot-Dienstplan-IDs aktiviert sein:

  • Microsoft Graph-Connectors in Microsoft 365 Copilot: 82d30987-df9b-4486-b146-198b21d164c7
  • Intelligente Suche: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot in Microsoft Teams: b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot in Produktivitäts-Apps: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Power Platform-Connectors in Microsoft 365 Copilot: 89f1c4c8-0878-40f7-804d-869c9128ab5d

Beispiel: Abonnieren von Copilot KI-Interaktionen für einen bestimmten Benutzer

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

Abonnieren von Copilot KI-Interaktionen im gesamten Mandanten (Vorschau)

Um Änderungsbenachrichtigungen für Copilot KI-Interaktionen im gesamten Mandanten zu erhalten, abonnieren Sie /copilot/interactionHistory/getAllEnterpriseInteractions. Diese Ressource unterstützt das Einbeziehen von Ressourcendaten in die Benachrichtigung.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Nicht unterstützt
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung AiEnterpriseInteraction.Read.All

Lizenzierungsanforderungen

Um auf diese Änderungsbenachrichtigungsressource zugreifen zu können, muss der Mandant über alle folgenden Copilot-Serviceplan-IDs verfügen, die bereitgestellt wurden und sich im aktiven Zustand befinden:

  • Microsoft Graph-Connectors in Microsoft 365 Copilot: 82d30987-df9b-4486-b146-198b21d164c7
  • Intelligente Suche: 931e4a88-a67f-48b5-814f-16a5f1e6028d
  • Microsoft 365 Copilot in Microsoft Teams: b95945de-b3bd-46db-8437-f2beb6ea2347
  • Microsoft 365 Copilot in Produktivitäts-Apps: a62f8878-de10-42f3-b68f-6149a25ceb97
  • Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960
  • Power Platform-Connectors in Microsoft 365 Copilot: 89f1c4c8-0878-40f7-804d-869c9128ab5d

Beispiel: Abonnieren von Copilot KI-Interaktionen im gesamten Mandanten

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

Verwenden von $filter, um nur über eine Teilmenge von Copilot KI-Interaktionen benachrichtigt zu werden

Sie können den $filter OData-Abfrageparameter verwenden, um copilot KI-Interaktionen herauszufiltern, die nicht benötigt werden. Wenn Sie beispielsweise Copilot KI-Interaktionen nur für eine bestimmte Microsoft 365-Anwendung wie Microsoft Teams abonnieren möchten, fügen Sie an das Ende der Ressourcenzeichenfolge an ?$filter=appClass eq 'IPM.SkypeTeams.Message.Copilot.Teams' . Um alle KI-Interaktionen zu abonnieren, bei denen conversationType nicht Microsoft BizChat ist, fügen Sie an ?$filter=conversationType ne 'bizchat'.

Hinweis

Derzeit kann der $filter Parameter nur für die Eigenschaften der obersten Ebene der ressource aiInteraction verwendet werden. Das Filtern nach geschachtelten Eigenschaften wird nicht unterstützt. wird z. B ?$filter=from/user/id eq '48902e20-56dc-48cf-ab15-0b65e15dda67' . derzeit nicht unterstützt.

Beispiele

Beispiel 1: Abonnieren von Copilot KI-Interaktionen nur für Microsoft Teams

Das folgende Beispiel zeigt, wie Copilot KI-Interaktionen nur für eine bestimmte Microsoft 365-Anwendung wie Microsoft Teams abonniert werden.

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

Beispiel 2: Abonnieren aller KI-Interaktionen, bei denen conversationType nicht Microsoft BizChat ist

Das folgende Beispiel zeigt, wie Sie alle KI-Interaktionen abonnieren, bei denen conversationType nicht bizchatist.

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

Benachrichtigungen mit Ressourcendaten

Bei Benachrichtigungen mit Ressourcendaten sieht die Nutzlast wie folgt aus.

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

Einzelheiten zum Validieren von Tokens und Entschlüsseln der Nutzlast finden Sie unter Änderungsbenachrichtigungen einrichten, die Ressourcendaten enthalten.

Die entschlüsselte Benachrichtigungsnutzlast sieht wie folgt aus. Die Nutzlast entspricht dem aiInteraction-Schema .

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

Benachrichtigungen ohne Ressourcendaten

Benachrichtigungen ohne Ressourcendaten enthalten genügend Informationen, um GET-Aufrufe zu tätigen, um Nachrichteninhalte zu erhalten. Abonnements für Benachrichtigungen ohne Ressourcendaten erfordern kein Verschlüsselungszertifikat (da Microsoft Graph die tatsächlichen Ressourcendaten nicht sendet).

Die folgende entschlüsselte Nutzlast beschreibt die Informationen, die in einer Anforderung für Benachrichtigungen ohne Ressourcendaten gesendet werden. Diese spezielle Nutzlast bedeutet, dass eine neue Interaktion erstellt wurde.

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

Verwandte Inhalte

Microsoft Graph-Änderungsbenachrichtigungen