API-Plug-In-Manifestschema 2.2 für Microsoft 365 Copilot

Artikel
11/19/2024

API-Plug-Ins ermöglichen Microsoft 365 Copilot die Interaktion mit REST-APIs, die in einer OpenAPI-Beschreibung beschrieben werden. Die OpenAPI-Beschreibung in einem API-Plug-In beschreibt die REST-APIs, mit denen Copilot interagieren kann. Darüber hinaus enthält ein API-Plug-In eine Plug-In-Manifestdatei, die Metadaten zum Plug-In bereitstellt, z. B. Name, Beschreibung und Version des Plug-Ins. Das Plug-In-Manifest enthält auch Informationen zu den Funktionen des Plug-Ins, z. B. zu den unterstützten APIs und zu den Vorgängen, die es ausführen kann.

Im folgenden Artikel wird das 2.2-Schema beschrieben, das von API-Plug-In-Manifestdateien verwendet wird. Weitere Informationen zu API-Plug-Ins finden Sie unter API-Plug-Ins für Microsoft 365 Copilot.

Änderungen gegenüber der vorherigen Version

Mit dieser Schemaversion werden die folgenden Änderungen gegenüber Version 2.1 eingeführt.

security_info Die -Eigenschaft wurde dem Funktionsfunktionsobjekt hinzugefügt. Mit dieser Eigenschaft können Sie das Verhalten des Plug-Ins nachweisen, um die Risiken des Aufrufs der Funktion zu bewerten.
Die veraltete localization Eigenschaft wurde aus dem Plug-In-Capabilities-Objekt entfernt. Manifeste, die mit dem Teams-Toolkit mithilfe des 2.1-Schemas generiert wurden, enthielten die veraltete localization Eigenschaft. Manifeste, die das 2.2-Schema verwenden, schlagen bei der Überprüfung fehl, wenn diese Eigenschaft enthalten ist.

JSON-Schema

Das in diesem Dokument beschriebene Schema finden Sie hier im JSON-Schemaformat.

Konventionen

Relative Verweise in URLs

Sofern nicht anders angegeben, können alle Eigenschaften, die URLs sind, relative Verweise sein. Relative Verweise im Manifestdokument sind relativ zur Position des Manifestdokuments.

Zeichenfolgenlänge

Sofern nicht anders angegeben, SOLLTEN alle Zeichenfolgeneigenschaften auf 4.000 Zeichen beschränkt sein. Diese Zeichenfolgenlänge verleiht keine akzeptable Größe für das gesamte Dokument. Implementierungen eine frei, ihre eigenen praktischen Grenzen für manifeste Länge aufzuerlegen.

Nicht erkannte Eigenschaften

Json-Objekte, die in diesem Dokument definiert sind, unterstützen nur die beschriebenen Eigenschaften. Nicht erkannte Eigenschaften in einem JSON-Objekt SOLLTEN das gesamte Dokument ungültig machen.

Lokalisierung von Zeichenfolgen

Lokalisierbare Zeichenfolgen können einen Lokalisierungsschlüssel anstelle eines Literalwerts verwenden. Die Syntax ist [[key_name]], wobei key_name der Schlüsselname in der localizationKeys -Eigenschaft in Ihren Lokalisierungsdateien ist. Ausführliche Informationen zur Lokalisierung finden Sie unter Lokalisieren Ihres Agents.

Beispiel für lokalisierte Zeichenfolgen

