Integration der OpenAPI-Spezifikation - Amazon Quick
Was Sie tun könnenBevor Sie beginnenOpenAPI-Spezifikation und Authentifizierung vorbereitenOpenAPI-Spezifikationsintegration einrichtenAnforderungen an Format und MusterNicht unterstützte FunktionenBewährte Verfahren für SchemasUnterstützte ErweiterungenSchemavalidierung und FehlerbehandlungIntegration der OpenAPI-Spezifikation verwaltenFehlerbehebung bei der Integration der OpenAPI-Spezifikation

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Integration der OpenAPI-Spezifikation

Mit der OpenAPI-Spezifikationsintegration können Sie benutzerdefinierte Integrationen auf der Grundlage von OpenAPI-Schemas erstellen. Auf diese Weise können Sie eine Verbindung zu jeder API herstellen, die eine OpenAPI-Spezifikation bereitstellt. Diese Integration unterstützt nur die Ausführung von Aktionen und erfordert die Amazon Quick Pro-Stufe oder höher.

Was Sie tun können

Die OpenAPI-Spezifikationsintegration bietet schemabasierte Konnektivität, damit Sie mit benutzerdefinierten Lösungen arbeiten können. APIs

Action-Konnektor

Führen Sie Aktionen auf der Grundlage der OpenAPI-Spezifikationen durch. Führen Sie API-Aufrufe aus, verwalten Sie Ressourcen und interagieren Sie mit benutzerdefinierten Diensten über dynamisch generierte Aktionen, die auf dem bereitgestellten Schema basieren.

Schemabasierte Konfiguration

Importieren Sie OpenAPI-Spezifikationen, um automatisch verfügbare Aktionen und Aktionen zu generieren. Support für JSON-Schemavalidierung und Parameterzuordnung.

Bevor Sie beginnen

Bevor Sie die OpenAPI-Spezifikationsintegration einrichten, stellen Sie sicher, dass Sie über Folgendes verfügen:

  • OpenAPI-Spezifikation (Version 3.0.0 oder höher) für Ihre Ziel-API.

  • API-Authentifizierungsdaten (API-Schlüssel oder anderes). OAuth

  • Amazon Quick Author oder höher.

  • API-Dokumentation und Endpunktzugriff.

OpenAPI-Spezifikation und Authentifizierung vorbereiten

Bevor Sie die Integration in Amazon Quick einrichten, bereiten Sie Ihre OpenAPI-Spezifikation und Ihre Authentifizierungsdaten vor. Ihre OpenAPI-Spezifikation muss bestimmte Anforderungen für eine erfolgreiche Integration erfüllen.

Grundlegende Anforderungen

Ihre OpenAPI-Spezifikation muss diese grundlegenden Anforderungen erfüllen.

  • OpenAPI-Version — Version 3.0.0 oder höher ist erforderlich.

  • Dateiformat — nur JSON-Format (application/json).

  • Dateigrößenbeschränkung — Maximal 1 MB für die gesamte OpenAPI-Spezifikation.

  • Operationslimit — Mindestens 1 und maximal 100 API-Operationen pro Konnektor.

Erforderliche Schemafelder

Ihre OpenAPI-Spezifikation muss diese erforderlichen Abschnitte enthalten.

openapi

