Verwenden der Azure CLI zum Verwalten Ihres API-Inventars

  • Artikel

In diesem Artikel erfahren Sie, wie Sie az apic api-Befehle in der Azure CLI verwenden, um APIs Ihrem API Center-Inventar hinzuzufügen und zu konfigurieren. Verwenden Sie Befehle in der Azure CLI zum Skripten von Vorgängen zum Verwalten Ihres API-Inventars und anderer Aspekte Ihrer API Center-Instanz.

Voraussetzungen

  • Ein API-Center in Ihrem Azure-Abonnement. Wenn Sie noch keins erstellt haben, lesen Sie die Schnellstartanleitung: Erstellen Ihres API-Centers.

  • Für die Azure CLI:

    • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

    • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

      • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

      • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

      • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

    Hinweis

    Für az apic-Befehle wird die Azure CLI-Erweiterung apic-extension benötigt. Wenn Sie keine az apic-Befehle verwendet haben, kann die Erweiterung dynamisch installiert werden, wenn Sie den ersten az apic-Befehl ausführen. Sie können die Erweiterung auch manuell installieren. Hier finden Si weitere Informationen zu Azure CLI-Erweiterungen.

    In den Versionshinweisen finden Sie die neuesten Änderungen und Updates in der apic-extension.

Registrieren von API, API-Version und -Definition

In den folgenden Schritten wird gezeigt, wie Sie eine API erstellen und eine einzelne API-Version und API-Definition zuordnen. Hintergrundinformationen zum Datenmodell in Azure API Center finden Sie unter Wichtige Konzepte.

Erstellen einer API

Verwenden Sie den Befehl az apic api create zum Erstellen einer API in Ihrer API Center-Instanz.

Im folgenden Beispiel wird eine API namens Petstore API in der Ressourcengruppe myResourceGroup und der API Center-Instanz myAPICenter erstellt. Bei der API handelt es sich um die REST-API.

az apic api create  --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --title "Petstore API" --type "rest"

Hinweis

Nach dem Erstellen einer API können Sie die deren Eigenschaften mithilfe des Befehls az apic api update aktualisieren.

Erstellen einer API-Version

Verwenden Sie den Befehl az apic api version create zum Erstellen einer Version für Ihre API.

Im folgenden Beispiel wird eine API-Version namens v1-0-0 für die API petstore-api erstellt, die Sie im vorherigen Abschnitt erstellt haben. Die Version ist auf die Lebenszyklusphase Test festgelegt.

az apic api version create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --title "v1-0-0" --lifecycle-stage "testing"

Erstellen einer API-Definition und Hinzufügen einer Spezifikationsdatei

Verwenden Sie den Befehl az apic api definition, um eine Definition und eine dazugehörige Spezifikationsdatei für eine API-Version hinzuzufügen.

Erstellen einer Definition

Im folgenden Beispiel wird der Befehl az apic api definition create verwendet, um eine Definition namens openapi für die API-Version petstore-api aus dem vorherigen Abschnitt zu erstellen.

az apic api definition create --resource-group myResourceGroup \
    --service-name myAPICenter --api-id petstore-api \
    --version-id v1-0-0 --definition-id openapi --title "OpenAPI"

Importieren einer Spezifikationsdatei

Importieren Sie mit dem Befehl az apic api definition import-specification eine Spezifikationsdatei zur Definition.

Im folgenden Beispiel wird eine OpenAPI-Spezifikationsdatei von einer öffentlich zugänglichen URL zur Definition openapi importiert, die Sie im vorherigen Schritt erstellt haben. Die Eigenschaften name und version der Spezifikationsressource werden als JSON übergeben.

az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --format "link" \
    --value 'https://petstore3.swagger.io/api/v3/openapi.json' \
    --specification '{"name":"openapi","version":"3.0.2"}'

Tipp

Sie können die Spezifikationsdatei inline importieren, indem Sie den Parameter --format auf inline festlegen und den Dateiinhalt mithilfe des Parameters --value übergeben.

Exportieren einer Spezifikationsdatei

Um eine API-Spezifikation aus API Center in eine lokale Datei zu exportieren, verwenden Sie den Befehl az apic api definition export-specification.

Im folgenden Beispiel wird die Spezifikationsdatei aus der Definition openapi exportiert, die Sie im vorherigen Abschnitt als lokale Datei specificationFile.json erstellt haben.

az apic api definition export-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id petstore-api --version-id v1-0-0 \
    --definition-id openapi --file-name "/Path/to/specificationFile.json"

Registrieren einer API aus einer Spezifikationsdatei in einem Schritt

Sie können eine API aus einer lokalen Spezifikationsdatei in einem einzigen Schritt registrieren, indem Sie den Befehl az apic api register verwenden. Bei dieser Option werden automatisch eine Standardversion und eine Definition für die API erstellt.

Im folgenden Beispiel wird eine API in der API Center-Instanz myAPICenter aus einer lokalen OpenAPI-Definitionsdatei namens specificationFile.jsonregistriert.

az apic api register --resource-group myResourceGroup \
    --service-name myAPICenter --api-location "/Path/to/specificationFile.json"
  • Mit dem Befehl werden die API-Eigenschaften wie Name und Typ aus Werten in der Definitionsdatei festgelegt.
  • Standardmäßig legt der Befehl die Lebenszyklusphase der API auf Design fest.
  • Es erstellt eine API-Version, die gemäß der version-Eigenschaft in der API-Definition benannt ist (oder standardmäßig 1-0-0), und eine API-Definition, die gemäß dem Spezifikationsformat benannt ist (z. B. openapi).

Nach der Registrierung einer API können Sie die Eigenschaften der API mithilfe der Befehle az apic api update, az apic api version update und az apic api definition update aktualisieren.

Löschen von API-Ressourcen

Verwenden Sie den Befehl az apic api delete Befehl, um eine API und alle zugehörigen Versions- und Definitionsressourcen zu löschen. Beispiel:

az apic api delete \
    --resource-group myResoureGroup --service-name myAPICenter \
    --api-id petstore-api

Um einzelne API-Versionen und -Definitionen zu löschen, verwenden Sie jeweils az apic api version delete und az apic api definition delete.

Zugehöriger Inhalt