{
    "schema_version": "v2.2",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

Plug-In-Manifestobjekt

Der Stamm des Plug-In-Manifestdokuments ist ein JSON-Objekt, das Eigenschaften enthält, die das Plug-In beschreiben.

Das Plug-In-Manifestobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`schema_version`	String	Erforderlich. Die Schemaversion. Frühere Versionen sind `v1` und `v2`. Muss auf `v2.2` festgelegt werden.
`name_for_human`	String	Erforderlich. Ein kurzer, für Menschen lesbarer Name für das Plug-In. Es MUSS mindestens ein Zeichen enthalten, das nicht weiß ist. Zeichen, die über 20 hinausgehen, können ignoriert werden. Diese Eigenschaft kann lokalisiert werden.
`namespace`	Zeichenfolge	Veraltet. Optional.
`description_for_model`	Zeichenfolge	Optional. Die Beschreibung für das Plug-In, das für das Modell bereitgestellt wird. Diese Beschreibung sollte beschreiben, wofür das Plug-In vorgesehen ist und unter welchen Umständen seine Funktionen relevant sind. Zeichen, die über 2048 hinausgehen, können ignoriert werden. Diese Eigenschaft kann lokalisiert werden.
`description_for_human`	String	Erforderlich. Eine lesbare Beschreibung des Plug-Ins. Zeichen, die über 100 hinausgehen, können ignoriert werden. Diese Eigenschaft kann lokalisiert werden.
`logo_url`	Zeichenfolge	Optional. Eine URL, die zum Abrufen eines Logos verwendet wird, das möglicherweise vom Orchestrator verwendet wird. Implementierungen KÖNNEN alternative Methoden bereitstellen, um Logos bereitzustellen, die ihren visuellen Anforderungen entsprechen. Diese Eigenschaft kann lokalisiert werden.
`contact_email`	Zeichenfolge	Optional. Eine E-Mail-Adresse eines Kontakts für Sicherheit/Moderation, Support und Deaktivierung.
`legal_info_url`	Zeichenfolge	Optional. Eine absolute URL, die ein Dokument mit den Nutzungsbedingungen für das Plug-In sucht. Diese Eigenschaft kann lokalisiert werden.
`privacy_policy_url`	Zeichenfolge	Optional. Eine absolute URL, die ein Dokument mit der Datenschutzrichtlinie für das Plug-In sucht. Diese Eigenschaft kann lokalisiert werden.
`functions`	Array des Function-Objekts	Optional. Ein Satz von Funktionsobjekten, die die für das Plug-In verfügbaren Funktionen beschreiben. Jeder Funktionsobjektname MUSS innerhalb des Arrays eindeutig sein. Die Reihenfolge des Arrays ist nicht signifikant. Wenn die `functions` Eigenschaft nicht vorhanden ist und eine OpenAPI-Runtime vorhanden ist, werden die Funktionen aus den OpenAPI-Vorgängen abgeleitet.
`runtimes`	Array des OpenAPI-Laufzeitobjekts	Optional. Ein Satz von Laufzeitobjekten, die die vom Plug-In verwendeten Runtimes beschreiben.
`capabilities`	Plug-In-Funktionen-Objekt	Optional. Beschreibt die Funktionen des Plug-Ins.

Funktionsobjekt

Informationen zur Interaktion des Modells mit einer Funktion.

Das Funktionsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`id`	Zeichenfolge	Optional.
`name`	String	Erforderlich. Eine Zeichenfolge, die diese Funktion eindeutig identifiziert. Laufzeitobjekte können auf diesen Bezeichner verweisen, um die Laufzeit an die Funktion zu binden. Wenn die Funktion an eine OpenAPI-Runtime gebunden ist, muss der Wert mit einem `operationId` Wert in der OpenAPI-Beschreibung übereinstimmen. Der Wert muss mit dem `^[A-Za-z0-9_]+$` regulären Ausdruck übereinstimmen.
`description`	Zeichenfolge	Optional. Eine Beschreibung, die besser auf das Modell zugeschnitten ist, z. B. Überlegungen zur Tokenkontextlänge oder Schlüsselwort (keyword) Verwendung für eine verbesserte Plug-In-Eingabeaufforderung.
`parameters`	Funktionsparameterobjekt	Optional. Ein -Objekt, das Eigenschaften enthält, die die Parameter einer Funktion laufzeitunabhängig beschreiben. Sie spiegelt die Form von json-schema wieder, unterstützt jedoch nur eine kleine Teilmenge der JSON-Schemafunktionen. Wenn die `parameters` Eigenschaft nicht vorhanden ist, verwenden Funktionen, die von einem Laufzeitobjekt vom Typ `OpenApi` beschrieben werden, die OpenAPI-Beschreibung, um die Parameter zu bestimmen. Jedes Element im JSON-Objekt ist ein Funktionsparameterobjekt, das die Semantik des Parameters beschreibt.
`returns`	Rückgabeobjekt OR Rich-Rückgabeobjekt	Optional. Beschreibt die Semantik des von der Funktion zurückgegebenen Werts.
`states`	Funktionsstatusobjekt	Optional. Definiert Zustandsobjekte für Orchestratorzustände.
`capabilities`	Funktionsfunktionsobjekt	Optional. Enthält eine Sammlung von Daten, die zum Konfigurieren optionaler Funktionen des Orchestrators beim Aufrufen der Funktion verwendet werden.

Funktionsobjektbeispiel

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

Funktionsparameterobjekt

Ein -Objekt, das verwendet wird, um den Satz von Parametern zu identifizieren, die an die Funktion übergeben werden können. Dieses Objekt ist so strukturiert, dass es die Form eines JSON-Schemaobjekts Spiegel, unterstützt aber nur eine Teilmenge von JSON-Schemaschlüsselwörtern.

Das Funktionsparameterobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`type`	Zeichenfolge	Optional. Der JSON-Schematyp. Muss auf `object` festgelegt werden.
`properties`	Eigenschaftenobjekt für Funktionsparameter	Erforderlich. Ein -Objekt, das parameternamen ihren Definitionen zuordnet.
`required`	Array aus Zeichenfolgen	Optional. Die Namen von Eigenschaften, die erforderliche Parameter sind. Im Gegensatz zum JSON-Schema müssen die Werte in diesem Array mit den in der `properties` -Eigenschaft aufgeführten Namen übereinstimmen.

Beispiel für Funktionsparameterobjekt

{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

Eigenschaftenobjekt für Funktionsparameter

Ein -Objekt, das parameternamen ihren Definitionen zuordnet.

Das Eigenschaftenobjekt der Funktionsparameter enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
Namensabgleich `^[A-Za-z0-9_]+$`	Funktionsparameterobjekt	Optional. Die Parameterdefinition, die dem Parameter entspricht, der dem Eigenschaftennamen entspricht.

Funktionsparameterobjekt

Ein -Objekt, das die Semantik eines Funktionsparameters beschreibt.

Das Funktionsparameterobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`type`	String	Erforderlich. Gibt den Typ des Parameters an. Mögliche Werte: `string`, `array`, `boolean`, `integer`, `number`.
`items`	Funktionsparameterobjekt	Optional. Ein Funktionsparameterobjekt, das ein einzelnes Element in einem Array beschreibt. DARF nur vorhanden sein, wenn `type` ist `array`.
`enum`	Array aus Zeichenfolgen	Optional. Ein Array gültiger Werte für diesen Parameter. DARF nur vorhanden sein, wenn `type` ist `string`.
`description`	Zeichenfolge	Optional. Eine Beschreibung des Parameters.
`default`	Array, Boolean, String, Number, Integer	Optional. Ein Wert des von der -Eigenschaft angegebenen Typs, der `type` den Wert angibt, den die API verwendet, wenn kein Wert für einen optionalen Parameter angegeben wird.

Beispiel für Funktionsparameter

{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

Rückgabeobjekt

Enthält die Semantik des von der Funktion zurückgegebenen Werts.

Das Rückgabeobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`type`	String	Erforderlich. Gibt den Typ des von der API zurückgegebenen Werts an. Mögliche Werte sind: `string`.
`description`	Zeichenfolge	Optional. Eine Beschreibung des von der API zurückgegebenen Werts.

Rich-Rückgabeobjekt

Gibt an, dass die Funktion eine Antwort zurückgibt, die mit dem Rich Responses-Protokoll kompatibel ist.

Das Rich-Rückgabeobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`$ref`	String	Erforderlich. Muss auf `https://copilot.microsoft.com/schemas/rich-response-v1.0.json` festgelegt werden.

Funktionsstatusobjekt

Definiert Zustandsobjekte für Orchestratorzustände.

Das Funktionszustandsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`reasoning`	State-Objekt	Optional. Der Zustand, in dem das Modell Funktionen aufrufen und Berechnungen ausführen kann.
`responding`	State-Objekt	Optional. Der Zustand, in dem das Modell Text generieren kann, der dem Benutzer angezeigt wird. Das Modell kann keine Funktionen im Antwortzustand aufrufen.
`disengaging`	State-Objekt	Optional.

State-Objekt

Enthält spezifische Anweisungen dafür, wann eine Funktion in einem bestimmten Orchestratorzustand aufgerufen wird.

Das Zustandsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`description`	Zeichenfolge	Optional. Beschreibt den Zweck einer Funktion, wenn sie in einem bestimmten Orchestratorzustand verwendet wird.
`instructions`	Array, Zeichenfolge	Optional. Eine Zeichenfolge oder ein Array von Zeichenfolgen, die verwendet werden, um dem Orchestrator Anweisungen zur Verwendung dieser Funktion in einem bestimmten Orchestratorzustand bereitzustellen. Die Angabe einer einzelnen Zeichenfolge gibt die Absicht an, einen vollständigen Satz von Anweisungen bereitzustellen, die alle integrierten Funktionsaufforderungen außer Kraft setzen würden. Die Angabe eines Arrays von Zeichenfolgen gibt an, dass der integrierte Eingabeaufforderungsmechanismus für Funktionen erweitert werden soll.
`examples`	Array, Zeichenfolge	Optional. Eine Zeichenfolge oder ein Array von Zeichenfolgen, die zum Bereitstellen von Beispielen für den Orchestrator verwendet werden, wie diese Funktion aufgerufen werden kann.

State-Objektbeispiel

{
  "functions": [
    {
      "name": "searchEmails",
      "description": "search for Emails from using 3S search Service",
      "states": {
        "reasoning": {
          "description": "\n# `searchEmails(**params) -> str` returns the emails from user's inbox based on search query.",
          "instructions": [
            "Examine the output of `searchEmails(**params) -> str`.",
            "Do not include any information that is not present in the JSON results.",
            "Exclude any irrelevant data from the JSON results",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message extracted from the response JSON.",
            "If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
          ],
          "examples": []
        }
      }
    }
  ]
}

Funktionsfunktionsobjekt

Enthält eine Sammlung von Daten, die zum Konfigurieren optionaler Funktionen des Orchestrators beim Aufrufen der Funktion verwendet werden.

Das Funktionsfunktionsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`confirmation`	Confirmation-Objekt	Optional. Beschreibt ein Bestätigungsdialogfeld, das dem Benutzer vor dem Aufrufen der Funktion angezeigt werden soll.
`response_semantics`	Antwortsemantikobjekt	Optional. Beschreibt, wie der Orchestrator die Antwortnutzlast interpretieren und ein visuelles Rendering bereitstellen kann.
`security_info`	Sicherheitsinformationsobjekt	Optional. Enthält Nachweise über das Verhalten des Plug-Ins, um die Risiken des Aufrufs der Funktion zu bewerten. Wenn diese Eigenschaft nicht angegeben wird, kann die Funktion nicht mit anderen Plug-Ins oder Funktionen des enthaltenden Agents interagieren.

Confirmation-Objekt

Beschreibt, wie der Orchestrator den Benutzer vor dem Aufrufen einer Funktion zur Bestätigung auffordert.

Das Bestätigungsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`type`	Zeichenfolge	Optional. Gibt den Typ der Bestätigung an. Mögliche Werte sind: `None` und `AdaptiveCard`.
`title`	Zeichenfolge	Optional. Der Titel des Bestätigungsdialogfelds. Diese Eigenschaft kann lokalisiert werden.
`body`	Zeichenfolge	Optional. Der Text des Bestätigungsdialogfelds. Diese Eigenschaft kann lokalisiert werden.

Antwortsemantikobjekt

Enthält Informationen, um die Semantik der Antwortnutzlast zu identifizieren und das Rendern dieser Informationen in einer umfassenden visuellen Umgebung mithilfe adaptiver Karten zu ermöglichen.

Das Antwortsemantikobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`data_path`	String	Erforderlich. Eine JSONPath-RFC9535 Abfrage, die einen Satz von Elementen aus der Funktionsantwort identifiziert, die mithilfe der in den einzelnen Elementen angegebenen Vorlage gerendert werden sollen.
`properties`	Eigenschaftenobjekt der Antwortsemantik	Optional. Ermöglicht die Zuordnung von JSONPath-Abfragen zu bekannten Datenelementen. Jede JSONPath-Abfrage ist relativ zu einem Ergebniswert.
`static_template`	Object	Optional. Ein JSON-Objekt, das dem Adaptive Kartenschema und der Vorlagensprache entspricht. Diese adaptive Karte instance wird verwendet, um ein Ergebnis aus der Plug-In-Antwort zu rendern. Dieser Wert wird verwendet, wenn nicht `template_selector` vorhanden ist oder nicht in eine adaptive Karte aufgelöst werden kann.
`oauth_card_path`	Zeichenfolge	Optional.

Beispiel für eine statische Vorlage

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.resources",
        "properties": {
          "title": "$.name",
          "subtitle": "$.location",
          "url": "$.href",
          "information_protection_label": "$.ipLabel"
        },
        "static_template": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.5",
          "body": [
            {
              "type": "TextBlock",
              "text": "${name}",
              "weight": "Bolder"
            },
            {
              "type": "TextBlock",
              "text": "${description}"
            }
          ],
          "action": [
            {
              "type": "Action.OpenUrl",
              "title": "View",
              "text": "${href}"
            }
          ]
        }
      }
    }
  }
}