Die verwendete OpenAPI-Version (muss „3.0.0" oder höher sein).

info

Serviceinformationen, einschließlich Titel, Beschreibung und Version.

Server

Basis-URL und Serverinformationen für API-Konnektivität.

Pfade

API-Endpunktdefinitionen mit HTTP-Methoden und -Operationen.

Unterstützte Authentifizierungsschemata

Bereiten Sie Authentifizierungsdaten auf der Grundlage der unterstützten Authentifizierungsmethoden in den OpenAPI-Spezifikationen vor.

OAuth 2.0

Unterstützt sowohl die Gewährung von Autorisierungscode als auch die Gewährung von Kundenanmeldedaten. Erfordert AuthorizationUrl-, TokenUrl- und Bereichsdefinitionen im Sicherheitsschema.

API-Schlüssel

Die API-Schlüsselauthentifizierung wurde in Abfrageparametern oder Headern übergeben.

Keine Authentifizierung

Standardoption, wenn in der Spezifikation keine Sicherheitsschemata definiert sind.

Anmerkung

Nicht unterstützte Authentifizierungsschemata in der OpenAPI-Spezifikation werden ignoriert, und der Konnektor verwendet standardmäßig keine Authentifizierung.

OpenAPI-Spezifikationsintegration einrichten

Nachdem Sie Ihre OpenAPI-Spezifikation und Ihre Authentifizierungsdaten vorbereitet haben, folgen Sie diesen Schritten, um Ihre OpenAPI-Spezifikationsintegration zu erstellen.

  1. Wählen Sie in der Amazon Quick-Konsole Integrationen aus.

  2. Klicken Sie auf Hinzufügen (mit dem Pluszeichen „+“).

  3. Wählen Sie auf der Seite „Schema hinzufügen“ die Option „Schema importieren“ und wählen Sie ein zu importierendes Schema aus.

  4. Klicken Sie auf Weiter.

  5. Geben Sie die Integrationsdetails einschließlich Name und Beschreibung ein.

  6. Überprüfen Sie die verfügbaren Aktionen, die anhand Ihrer OpenAPI-Spezifikation generiert wurden.

  7. Wählen Sie Erstellen und fortfahren.

  8. Wählen Sie Benutzer aus, mit denen Sie die Integration teilen möchten.

  9. Klicken Sie auf Weiter.

Erwartete Ergebnisse

Nach erfolgreicher Einrichtung erscheint Ihre OpenAPI-Spezifikationsintegration in der Integrationsliste mit dynamisch generierten Aktionen, die auf Ihrem Schema basieren. Die Integration ist für Amazon Quick-Workflows, Automatisierungen und KI-Agenten verfügbar, wobei die Aufgaben den in Ihrer OpenAPI-Spezifikation definierten Endpunkten entsprechen.

Anforderungen an Format und Muster

Ihre OpenAPI-Spezifikation muss diesen Formatanforderungen entsprechen.

  • Pfadmuster — Sie müssen dem Muster: folgen ^/[^/]*(/[^/]*)*$ und mit einem Schrägstrich (/) beginnen.

  • Bedienung IDs — Muss dem Muster folgen:^[a-zA-Z0-9_ ]{1,256}$.

  • Beschreibungen — Erforderlich für alle Operationen und Parameter, maximal 5000 Zeichen.

  • Inhaltstyp — application/json Wird nur für Anfrage- und Antworttexte unterstützt.

Nicht unterstützte Funktionen

Die folgenden OpenAPI-Funktionen werden nicht unterstützt und führen zu Validierungsfehlern.

  • Array-Typen — Schemas mit Array-Typen (z. B.{"type": "array", "items": {"string"}}) werden nicht unterstützt.

  • Kompositionsschlüsselwörter — die Schlüsselwörter AllOf, OneOf, AnyOf und not werden nicht unterstützt.

  • Zirkelverweise — Zirkuläre oder zyklische Verweise ($ref innerhalb von $ref) werden nicht unterstützt.

  • Komplexe verschachtelte Strukturen — Vermeiden Sie nach Möglichkeit tief verschachtelte Objektstrukturen.

Bewährte Verfahren für Schemas

Folgen Sie diesen Best Practices, wenn Sie Ihre OpenAPI-Spezifikation erstellen.

Schreiben Sie aussagekräftige Beschreibungen

Verwenden Sie diese Richtlinien, um klare und hilfreiche Beschreibungen zu verfassen.

  • Funktionsbeschreibungen — Beschreiben Sie, was die Operation macht, wann sie verwendet wird und wie sie sich verhält.

  • Parameterbeschreibungen — Erläutern Sie kurz den Zweck des Parameters und seine Auswirkungen auf das Betriebsverhalten.

  • Eigenständiger Inhalt — Stellen Sie sicher, dass die Beschreibungen ohne externe Verweise eine ausreichende Orientierungshilfe bieten.

  • Klarheit der Abhängigkeiten — Machen Sie Abhängigkeiten zwischen Vorgängen in Beschreibungen explizit.

  • Operationsreferenzen — Verwenden Sie OperationID, wenn Sie auf andere Operationen verweisen, nicht auf API-Pfade.

Empfehlungen zur Parameterstruktur

Strukturieren Sie Ihre Parameter für eine optimale Benutzerfreundlichkeit.

  • Vereinfachen Sie komplexe Objekte — Verwenden Sie statt verschachtelter Objekte separate Parameter (z. B. start_date, start_time, end_date, end_time).

  • Standardformate verwenden — Verwenden Sie Standardformatwerte wie „Datum/Uhrzeit“ oder „Datum“ für ISO-8601-Datums- und Uhrzeitangaben.

  • Parameternamen löschen — Verwenden Sie aussagekräftige Parameternamen, die ihren Zweck klar angeben.

  • Erforderliche Feldmarkierung — Kennzeichnen Sie Parameter je nach API-Verhalten ordnungsgemäß als erforderlich oder optional.

Unterstützte Erweiterungen

Wir unterstützen benutzerdefinierte OpenAPI-Erweiterungen, um die Benutzererfahrung zu verbessern.

x-amzn-form-display-Name

Wird auf Parameterebene verwendet, um den Standardfeldnamen zu überschreiben, der in Bestätigungsformularen angezeigt wird. Wird derzeit nur für Anforderungstextparameter unterstützt.

"x-amzn-form-display-name": "User Name"
x-amzn-operation-type

Definiert, ob eine Operation als „Lesen“ oder „Schreiben“ behandelt werden soll. Standardmäßig sind GET-Methoden „Lese“ -Operationen und alle anderen HTTP-Methoden sind „Schreib“ -Operationen.

"x-amzn-operation-type": "read"

Schemavalidierung und Fehlerbehandlung

Wenn Sie eine OpenAPI-Spezifikation hochladen, führen wir eine umfassende Validierung durch.

  • Überprüfung der Dateigröße — Stellt sicher, dass die Spezifikation 1 MB nicht überschreitet.

  • Validierung der Anzahl von Vorgängen — Überprüft, ob zwischen 1 und 100 Operationen definiert sind.

  • Überprüfung der Schemastruktur — Prüft, ob Pflichtfelder vorhanden sind und ob die Formatierung korrekt ist.

  • Überprüfung des Sicherheitsschemas — Überprüft die unterstützten Authentifizierungsmethoden.

  • Überprüfung des Inhaltstyps — Stellt sicher, dass nur verwendet application/json wird.

Validierungsfehler werden unter dem Schema-Editor angezeigt und müssen behoben werden, bevor die Integration erstellt werden kann. Zu den häufigsten Problemen bei der Validierung gehören:

  • Fehlende Pflichtfelder (Openapi, Info, Server, Pfade).

  • Ungültige Pfadmuster oder ungültiger Vorgang IDs.

  • Nicht unterstützte Schemafunktionen (Arrays, Kompositionsschlüsselwörter).

  • Fehlende oder zu lange Beschreibungen.

  • Zirkelverweise in Schemadefinitionen.

Integration der OpenAPI-Spezifikation verwalten

Nachdem Sie Ihre OpenAPI-Spezifikationsintegration erstellt haben, können Sie sie über verschiedene Optionen verwalten.

Integration teilen

Sie können OpenAPI-Spezifikations-Action-Konnektoren mit anderen Benutzern in Ihrer Organisation teilen.

  1. Wählen Sie auf der Detailseite der OpenAPI-Integration die Option Teilen aus.

  2. Konfigurieren Sie die Optionen zum Teilen:

    • Mit bestimmten Benutzern teilen — Geben Sie Benutzernamen oder E-Mail-Adressen ein.

    • Mit der Organisation teilen — Für alle Benutzer in Ihrer Organisation verfügbar machen.

  3. Legen Sie Berechtigungsstufen für den gemeinsamen Zugriff fest.

  4. Wählen Sie Share-Integration aus, um die Freigabeeinstellungen zu übernehmen.

Integration löschen

Gehen Sie wie folgt vor, um Ihre OpenAPI-Integration dauerhaft zu entfernen.

  1. Wählen Sie auf der Detailseite der OpenAPI-Integration die Option Löschen aus.

  2. Prüfen Sie die Auswirkungen des Löschvorgangs, einschließlich aller Workflows oder Automatisierungen, die diese Integration verwenden.

  3. Geben Sie den Namen der Integration ein, um das Löschen zu bestätigen.

  4. Wählen Sie Integration löschen, um sie dauerhaft zu entfernen.

Fehlerbehebung bei der Integration der OpenAPI-Spezifikation

Verwenden Sie diese Tipps zur Fehlerbehebung, um häufig auftretende Probleme bei der Integration der OpenAPI-Spezifikation zu lösen.

Schemavalidierungsfehler

Stellen Sie sicher, dass Ihre OpenAPI-Spezifikation dem richtigen Format folgt und alle erforderlichen Felder enthält. Verwenden Sie einen OpenAPI-Validator, um Ihr Schema vor dem Import zu überprüfen.

Es wurden keine Aufgaben generiert

Stellen Sie sicher, dass Ihre OpenAPI-Spezifikation Pfaddefinitionen mit HTTP-Methoden und -Operationen IDs enthält. Aktionen werden auf der Grundlage der in Ihrem Schema definierten Operationen generiert.

Authentication failures (Authentifizierungsfehler)

Überprüfen Sie, ob das in Ihrer OpenAPI-Spezifikation definierte Authentifizierungsschema den tatsächlichen API-Anforderungen entspricht und ob die Anmeldeinformationen ordnungsgemäß konfiguriert sind.

Fehler bei der Ausführung der Aktion

Überprüfen Sie die Aktionsparameter und stellen Sie sicher, dass sie mit den Parameterdefinitionen in Ihrer OpenAPI-Spezifikation übereinstimmen, einschließlich der erforderlichen Felder und Datentypen.