Share via

Importieren von APIs aus Azure API Management in Ihr API-Center

  • Artikel

In diesem Artikel wird gezeigt, wie Sie APIs aus einer Azure API Management-Instanz mithilfe der Azure CLI in Ihr API-Center importieren (hinzufügen). Durch das Hinzufügen von APIs aus API Management zu Ihrem API-Bestand können Entwickler, API-Programmmanager und andere Projektbeteiligte in Ihrer Organisation sie finden und darauf zugreifen.

In diesem Artikel werden zwei Optionen für die Verwendung der Azure CLI zum Hinzufügen von APIs zum API-Center aus API Management gezeigt:

  • Option 1 – Exportieren einer API-Definition aus einer API Management-Instanz mithilfe des Befehls az apim api export. Importieren Sie dann die Definition in Ihr API-Center.

    Mögliche Verfahren zum Importieren einer API-Definition, die aus API Management exportiert wurde:

  • Option 2 – Importieren von APIs direkt aus API Management in Ihr API-Center mithilfe des Befehls az apic service import-from-apim.

Nachdem Sie API-Definitionen oder APIs aus API Management importiert haben, können Sie Metadaten und Dokumentationen in Ihrem API-Center hinzufügen, um Projektbeteiligten dabei zu helfen, die API zu finden, zu verstehen und zu nutzen.

Voraussetzungen

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

  • Eine oder mehrere Instanzen von Azure API Management im selben oder unterschiedlichen Abonnements. Wenn Sie APIs direkt aus API Management importieren, müssen sich die API Management-Instanz und das API-Center im selben Verzeichnis befinden. Fall Sie noch keine erstellt haben, finden Sie weitere Informationen unter Erstellen einer neuen Azure API Management-Instanz mithilfe des Azure-Portals.

  • Mindestens eine in Ihrer API Management-Instanz verwaltete API, die Sie Ihrem API-Center hinzufügen möchten.

  • 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, wird die Erweiterung dynamisch installiert, sobald Sie den ersten az apic-Befehl ausführen. Hier finden Si weitere Informationen zu Azure CLI-Erweiterungen.

    Hinweis

    Azure CLI-Befehlsbeispiele in diesem Artikel können in PowerShell oder einer Bash-Shell ausgeführt werden. Bei Bedarf aufgrund unterschiedlicher Variablensyntax werden separate Befehlsbeispiele für die beiden Shells bereitgestellt.

Option 1: Exportieren einer API-Definition aus API Management und Importieren in Ihr API-Center

Exportieren Sie zuerst mithilfe des Befehls az apim api export eine API aus Ihrer API Management-Instanz in eine API-Definition. Je nach Szenario können Sie die API-Definition in eine lokale Datei oder eine URL exportieren.

Exportieren einer API in eine lokale API-Definitionsdatei

Der folgende Beispielbefehl exportiert die API mit dem Bezeichner my-api in der myAPIManagement-API-Instanz. Die API wird im OpenApiJson-Format in eine lokale OpenAPI-Definitionsdatei namens specificationFile.json exportiert.

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

#! PowerShell syntax
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

Exportieren der API in eine URL

Im folgenden Beispiel exportiert az apim api export die API mit dem Bezeichner my-api im OpenApiJson-Format in eine URL im Azure-Speicher. Die URL ist ungefähr 5 Minuten lang verfügbar. Hier wird der Wert der URL in der variablen $link gespeichert.

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# PowerShell syntax
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

Registrieren der API im API-Center aus einer exportierten API-Definition

Sie können eine neue API im API-Center aus der exportierten Definition registrieren, indem Sie den Befehl az apic api register verwenden.

Im folgenden Beispiel wird eine API im API-Center myAPICenter aus einer lokalen OpenAPI-Definitionsdatei namens definitionFile.json registriert.

az apic api register --resource-group myResourceGroup --service myAPICenter --api-location "/path/to/definitionFile.json"

Importieren der API-Definition in eine vorhandene API im API-Center

Im folgenden Beispiel wird der Befehl az apic api definition import-specification verwendet, um eine API-Definition in eine vorhandene API im API-Center myAPICenter zu importieren. Hier wird die API-Definition aus einer URL importiert, die in der variablen $link gespeichert ist.