Beispiel für eine dynamische Vorlage

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

Eigenschaftenobjekt der Antwortsemantik

Ermöglicht die Zuordnung von JSONPath-Abfragen zu bekannten Datenelementen. Jede JSONPath-Abfrage ist relativ zu einem Ergebniswert.

Das Eigenschaftenobjekt der Antwortsemantik enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`title`	Zeichenfolge	Optional. Titel eines Zitats für das Ergebnis.
`subtitle`	Zeichenfolge	Optional. Untertitel eines Zitats für das Ergebnis.
`url`	Zeichenfolge	Optional. URL eines Zitats für das Ergebnis.
`thumbnail_url`	Zeichenfolge	Optional. URL eines Miniaturbilds für das Ergebnis.
`information_protection_label`	Zeichenfolge	Optional. Datenempfindlichkeitsindikator des Ergebnisinhalts.
`template_selector`	Zeichenfolge	Optional. Ein JSONPath-Ausdruck für eine adaptive Karte instance zum Rendern des Ergebnisses verwendet werden.

Sicherheitsinformationsobjekt

Enthält Informationen, die verwendet werden, um das relative Risiko des Aufrufens der Funktion zu bestimmen.

Das Sicherheitsinformationsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`data_handling`	Array aus Zeichenfolgen	Erforderlich. Ein Array von Zeichenfolgen, die das Datenverarbeitungsverhalten der Funktion beschreiben. Gültige Werte sind `GetPublicData`, `GetPrivateData`, `DataTransform`, `DataExport`und `ResourceStateUpdate`.

