OpenAPI-Spezifikation für Ihre Integration ansehen

Mit Application Integration können Sie die OpenAPI-Spezifikationen Ihrer veröffentlichten Integrationen, die mit einem oder mehreren API-Triggern konfiguriert sind, dynamisch generieren und ansehen. Wenn Sie auf die OpenAPI-Spezifikation Ihrer Integration zugreifen, können Sie Folgendes tun:

  • Verschaffen Sie sich einen umfassenden Überblick über die API-Endpunkte, Methoden und Datenstrukturen Ihrer Integration.
  • Ermöglicht eine effizientere Entwicklung und Fehlerbehebung durch eine detaillierte und zentrale Ansicht der API Ihrer Integration.
  • Informationen zum Bereitstellen Ihrer Integrations-APIs und zur nahtlosen Einbindung in Konversations-Agenten finden Sie unter Konversations-Agenten mit Application Integration erstellen.

Was ist die OpenAPI-Spezifikation?

Logo: OpenAPI-Spezifikation

Die OpenAPI-Spezifikation (OAS) ist ein standardmäßiges, sprachunabhängiges Format zur Beschreibung von RESTful APIs. Die OpenAPI-Spezifikation wird in der Regel im YAML- oder JSON-Format geschrieben und enthält eine formale Beschreibung der API-Elemente, z. B. Basis-URL, Pfade und Verben, Header, Suchparameter, Inhaltstypen, Anfrage- und Antwortmodelle. Weitere Informationen zur OpenAPI-Spezifikation finden Sie unter OpenAPI-Spezifikation.

OpenAPI-Spezifikation generieren und ansehen

Sie können die OpenAPI-Spezifikation für Ihre Integrationen dynamisch im Integrationseditor in der Google Cloud Console oder über einen API-Aufruf generieren und ansehen.

Hinweis

  • Prüfen Sie, ob Ihre Integration mit einem oder mehreren API-Triggern konfiguriert ist. Informationen zum Konfigurieren von API-Triggern finden Sie unter API-Trigger.
  • Veröffentlichen Sie die Integration. Informationen zum Veröffentlichen einer Integration finden Sie unter Integrationen testen und veröffentlichen.

OpenAPI-Spezifikation ansehen

Wählen Sie eine der folgenden Optionen aus, um die OpenAPI-Spezifikation für Ihre Integration aufzurufen:

Console

So rufen Sie die OpenAPI-Spezifikation für eine bestimmte Integration auf:

  1. Rufen Sie die Seite Application Integration auf.

    Zu Application Integration

  2. Klicken Sie im Navigationsmenü auf Integrationen.

    Die Seite Integrationen wird angezeigt. Dort sind alle im Projekt Google Cloud verfügbaren Integrationen aufgeführt.

  3. Klicken Sie auf die Integration, für die Sie die OpenAPI-Spezifikation aufrufen möchten. Dadurch wird die Integration im Integrationseditor geöffnet.
  4. Klicken Sie in der Symbolleiste des Integrationseditors auf (Aktionsmenü) und wählen Sie OpenAPI-Spezifikation ansehen aus.

    Der Bereich OpenAPI-Spezifikation ansehen wird angezeigt und enthält die OpenAPI-Spezifikation der Integration. Die generierte OpenAPI-Spezifikation enthält standardmäßig alle in der Integration konfigurierten API-Trigger.

    • Wenn Sie die OpenAPI-Spezifikation für einen bestimmten API-Trigger aufrufen möchten, wählen Sie den API-Trigger aus der Drop-down-Liste APIs aus.
    • Klicken Sie auf download (Herunterladen), um die OpenAPI-Spezifikation als YAML-Datei herunterzuladen.

API

Mit der Methode generateOpenApiSpec der Application Integration API können Sie die OpenAPI-Spezifikation für Ihre Integration über einen API-Aufruf aufrufen.

Verwenden Sie den folgenden curl-Befehl, um die OpenAPI-Spezifikation für eine oder mehrere Integrationen in derselben Region aufzurufen:

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"

Ersetzen Sie Folgendes:

  • TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: Die Namen des API-Triggers in Ihrer Integration, für die Sie die OpenAPI-Spezifikation aufrufen möchten.
  • INTEGRATION_NAME: Der Name Ihrer Integration.
  • DOC_TYPE: Der Typ des zu generierenden Dokuments. Die folgenden Werte werden unterstützt: YAML oder JSON.
  • PROJECT_ID: Die ID Ihres Google Cloud -Projekts.
  • LOCATION: Der Standort Ihres Google Cloud -Projekts.

OpenAPI-Spezifikation verstehen

Application Integration generiert die OpenAPI-Spezifikation für Ihre veröffentlichten Integrationen gemäß dem Standard OpenAPI-Spezifikation 3.0. In der folgenden Tabelle werden die Elemente der OpenAPI-Spezifikation beschrieben, die in Application Integration generiert wird:

Element Beschreibung
openapi Die verwendete OpenAPI-Spezifikationsversion.
info Informationen zur Integration, z. B. Name (Titel), Beschreibung und veröffentlichte Version.
servers Die Server-URLs, auf denen die Integration gehostet wird.
paths Für jeden ausgewählten API-Trigger in der Integration werden Pfade erstellt. Die Server-URL bildet zusammen mit dem Pfad den API-Endpunkt für API-Aufrufe.

Die Felder Request und Response werden basierend auf den Eingabe- und Ausgabevariablen ausgefüllt, die für den entsprechenden API-Trigger konfiguriert sind.

components Das Feld schemas enthält das JSON-Schema für die Eingabe- und Ausgabevariablen des API-Triggers.

Das Feld securitySchemes enthält die Authentifizierungsinformationen für die API-Trigger.

Hinweise

Beachten Sie beim Aufrufen der OpenAPI-Spezifikation für Ihre Integration Folgendes:

  • Die OpenAPI-Spezifikation wird nur für veröffentlichte Integrationen generiert.
  • Die OpenAPI-Spezifikation wird nur für Integrationen generiert, die mit einem oder mehreren API-Triggern konfiguriert sind.
  • Die OpenAPI-Spezifikation wird nur für Integrationen in derselben Region generiert.
  • Die OpenAPI-Spezifikation wird standardmäßig im YAML-Format generiert. Wenn Sie die OpenAPI-Spezifikation im JSON-Format generieren und ansehen möchten, setzen Sie im API-Aufruf den Parameter fileFormat auf JSON.
  • Application Integration unterstützt derzeit nur die folgenden JSON-Schema-Schlüsselwörter:
    • type
    • items
    • properties
    • description
    • required
    • array
    • object
    • oneOf
    • allOf
    • anyOf
    • not
    • null
    • enum
    • additionalProperties
    • default
  • Wenn Sie die OpenAPI-Spezifikation mit dem Swagger Editor validieren, können semantische Fehler im Zusammenhang mit den API-Pfaden auftreten, ähnlich wie in der folgenden Abbildung:

    Swagger Editor Swagger Editor

    Diese Fehler können ignoriert werden. Die OpenAPI-Spezifikation ist weiterhin gültig.

Nächste Schritte