OpenAPI-Spezifikation für Ihre Integration ansehen

Vorschau – OpenAPI-Spezifikation

Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support. Weitere Informationen finden Sie unter den Beschreibungen der Startphase.

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:

• Ein umfassendes Verständnis der API-Endpunkte, Methoden und Datenstrukturen Ihrer Integration erhalten.
• Die Entwicklung und Fehlerbehebung effizienter gestalten, indem Sie eine detaillierte und zentralisierte Ansicht der API Ihrer Integration erhalten.
• Ihre Integrations-APIs verfügbar machen und nahtlos in Konversations-Agents einbinden. Weitere Informationen finden Sie unter Konversations-Agents mit Application Integration erstellen.

Was ist die OpenAPI-Spezifikation?

Die OpenAPI-Spezifikation (OAS) ist ein standardisiertes, 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 formelle Beschreibung der API-Elemente, z. B. der Basis-URL, Pfade und Verben, Header, Abfrageparameter, Inhaltstypen, Anfrage- und Antwortmodelle. Weitere Informationen zur OpenAPI-Spezifikation finden Sie unter OpenAPI-Spezifikation.

Hinweis:Application Integration unterstützt nur die Version 3.0.1 der 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 Ihre 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 anzusehen:

Console

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

1. Rufen Sie die Seite Application Integration auf.

   Zu Application Integration

2. Klicken Sie im Navigationsmenü auf Integrationen.

   Die Seite Integrationen wird angezeigt und enthält eine Liste aller Integrationen, die im Google Cloud project verfügbar sind.

3. Klicken Sie auf die Integration, für die Sie die OpenAPI-Spezifikation ansehen möchten. Dadurch wird die Integration im Integrationseditor geöffnet.
4. Klicken Sie in der Symbolleiste des Integrationseditors auf (Menü „Aktionen“) 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 ansehen möchten, wählen Sie den API-Trigger aus der Drop-down-Liste APIs aus.
   • Wenn Sie die OpenAPI-Spezifikation als YAML-Datei herunterladen möchten, klicken Sie auf download (Herunterladen).

Hinweis:Sie können die OpenAPI-Spezifikation nur für eine einzelne Integration gleichzeitig im YAML-Format im Integrationseditor ansehen und herunterladen. Wenn Sie die OpenAPI-Spezifikation im YAML- oder JSON-Format ansehen und herunterladen möchten, folgen Sie der Anleitung im Abschnitt API.

API

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

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

Tipp:curl ist in der Regel für Linux- und macOS-Betriebssysteme vorinstalliert. Wenn curl nicht installiert ist, können Sie es auf der Seite „curl Releases und Downloads“ herunterladen.

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 der API-Trigger in Ihrer Integration, für die Sie die OpenAPI-Spezifikation ansehen 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.
  Hinweis:Sie können die OpenAPI-Spezifikation nur für mehrere Integrationen in derselben Region ansehen.

OpenAPI-Spezifikation

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

Element	Beschreibung
openapi	Die verwendete Version der OpenAPI-Spezifikation.
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 in Kombination mit dem Pfad bildet den API-Endpunkt für API-Aufrufe. Die Felder Request und Response werden basierend auf den für den entsprechenden API-Trigger konfigurierten Eingabe- und Ausgabevariablen ausgefüllt. Hinweis:Application Integration unterstützt derzeit nur eine begrenzte Anzahl von JSON-Schema-Schlüsselwörtern. Informationen zu den unterstützten Schlüsselwörtern finden Sie unter Hinweise.
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

Die folgenden Hinweise gelten beim Ansehen der OpenAPI-Spezifikation für Ihre Integration:

• 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, legen Sie den Parameter fileFormat im API-Aufruf auf JSON fest.
• Application Integration unterstützt derzeit nur die folgende begrenzte Anzahl von JSON-Schema-Schlüsselwörtern:
  • 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, treten möglicherweise semantische Fehler im Zusammenhang mit den API-Pfaden auf, ähnlich wie in der folgenden Abbildung:

  

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

Nächste Schritte

• Konversations-Agents mit Application Integration erstellen.
• Erfahren Sie mehr über API-Trigger.
• Erfahren Sie mehr über Integrationen testen und veröffentlichen.