Datenverarbeitungswerte

Wert	Beschreibung	Beispiel
`GetPublicData`	Gibt an, dass die Funktion Daten aus einer externen Quelle abruft, die keine Authentifizierung erfordert.	Eine Funktion, die einen Dienstaufruf zum Abrufen von Daten von einer öffentlichen Website vornimmt.
`GetPrivateData`	Gibt an, dass die Funktion Daten aus einer externen Quelle abruft, die eine Authentifizierung erfordert, oder aus der aktuellen Anwendung des Benutzers.	Eine Funktion, die Daten aus einer privaten Datenbank oder aus dem aktuell geöffneten Dokument des Benutzers abruft.
`DataTransform`	Gibt an, dass die Funktion nur eine Ausgabe basierend auf der Eingabe zurückgibt, ohne dass neue Daten eingeführt oder eine Ressourcenaktualisierung verursacht wird.	Eine Funktion, die eine Zahl in ein Wort konvertiert oder ein Datum formatiert.
`DataExport`	Gibt an, dass die Funktion Daten an einen Speicherort außerhalb der Funktion selbst sendet oder schreibt.	Eine Funktion, die Daten in einer lokalen oder Clouddatei speichert.
`ResourceStateUpdate`	Gibt an, dass sich die Funktion auf eine Ressource auswirkt, indem sie eine Transaktion initiiert, einen Prozess in der realen Welt ändert, Berechtigungen gewährt oder verweigert oder eine andere Aktion ausführt, die eine explizite Bestätigung durch den Benutzer erfordern würde.	Eine Funktion, die ein Hotelzimmer bucht oder den Zustand eines Arbeitselements von in `activeresolved`ändert.

