Freigeben über

API-Plug-Ins für Microsoft 365 Copilot

  • Artikel

API-Plug-Ins ermöglichen deklarativen Agents in Microsoft 365 Copilot die Interaktion mit REST-APIs mit einer OpenAPI-Beschreibung. Mit einem API-Plug-In können Benutzer einen deklarativen Agent bitten, nicht nur informationen in einer REST-API abzufragen, sondern auch Daten und Objekte zu erstellen, zu aktualisieren und zu löschen. Auf alles, was die REST-API tun kann, kann über Eingabeaufforderungen in natürlicher Sprache zugegriffen werden.

Wichtig

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

Ein API-Plug-In stellt ein OpenAPI-Beschreibungsdokument und ein Plug-In-Manifest bereit, das Copilot verwendet, um die Funktionen der API zu erlernen. Copilot kann dann entscheiden, wann die API eines installierten und aktivierten Plug-Ins geeignet ist, um eine bestimmte Aufforderung zu beantworten. Weitere Informationen zur Manifestdatei, die für ein API-Plug-In erforderlich ist, finden Sie unter API-Plug-In-Manifestschema für Microsoft 365 Copilot.

Betrachten Sie beispielsweise eine Budget-API, die das Abfragen und Erstellen von Budgets, das Berechnen von Ausgaben oder das Hinzufügen von Mitteln zu vorhandenen Budgets ermöglicht. Die Aufforderung "Wie viel ist im Contoso-Reisebudget übrig?" könnte ein Budget-Plug-In auslösen, das den folgenden API-Aufruf vornimmt.

GET /budgets?name=contoso%20travel

Copilot verwendet die Antwort des API-Aufrufs, um seine Antwort zu generieren: "Das Contoso-Reisebudget verfügt derzeit über 5.000 US-Dollar an verfügbaren Mitteln. Wenn Sie Mittel bestimmten Kategorien zuordnen oder Ausgaben nachverfolgen müssen, kann ich Ihnen auch dabei helfen. Lassen Sie mich einfach wissen, wie ich helfen kann!"

Die Aufforderung "500 US-Dollar auf das Contoso-Reisebudget für das Flugticket von Megan berechnen" könnte in den folgenden API-Aufruf übersetzt werden.

POST /budgets/charge
Content-Type: application/json

{
  "budgetName": "Contoso travel",
  "amount": 500,
  "description": "Megan's airline ticket"
}

Copilot antwortet dem Benutzer mit den zurückgegebenen Informationen: "Die Gebühr von 500 US-Dollar für das Flugticket von Megan wurde erfolgreich verarbeitet. Das Contoso-Reisebudget verfügt jetzt über 4.500 US-Dollar an verfügbaren Mitteln. Wenn Sie weitere Transaktionen tätigen oder weitere Unterstützung bei Ihrem Budget benötigen, lassen Sie es mich wissen!"

Funktionsweise von API-Plug-Ins

Ein Sequenzdiagramm, das zeigt, wie ein API-Plug-In funktioniert

  1. Der Benutzer fragt den Agent: "Wie viel bleibt im Budget für die Renovierung der vierten Kaffeelobby übrig?"

  2. Der Agent identifiziert ein budgetbezogenes Plug-In aus seinen verfügbaren Plug-Ins, das über eine Funktion GetBudget zum Abrufen von Budgetdetails verfügt. Es ordnet Teile der Frage des Benutzers den Parametern der Funktion zu: budgetName="".

  3. Der Agent fordert den Benutzer auf, das Senden Fourth Coffee lobby renovation an das Plug-In zuzulassen.

  4. Der Benutzer entscheidet, dass Daten einmal für das Plug-In freigegeben werden, oder er entscheidet, dass Daten für diese Funktion immer freigegeben werden.

  5. Wenn die API des Plug-Ins eine Authentifizierung erfordert, fordert das Plug-In ein Token oder einen API-Schlüssel vom Tokenspeicher an.

  6. Der Tokenspeicher gibt ein Token oder einen Schlüssel zurück. Bei Bedarf veranlasst der Tokenspeicher den Agent, den Benutzer zur Anmeldung aufzufordern.

  7. Der Agent sendet eine Anforderung an die API des Plug-Ins, die außerhalb von Microsoft 365 gehostet wird.

    GET /budgets?budgetName=Fourth+Coffee+lobby+renovation

  8. Die API gibt eine API-Antwort in dem in ihrer OpenAPI-Spezifikation angegebenen Format zurück.

    {
  "name": "Fourth Coffee lobby renovation",
  "availableFunds": 5000.00
}

  9. Der Agent generiert eine Antwort basierend auf der API-Antwort.

  10. Der Agent sendet die Antwort "Die verfügbaren Mittel, die im Vierten Kaffee-Lobby-Renovierungsbudget verbleiben, sind 5000 US-Dollar."

Bestätigen von Aktionen

Copilot fragt den Benutzer vor dem Senden von Daten an ein API-Plug-In.

Screenshot eines Plug-In-Bestätigungsdialogfelds.

Standardmäßig bieten APIs, die nur Daten abrufen, dem Benutzer die Option "Immer zulassen", während APIs, die Daten ändern, dies nicht der Fall ist. Plug-In-Entwickler können diese Standardwerte außer Kraft setzen. Weitere Informationen finden Sie unter Bestätigungsaufforderungen für API-Plug-Ins für Microsoft 365 Copilot.

Anpassen der Antwortpräsentation

Copilot generiert Konversationsantworten mithilfe von Daten aus API-Antworten. Plug-Ins können diese Antworten anpassen, indem sie Vorlagen für adaptive Karten bereitstellen, um Daten auf strukturierte Weise anzuzeigen.

Screenshot einer Antwort für adaptive Karten von einem API-Plug-In

Generieren von API-Plug-In-Paketen

Es gibt zwei Tools, mit denen Entwickler API-Plug-In-Pakete generieren können.

  • Das Teams Toolkit in Visual Studio oder Visual Studio Code kann Plug-In-Pakete basierend auf einer vorhandenen OpenAPI-Beschreibung erstellen. Wenn Sie nicht über eine vorhandene API verfügen, verfügt teams Toolkit auch über Startprojekte mit einer Beispiel-API und einem entsprechenden Plug-In-Paket.
  • Kiota ist ein Befehlszeilentool und eine Visual Studio Code-Erweiterung, die Plug-In-Pakete basierend auf einer vorhandenen OpenAPI-Beschreibung generieren kann.

Begrenzungen

URLs in API-Antworten werden redigiert

Um die Privatsphäre des Benutzers zu schützen, bearbeitet Copilot alle URLs, die in API-Antworten enthalten sind. Die einzige Ausnahme von diesem Verhalten ist jede URL in einer Eigenschaft, die durch die url -Eigenschaft im Eigenschaftenobjekt Der Antwortsemantik angegeben wird.

Verwandte Inhalte