Bestätigungsaufforderungen für API-Plug-Ins für Microsoft 365 Copilot

Wichtig

API-Plug-Ins werden nur als Aktionen in deklarativen Agents unterstützt. Sie sind in Microsoft 365 Copilot nicht aktiviert.

Standardmäßig fordert Microsoft 365 Copilot den Benutzer auf, das Senden von Daten an ein Plug-In zu bestätigen, bevor es sie sendet, um unbeabsichtigte Folgen in externen Systemen zu verhindern. Der Benutzer kann die zu sendenden Daten sehen und hat die Wahl, die Daten zuzulassen oder abzulehnen. Bei einigen API-Vorgängen haben Benutzer die Möglichkeit, das Senden von Daten immer zuzulassen, wodurch zukünftige Bestätigungsaufforderungen für diesen bestimmten Vorgang verhindert werden.

Normalerweise zeigt Microsoft 365 Copilot dem Benutzer die Option immer zulassen für HTTP GET-Vorgänge an und zeigt die Option für POST, PATCH, PUT und DELETE nicht an. API-Plug-In-Entwickler können dieses Verhalten für einzelne Vorgänge in ihrer API ändern. Entwickler können auch den Text anpassen, den Copilot dem Benutzer im Rahmen der Bestätigungsaufforderung anzeigt.

Überschreiben des Eingabeaufforderungsverhaltens

Entwickler können steuern, ob Microsoft 365 Copilot die Option immer zulassen für einen bestimmten Vorgang anzeigt, indem sie die x-openai-isConsequential -Eigenschaft im OpenAPI-Dokument für ihre API hinzufügen. Wenn Sie diese Eigenschaft auf festlegen true , wird die Option Immer zulassen deaktiviert, und wenn Sie sie auf false festlegen, wird sie aktiviert. In der Regel sollte jede Aktion mit Nebenwirkungen im externen System mit true gekennzeichnet werden, um sicherzustellen, dass der Benutzer die Kontrolle hat und unbeabsichtigte Folgen für Aktionen mit Nebenwirkungen im externen System verhindert.

Betrachten Sie beispielsweise eine API, die eine Erinnerung erstellt: POST /reminders. Da es sich um einen POST-Vorgang handelt, fordert Microsoft 365 Copilot den Benutzer bei jeder Verwendung dieser API zur Bestätigung auf und gibt dem Benutzer nicht die Möglichkeit, diesen Vorgang immer zuzulassen.

Um die Option immer zulassen zu aktivieren, fügen Sie die Eigenschaft hinzu, die x-openai-isConsequential auf false festgelegt ist, wie im folgenden Beispiel gezeigt.

post:
  x-openai-isConsequential: false
  summary: Create a new reminder
  description: Create a new budget with a specified name and due date
  operationId: CreateReminder
  requestBody:
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Reminder'
    required: true

Stellen Sie sich nun eine verwandte API vor, die vorhandene Erinnerungen abruft: GET /reminders. Da es sich um eine GET-Option handelt, zeigt Microsoft 365 Copilot dem Benutzer die Option Immer zulassen an.

Dieses Verhalten kann geändert werden, indem auf x-openai-isConsequential true festgelegt hinzugefügt wird.

get:
  x-openai-isConsequential: true
  summary: Get existing reminders
  description: Gets a list of existing reminders
  operationId: GetReminders

Anpassen des Bestätigungstexts

Entwickler können den Bestätigungstext angeben, indem sie die body Eigenschaft im Confirmation-Objekt im Funktionsfunktionsobjekt der Funktion im Plug-In-Manifest festlegen. Der Wert von body sollte ein Hinweis darauf sein, was die Funktion ausführt. Wenn diese Eigenschaft nicht im Manifest vorhanden ist, wird stattdessen die description -Eigenschaft im Function-Objekt verwendet.

{
  "name": "GetBudgets",
  "description": "Returns details including name and available funds of budgets, optionally filtered by budget name",
  "capabilities": {
    "confirmation": {
      "type": "AdaptiveCard",
      "title": "Search budgets",
      "body": "Do you want to allow searching for budgets?"
    }
  }
}