Hinweis

Plug-In-Manifeste, die den DataExport Wert verwenden, können bei der Überprüfung fehlschlagen, wenn sie versuchen, das Plug-In zu installieren. Dies ist vorübergehend und wird in Kürze behoben werden.

OpenAPI-Laufzeitobjekt

Beschreibt, wie das Plug-In OpenAPI-Funktionen aufruft.

Das OpenAPI-Laufzeitobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`type`	String	Erforderlich. Identifiziert diese Runtime als OpenAPI-Runtime. Muss auf `OpenApi` festgelegt werden.
`auth`	Laufzeitauthentifizierungsobjekt	Erforderlich. Authentifizierungsinformationen, die zum Aufrufen der Runtime erforderlich sind.
`run_for_functions`	Array aus Zeichenfolgen	Optional. Die Namen der Funktionen, die in dieser Laufzeit verfügbar sind. Wenn diese Eigenschaft nicht angegeben wird, sind alle von der Runtime beschriebenen Funktionen verfügbar. Bereitgestellte Zeichenfolgenwerte können Wildcards enthalten. Mehr als eine Laufzeit DARF DIE Unterstützung für dieselbe Funktion nicht implizit oder explizit deklarieren.
`spec`	OpenAPI-Spezifikationsobjekt	Erforderlich. Enthält die OpenAPI-Informationen, die zum Aufrufen der Runtime erforderlich sind.