In diesem Beispiel wird davon ausgegangen, dass Sie über eine API mit dem Namen my-api, eine zugeordnete API-Version v1-0-0 und die Definitionsentität openapi im API-Center verfügen. Falls nicht, lesen Sie den Artikel zum Hinzufügen von APIs zum API-Center.

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# PowerShell syntax
az apic api definition import-specification `
    --resource-group myResourceGroup --service myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

Option 2: Importieren von APIs direkt aus Ihrer API Management-Instanz

Mit den folgenden Schritten werden APIs mithilfe des Befehls az apic service import-from-apim direkt aus Ihrer API Management-Instanz in Ihr API-Center importiert. Dieser Befehl ist nützlich, wenn Sie mehrere APIs aus API Management in Ihr API-Center importieren möchten, Sie können damit aber auch eine einzelne API importieren.

Wenn Sie APIs aus einer API Management-Instanz mithilfe von az apic service import-from-apim zu Ihrem API-Center hinzufügen, geschieht Folgendes automatisch:

  • Die Versionen, Definitionen und Bereitstellungsinformationen für die APIs werden in Ihr API-Center kopiert.
  • Die API erhält einen vom System generierten API-Namen im API-Center. Sie behält den Anzeigenamen (Titel) aus API Management bei.
  • Die Lebenszyklusphase der API ist auf Design festgelegt.
  • Azure API Management wird als Umgebung hinzugefügt.

Hinzufügen einer verwalteten Identität in Ihrem API-Center

In diesem Szenario verwendet Ihr API-Center eine verwaltete Identität für den Zugriff auf APIs in Ihrer API Management-Instanz. Konfigurieren Sie je nach Ihren Anforderungen entweder eine systemseitig oder ein oder mehrere benutzerseitig zugewiesene verwaltete Identitäten.

Die folgenden Beispiele zeigen, wie Sie eine systemseitig zugewiesene verwaltete Identität mithilfe des Azure-Portals oder der Azure CLI konfigurieren. Im Großen und Ganzen sind die Konfigurationsschritte für eine benutzerseitig zugewiesene verwaltete Identität ähnlich.

  1. Navigieren Sie im Portal zu Ihrem API-Center.
  2. Wählen Sie im linken Menü unter Sicherheit die Option Verwaltete Identitäten aus.
  3. Wählen Sie Systemseitig zugewiesen aus, und legen Sie den Status auf Ein fest.
  4. Wählen Sie Speichern.

Zuweisen der Rolle „Leser des API Management-Diensts“ zur verwalteten Identität

Um den Import von APIs zuzulassen, weisen Sie der verwalteten Identität Ihres API-Centers die Rolle Leser des API Management-Diensts in Ihrer API Management-Instanz zu. Sie können das Portal oder die Azure CLI verwenden.

  1. Navigieren Sie im Portal zu Ihrer API Management-Instanz.
  2. Wählen Sie im linken Menü Zugriffssteuerung (IAM) aus.
  3. Wählen Sie + Rollenzuweisung hinzufügen aus.
  4. Legen Sie auf der Seite Rollenzuweisung hinzufügen die Werte wie folgt fest:
    1. Auf der Registerkarte Rolle: Wählen Sie Leser des API Management-Diensts aus.
    2. Auf der Seite Mitglieder unter Zugriff zuweisen: Wählen Sie Verwaltete Identität>+ Mitglieder auswählen aus.
    3. Auf der Seite Verwaltete Identitäten auswählen: Wählen Sie die systemseitig zugewiesene verwaltete Identität Ihres API-Centers aus, die Sie im vorherigen Abschnitt hinzugefügt haben. Klicken Sie auf Auswählen.
    4. Wählen Sie Überprüfen und zuweisen aus.

Importieren von APIs aus der API-Verwaltung

Verwenden Sie den Befehl az apic service import-from-apim, um eine oder mehrere APIs aus Ihrer API Management-Instanz in Ihr API-Center zu importieren.

Hinweis

  • Dieser Befehl hängt von einer verwalteten Identität ab, die im API-Center konfiguriert ist und über die Leseberechtigungen für die API Management-Instanz verfügt. Wenn Sie keine verwaltete Identität hinzugefügt oder konfiguriert haben, lesen Sie Hinzufügen einer verwalteten Identität in Ihrem API-Center weiter oben in diesem Artikel.

  • Wenn Ihr API-Center über mehrere verwaltete Identitäten verfügt, sucht der Befehl zuerst nach einer systemseitig zugewiesenen Identität. Wenn keine gefunden wird, wird die erste benutzerseitig zugewiesene Identität in der Liste ausgewählt.

Importieren aller APIs aus einer API Management-Instanz

Verwenden Sie ein Platzhalterzeichen (*), um alle APIs aus der API Management-Instanz anzugeben.

  1. Rufen Sie die Ressourcen-ID Ihrer API Management-Instanz mithilfe des Befehls az apim show ab.

    #! /bin/bash
apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

    # PowerShell syntax
$apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

  2. Verwenden Sie den Befehl az apic service import-from-apim, um die APIs zu importieren. Setzen Sie die Namen Ihres API-Centers und Ihrer Ressourcengruppe ein, und verwenden Sie *, um alle APIs aus der API Management-Instanz anzugeben.

    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*

    Hinweis

    Wenn Ihre API Management-Instanz über eine große Anzahl von APIs verfügt, kann der Import in Ihr API-Center einige Zeit in Anspruch nehmen.

Importieren einer bestimmten API aus einer API Management-Instanz

Geben Sie eine zu importierende API an, indem Sie den Namen aus der API Management-Instanz verwenden.

  1. Rufen Sie die Ressourcen-ID Ihrer API Management-Instanz mithilfe des Befehls az apim show ab.

    #! /bin/bash
apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

    # PowerShell syntax
$apimID=$(az apim show --name <apim-name> --resource-group <resource-group-name> --query id --output tsv)

  2. Verwenden Sie den Befehl az apic service import-from-apim, um die API zu importieren. Setzen Sie die Namen Ihres API-Centers und Ihrer Ressourcengruppe ein, und geben Sie einen API-Namen aus der API Management-Instanz an.

    az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>

    Hinweis

    Geben Sie <api-name> mithilfe des API-Ressourcennamens in der API Management-Instanz an, nicht mit dem Anzeigenamen. Beispiel: petstore-api anstelle von Petstore API.

Nach dem Importieren von APIs aus API Management können Sie die importierten APIs im API-Center anzeigen und verwalten.

Zugehöriger Inhalt