Wie man ein OpenAPI-Dokument bei der Erweiterung von Copilot effektiv macht

Mit Plug-Ins können Microsoft Copilot mit Webdiensten arbeiten und Echtzeitinformationen abrufen. Copilot verwendet diese Informationen, um seine Fähigkeiten zu erweitern. Mit einem Plug-In kann ein Benutzer Echtzeitdaten aus dem branchenspezifischen System auf den Copilot übertragen.

Ein Plug-In besteht aus einem API-Dienst, seiner OpenAPI-Beschreibung und einer Manifestdatei. Das Plug-In-Manifest informiert Copilot ü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. Für eine optimale Plug-In-Leistung mit Copilot geben Sie eine klare und aussagekräftige OpenAPI-Beschreibung an. In diesem Dokument werden die Elemente erläutert, die eine OpenAPI-Beschreibung für ein Plug-In, das Copilot erweitert, effektiv machen.

Hier wird davon ausgegangen, dass Sie über eine API und eine OpenAPI-Beschreibung verfügen.

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, ein Befehlszeilentool, das OpenAPI-Beschreibungen unter anderen Anwendungsfällen überprüfen kann, oder ein beliebiges anderes Tool ihrer Wahl verwenden. Eine gültige OpenAPI-Beschreibung funktioniert nicht nur gut mit Copilot, sondern stellt auch sicher, dass Ihre OpenAPI-Beschreibung mit anderen Tools verwendet werden kann.

Infoabschnitt: Das Beschreibungsfeld ist in der OpenAPI-Spezifikation optional, aber es ist wichtig für eine OpenAPI-Beschreibung, die copilot-Fähigkeiten erweitern soll. Copilot benötigt das Beschreibungsfeld, um zu wissen, was die API tut und wann das Plug-In verwendet werden soll. Beim Generieren eines Plug-In-Manifests aus einem OpenAPI-Dokument wird die Beschreibung im Infoabschnitt als Beschreibung für das Plug-In-Manifest verwendet. Daher ist es wichtig, immer ein Beschreibungsfeld zu haben, das kurz und klar ist. Hier ist beispielsweise ein Infoabschnitt einer OpenAPI-Beschreibung eines Reparaturwerks.

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

Vorgangs-IDs: Eine nützliche Methode, um die Benutzerfreundlichkeit einer OpenAPI-Beschreibung zu verbessern, ist das Hinzufügen eines operationID für jede Kombination aus API-Pfad und HTTP-Methode, die von der API angeboten wird. 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.

Fügen Sie außerdem eine aussagekräftige Beschreibung der einzelnen Vorgänge hinzu, die von Ihrer API unterstützt werden. Nachdem Copilot sich für die Verwendung eines Plug-Ins basierend auf der Eingabeaufforderung des Benutzers und der Plug-In-Beschreibung 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 der entsprechenden Debuggerausgabe:

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

Debuggerausgabe:

Parameter: Wenn ein von Ihrer API unterstützter Vorgang Parameter akzeptiert, schließen Sie die Parameter in die OpenAPI-Beschreibung ein. Fügen Sie ein Beschreibungsfeld für jeden Parameter ein, um ihn kurz zu beschreiben, und geben Sie bei Bedarf ein Beispiel für die Verwendung des Parameters an. Parameter werden von Copilot verwendet, um alle erforderlichen Informationen aus der Aufforderung eines Benutzers zum Senden einer Anforderung an die API abzurufen.

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 der Erfolgs- und Fehlerantworten. Jede Antwort muss einen status Code und eine Beschreibung dessen enthalten, was sie darstellt. Das Einschließen 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