OpenAPI-Spezifikationsobjekt

Enthält die OpenAPI-Informationen, die zum Aufrufen der Runtime erforderlich sind.

Das OpenAPI-Spezifikationsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`url`	Zeichenfolge	Optional. Die URL zum Abrufen der OpenAPI-Spezifikation, die mit einer GET-Anforderung aufgerufen wird. Dieser Member ist erforderlich, es sei denn `api_description` , es ist vorhanden.
`api_description`	Zeichenfolge	Optional. Eine Zeichenfolge, die eine OpenAPI-Beschreibung enthält. Wenn dieses Element vorhanden ist, `url` ist nicht erforderlich und wird ignoriert, falls vorhanden.
`progress_style`	Zeichenfolge	Optional. Der Statusstil, der verwendet wird, um den Fortschritt der Funktion anzuzeigen. Mögliche Werte: `None`, `ShowUsage`, `ShowUsageWithInput`, `ShowUsageWithInputAndOutput`

OpenAPI-Spezifikationsobjektbeispiel

{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}

Laufzeitauthentifizierungsobjekt

Enthält Informationen, die vom Plug-In zur Authentifizierung bei der Runtime verwendet werden.

Das Laufzeitauthentifizierungsobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`type`	Zeichenfolge	Optional. Gibt den Typ der Authentifizierung an, die zum Aufrufen einer Funktion erforderlich ist. Mögliche Werte sind: `None`, `OAuthPluginVault` und `ApiKeyPluginVault`.
`reference_id`	Zeichenfolge	Optional. Ein Wert, der verwendet wird, wenn `type` oder `ApiKeyPluginVault`ist`OAuthPluginVault`. Der `reference_id` Wert wird unabhängig voneinander abgerufen, wenn die erforderlichen Authentifizierungskonfigurationswerte bereitgestellt werden. Dieser Mechanismus ist vorhanden, um das Speichern von Geheimniswerten im Plug-In-Manifest zu verhindern.

Beispiel für ein Laufzeitauthentifizierungsobjekt

