Oracle Cloud Infrastructure - Dokumentation

API-Ressource mit einer API-Beschreibung erstellen

Erfahren Sie, wie Sie eine API-Ressource mit dem API-Gateway-Service erstellen, mit dem Sie eine API in einem API-Gateway bereitstellen können.

Wenn Sie den API Gateway-Service verwenden, können Sie optional eine API-Ressource erstellen. Mit der API-Ressource können Sie eine API in einem API-Gateway bereitstellen. Die API-Ressource enthält eine API-Beschreibung, die die API beschreibt.

Wenn Sie eine API-Ressource verwenden, um eine API in einem API-Gateway bereitzustellen, füllt die API-Beschreibung einige Eigenschaften der API-Deployment-Spezifikation vorab auf.

Sie können die API-Beschreibung optional aus einer Datei (manchmal auch als "API-Spezifikation" bezeichnet) importieren, die in einer unterstützten Sprache geschrieben ist. Derzeit werden OpenAPI-Spezifikation Version 2.0 (ehemals Swagger-Spezifikation 2.0) und Version 3.0 unterstützt.

Beachten Sie, dass die Erstellung einer API-Ressource im API Gateway-Service optional ist. Sie können eine API in einem API-Gateway bereitstellen, ohne eine API-Ressource im API Gateway-Service zu erstellen. Beachten Sie auch, dass Sie zunächst eine API-Ressource ohne API-Beschreibung erstellen und später eine API-Beschreibung hinzufügen können.

    1. Wählen Sie auf der Listenseite APIs die Option API erstellen aus. Wenn Sie Hilfe beim Suchen der Listenseite benötigen, finden Sie weitere Informationen unter API-Ressourcen auflisten.

    2. Geben Sie die folgenden Werte für die API-Ressource an:

      • Name: Der Name der API-Ressource. Vermeiden Sie die Eingabe von vertraulichen Informationen.
      • Compartment: Das Compartment, in dem die API-Ressource erstellt werden soll.
      • API-Beschreibungsdatei hochladen: (Optional) Eine Datei mit der API-Beschreibung (in einer unterstützten Sprache), die hochgeladen wird und aus der die API-Beschreibung erstellt werden soll. Die Datei kann bis zu 1 MB groß sein. Die Datei wird analysiert, um zu bestätigen, dass sie in einer unterstützten Sprache geschrieben und korrekt formatiert ist. Derzeit werden OpenAPI-Spezifikationsdateien von Version 2.0 (ehemals Swagger-Spezifikation 2.0) und Version 3.0 unterstützt.
      • Erweiterte Optionen anzeigen: Wählen Sie diese Option aus, um Tags auf die Ressource anzuwenden. Wenn Sie über Berechtigungen zum Erstellen von Ressourcen verfügt, sind Sie auch berechtigt: Freiformtags auf diese Ressource anwenden. Um ein definiertes Tag anzuwenden, benötigen Sie Die Berechtigungen zum Verwenden des Tag-Namespace. Weitere Informationen zu Tagging finden Sie unter Ressourcentags. Wenn Sie nicht sicher sind, ob Tags angewendet werden sollen, überspringen Sie diese Option, oder fragen Sie einen Administrator. Sie können Tags später anwenden.

    3. Wählen Sie API erstellen aus, um die API-Ressource zu erstellen.

      Wenn Sie eine API-Beschreibungsdatei hochgeladen haben, wird die API-Beschreibung erstellt und validiert. Es kann einige Minuten dauern, die API-Beschreibung zu validieren. Während der Validierung wird die API-Beschreibung auf der Seite Validierungen mit dem Status "Wird validiert" angezeigt. Wenn die API-Beschreibung erfolgreich validiert wurde, werden die folgenden Aktionen ausgeführt:

      • Auf der Seite Validierungen wird eine erfolgreiche Validierung angezeigt.
      • Auf der Seite API-Beschreibung wird die API-Beschreibung angezeigt, die aus der API-Beschreibungsdatei erstellt wurde.
      • Auf der Seite API-Deployment-Spezifikation werden zusätzliche Informationen zur API-Deployment-Standardspezifikation angezeigt, die aus der API-Beschreibung erstellt wurde.

      Anstatt die API-Ressource sofort zu erstellen, können Sie sie später mit Resource Manager und Terraform erstellen. Wählen Sie Als Stack speichern aus, um die Ressourcendefinition als Terraform-Konfiguration zu speichern. Weitere Informationen zum Speichern von Stacks aus Ressourcendefinitionen finden Sie unter Stacks auf der Seite "Ressourcen erstellen" erstellen.

    4. Wenn Sie mehr als ein paar Minuten darauf gewartet haben, dass die API-Beschreibung als "Gültig" angezeigt wird (oder wenn der Vorgang zum Validieren der API-Beschreibung fehlgeschlagen ist), gehen Sie wie folgt vor:

      1. Wählen Sie Arbeitsanforderungen aus, um einen Überblick über den Vorgang zum Validieren der API-Beschreibung anzuzeigen.
      2. Wählen Sie den Vorgang API validieren aus, um weitere Informationen zum Vorgang anzuzeigen (einschließlich Fehlermeldungen, Logmeldungen und Status der zugehörigen Ressourcen).
      3. Wenn der Vorgang zur Validierung der API-Beschreibung nicht erfolgreich war und Sie die Ursache des Problems nicht aus den Arbeitsanforderungsinformationen diagnostizieren können, gehen Sie zu API-Gateway-Fehler beheben.

    5. Wenn Sie bei der ersten Erstellung der API-Ressource keine API-Beschreibung hochgeladen haben oder später eine andere API-Beschreibungsdatei hochladen möchten, befolgen Sie diese Schritte:

      1. On the APIs page, select Edit from the Actions menu Menü "Aktionen" for the API resource.
      2. Geben Sie die Details zur API-Beschreibungsdatei an, aus der Sie die API-Beschreibung erstellen möchten.

    Nachdem Sie eine API-Ressource mit einer API-Beschreibung erfolgreich erstellt haben, können Sie sie in einem API-Gateway bereitstellen. Siehe Mit der Konsole ein API-Deployment aus einer API-Ressource erstellen.

  • So erstellen Sie eine API-Ressource mit der CLI:

    1. Konfigurieren Sie die Clientumgebung zur Verwendung der CLI (Clientumgebung zur Verwendung der CLI für API-Gateway-Entwicklung konfigurieren).
    2. Öffnen Sie eine Eingabeaufforderung, und führen Sie oci api-gateway api create aus, um die API-Ressource zu erstellen:
      oci api-gateway api create --display-name "<api-name>" --compartment-id <compartment-ocid> --content "<api-description>"

      Dabei gilt:

      • <api-name> ist der Name der neuen API-Ressource. Vermeiden Sie die Eingabe von vertraulichen Informationen.
      • <compartment-ocid> ist die OCID des Compartments, zu dem die neue API-Ressource gehört.
      • <api-description> ist eine optionale API-Beschreibung (in einer unterstützten Sprache). Für <api-description> können Sie folgende Werte angeben:
        • Die gesamte API-Beschreibung, in doppelte Anführungszeichen gesetzt. Innerhalb der Beschreibung muss jedes doppelte Anführungszeichen mit einem umgekehrten Schrägstrich (\) maskiert werden. Beispiel (zur besseren Lesbarkeit abgekürzt): --content "swagger:\"2.0\",title:\"Sample API\",..."
        • Name und Speicherort einer API-Beschreibungsdatei, in doppelte Anführungszeichen gesetzt und im Format "$(< <path>/<filename>.yaml)". Beispiel: --content "$(< /users/jdoe/api.yaml)"
        Die Beschreibung wird geparst, um zu bestätigen, dass sie in einer unterstützten Sprache geschrieben und korrekt formatiert ist. Derzeit werden OpenAPI-Spezifikationsdateien von Version 2.0 (ehemals Swagger-Spezifikation 2.0) und Version 3.0 unterstützt.

      Beispiel:

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..."

      Die Antwort auf den Befehl umfasst Folgendes:

      • Die OCID der API-Ressource.
      • Den Lebenszyklusstatus (Beispiel: SUCCEEDED, FAILED).
      • Die ID der Arbeitsanforderung zum Erstellen der API-Ressource (Details der Arbeitsanforderungen sind für sieben Tage nach Abschluss, Abbruch oder Fehler verfügbar).

      Wenn der Befehl die Steuerung erst dann zurückgeben soll, wenn die API-Ressource erstellt wurde (oder die Anforderung nicht erfolgreich war), nehmen Sie einen oder beide der folgenden Parameter auf:

      • --wait-for-state SUCCEEDED
      • --wait-for-state FAILED

      Beispiel:

      oci api-gateway api create --display-name "Hello World API Resource" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --content "swagger:\"2.0\",title:\"Sample API\",..." --wait-for-state SUCCEEDED

      Beachten Sie, dass Sie die API-Ressource erst verwenden können, wenn sie durch die Arbeitsanforderung erfolgreich erstellt wurde.

    3. (Optional) Geben Sie Folgendes ein, um den Status der Arbeitsanforderung anzuzeigen, die die API-Ressource erstellt:

      oci api-gateway work-request get --work-request-id <work-request-ocid>

    4. (Optional) Geben Sie Folgendes ein, um die Logs der Arbeitsanforderung anzuzeigen, die die API-Ressource erstellt:

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>

    5. (Optional) Wenn die Arbeitsanforderung, die die API-Ressource erstellt, nicht erfolgreich ist und Sie die Fehlerlogs prüfen möchten, geben Sie Folgendes ein:

      oci api-gateway work-request-error --work-request-id <work-request-ocid>

    Weitere Informationen zur Verwendung der CLI finden Sie unter Befehlszeilenschnittstelle (CLI). Eine vollständige Liste der Flags und Optionen, die für CLI-Befehle verfügbar sind, finden Sie in der CLI-Hilfe.

  • Führen Sie den Vorgang CreateAPI aus, um eine API-Ressource zu erstellen.