Erstellen effektiver OpenAPI-Beschreibungen zum Erweitern von Microsoft 365 Copilot

API-Plug-Ins ermöglichen es Microsoft 365 Copilot-Agents, mit Webdiensten zu interagieren und auf Echtzeitinformationen zuzugreifen. Mit einem API-Plug-In können Benutzer mit Echtzeitdaten aus ihrem Branchensystem über Befehle in natürlicher Sprache mit einem Agenten innerhalb von Copilot Chat interagieren.

Ein API-Plug-In besteht aus einem API-Dienst, seiner OpenAPI-Beschreibung und einer Manifestdatei. Das Plug-In-Manifest informiert den Copilot-Orchestrator über die Funktionen der API. Das Plug-In-Manifest enthält eine OpenAPI-Beschreibung für den API-Dienst. Die OpenAPI-Beschreibung ist wichtig, da sie Copilot beschreibt, wie eine Verbindung mit der API hergestellt wird. Stellen Sie für eine optimale Auffindbarkeit und Leistung des Plug-Ins mit Copilot eine klare und aussagekräftige OpenAPI-Beschreibung bereit.

In diesem Artikel werden die Elemente beschrieben, die eine OpenAPI-Beschreibung für ein Plug-In effektiv machen, das die Funktionen des Copilot-Agents erweitert.

OpenAPI-Beschreibungselemente

In diesem Abschnitt werden die Elemente einer OpenAPI-Beschreibung und deren Optimierung für Copilot-Agents beschrieben.

OpenAPI-Validierung: Ein guter erster Schritt besteht darin, zu überprüfen, ob Ihre OpenAPI-Beschreibung den Regeln der OpenAPI-Spezifikation entspricht. Sie können Hidi verwenden, ein Befehlszeilentool, das OpenAPI-Beschreibungen neben anderen Anwendungsfällen validieren kann, oder ein anderes Tool Ihrer Wahl. Eine gültige OpenAPI-Beschreibung funktioniert nicht nur gut mit Copilot, sondern stellt auch sicher, dass Ihre OpenAPI-Beschreibung mit anderen Tools funktionieren kann.

Der Info-Abschnitt: Das Beschreibungsfeld ist in der OpenAPI-Spezifikation optional, aber für eine OpenAPI-Beschreibung, die die Copilot-Fähigkeiten erweitern soll, unerlässlich. Copilot benötigt das Beschreibungsfeld, um zu wissen, was die API tut und wann das Plugin verwendet werden soll. Beim Generieren eines Plugin-Manifests aus einem OpenAPI-Dokument wird die Beschreibung im Info-Abschnitt als Beschreibung für das Plugin-Manifest verwendet. Daher ist es wichtig, immer über ein kurzes und klares Beschreibungsfeld zu verfügen. Hier ist zum Beispiel ein Infoabschnitt einer OpenAPI-Beschreibung einer Reparaturwerkstatt.

info:
  title: Repair Service
  description: A simple service to manage repairs for various items
  version: 1.0.0

Vorgangs-IDs: Eine nützliche Technik, um die Benutzerfreundlichkeit einer OpenAPI-Beschreibung zu verbessern, ist das Hinzufügen einer operationID für jede von der API angebotenen Kombination aus API-Pfad und HTTP-Methode. Vorgangs-IDs sind eindeutige Bezeichner für einen Vorgang in der API und werden von Copilot verwendet, um Funktionen zu erstellen, die ausgeführt werden, wenn auf die Eingabeaufforderung eines Benutzers reagiert wird.

Fügen Sie außerdem eine aussagekräftige Beschreibung jeder Operation hinzu, die von Ihrer API unterstützt wird. Nachdem sich Copilot basierend auf der Eingabeaufforderung des Benutzers und der Plug-In-Beschreibung für die Verwendung eines Plug-Ins entschieden hat, durchsucht es die Beschreibungen der Pfade, um den Endpunkt zu bestimmen, der verwendet werden soll, um die Anforderung des Benutzers zu erfüllen.

Vorgangs-IDs werden während des Debuggens als Funktionen angezeigt, um anzugeben, welche Vorgänge Copilot auszuführen versucht. Hier sehen Sie ein Beispiel für ein OpenAPI-Dokument und ein Beispiel für die entsprechende Debuggerausgabe:

paths:
  /repairs:
    get:
      operationId: listRepairs
      summary: List all repairs
      description: Returns a list of repairs with their details and images

Debuggerausgabe:

Abbildung des Debuggers, der die ausgewählte Funktion eines Plugins zeigt.

Parameter: Wenn ein von Ihrer API unterstützter Vorgang Parameter enthält, schließen Sie die Parameter in die OpenAPI-Beschreibung ein. Fügen Sie für jeden Parameter ein Beschreibungsfeld hinzu, um ihn kurz zu beschreiben, und geben Sie gegebenenfalls ein Beispiel für die Verwendung des Parameters an. Parameter werden von Copilot verwendet, um alle erforderlichen Informationen aus der Eingabeaufforderung eines Benutzers für eine Anforderung an die API zu erhalten.

Hier ist ein Beispiel:

parameters:
  - name: assignedTo
    in: query
    description: The name or ID of the person or team to whom the repair is assigned.
    schema:
      type: string
    required: false

Antworten: Definieren Sie klar alle möglichen Antworten für jeden Vorgang, einschließlich Erfolgs- und Fehlerantworten. Jede Antwort muss über einen Status und eine Beschreibung dessen verfügen. Das Einbeziehen von Beispielen für Antworten hilft Copilot zu verstehen, was von der API zu erwarten ist.

responses:
  '200':
    description: A list of repairs
    content:
      application/json:
        schema:
          type: array
          items:
            $ref: '#/components/schemas/Repair'
        examples:
          example1:
            value:
              [
                {
                  "id": "1",
                  "item": "Laptop",
                  "status": "In Progress",
                  "assignedTo": "John Doe"
                }
              ]
  '404':
    description: No repairs found
  '500':
    description: Server error