{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

Plug-In-Funktionen-Objekt

Beschreibt die Funktionen des Plug-Ins.

Das Plug-In-Capabilities-Objekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`conversation_starters`	Array des Conversation-Starterobjekts	Optional. Unterhaltungsstarter, die dem Benutzer angezeigt werden können, um Vorschläge zum Aufrufen des Plug-Ins zu erhalten.

Conversation Starter-Objekt

Ein Beispiel für eine Frage, die das Plug-In beantworten kann.

Das Unterhaltungsstartobjekt enthält die folgenden Eigenschaften.

Eigenschaft	Typ	Beschreibung
`text`	String	Erforderlich. Der Text des Unterhaltungsstarts. Diese Eigenschaft kann lokalisiert werden.
`title`	Zeichenfolge	Optional. Der Titel des Konversationsstarts. Diese Eigenschaft kann lokalisiert werden.

Conversation Starter-Objektbeispiel

{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

Manifestbeispiel

Hier sehen Sie ein Beispiel für eine Plug-In-Manifestdatei, die die meisten der im Artikel beschriebenen Manifesteigenschaften und Objekteigenschaften verwendet:

{
  "schema_version": "v2.2",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
  "capabilities": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "functions": [
    {
      "name": "getListings",
      "description": "Get a list of properties matching the specified criteria",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search properties in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms the property should have"
          },
          "bathrooms": {
            "type": "number",
            "description": "The number of bathrooms the property should have"
          },
          "amenities": {
            "type": "array",
            "description": "The list of amenities the property should have",
            "items": {
              "type": "string",
              "description": "One amenity the property should have",
              "enum": [
                "air conditioning",
                "balcony",
                "dishwasher",
                "elevator",
                "fireplace",
                "furniture",
                "garden",
                "gym",
                "heating",
                "jacuzzi",
                "laundry room",
                "microwave",
                "no furniture",
                "parking",
                "patio",
                "sauna",
                "swimming pool",
                "terrace",
                "wi-fi"
              ]
            }
          }
        }
      },
      "returns": {
        "type": "string",
        "description": "A list of properties"
      },
      "states": {
        "reasoning": {
          "description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
          "instructions": [
            "If the user mentions a city in their question, only search in that city by using the city parameter.",
            "If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
            "Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found.",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message from the JSON response to the user.",
            "If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "GetPublicData",
            "GetPrivateData"
          ]
        }
      }
    },
    {
      "name": "saveSearch",
      "description": "Save a search for properties for sale",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms"
          }
        },
        "required": [
          "city"
        ]
      },
      "returns": {
        "type": "string",
        "description": "The unique ID for the saved search"
      },
      "states": {
        "responding": {
          "description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
          "instructions": [
            "Examine the output of the `saveSearch` function.",
            "Extract the unique ID integer from the output and include it in your response to the user."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    },
    {
      "name": "deleteSavedSearch",
      "description": "Delete a previously saved search",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique ID of the saved search"
          }
        },
        "required": [
          "id"
        ]
      },
      "returns": {
        "type": "string",
        "description": "True if the saved search was deleted, false otherwise"
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "none"
      },
      "run_for_functions": [
        "getListings",
        "saveSearch",
        "deleteSavedSearch"
      ],
      "spec": {
        "url": "http://contoso.com/openapi.yaml"
      }
    }
  ],
  "logo_url": "http://contoso.com/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/"
}

Siehe auch

API-Plug-Ins für Microsoft 365 Copilot

Freigeben über

API-Plug-In-Manifestschema 2.2 für Microsoft 365 Copilot

Änderungen gegenüber der vorherigen Version

JSON-Schema

Konventionen

Relative Verweise in URLs

Zeichenfolgenlänge

Nicht erkannte Eigenschaften

Lokalisierung von Zeichenfolgen

Beispiel für lokalisierte Zeichenfolgen

Plug-In-Manifestobjekt

Funktionsobjekt

Funktionsobjektbeispiel

Funktionsparameterobjekt

Beispiel für Funktionsparameterobjekt

Eigenschaftenobjekt für Funktionsparameter

Funktionsparameterobjekt

Beispiel für Funktionsparameter

Rückgabeobjekt

Rich-Rückgabeobjekt

Funktionsstatusobjekt

State-Objekt

State-Objektbeispiel

Funktionsfunktionsobjekt

Confirmation-Objekt

Antwortsemantikobjekt

Beispiel für eine statische Vorlage

Beispiel für eine dynamische Vorlage

Eigenschaftenobjekt der Antwortsemantik

Sicherheitsinformationsobjekt

Datenverarbeitungswerte

OpenAPI-Laufzeitobjekt

OpenAPI-Spezifikationsobjekt

OpenAPI-Spezifikationsobjektbeispiel

Laufzeitauthentifizierungsobjekt

Beispiel für ein Laufzeitauthentifizierungsobjekt

Plug-In-Funktionen-Objekt

Conversation Starter-Objekt

Conversation Starter-Objektbeispiel

Manifestbeispiel

Siehe auch

Feedback

Zusätzliche Ressourcen