Tutorial: Veröffentlichen mehrerer Versionen Ihrer API

Manchmal ist es unpraktisch, wenn alle Aufrufer genau die gleiche Version Ihrer API verwenden müssen. Wenn Aufrufer auf eine höhere Version upgraden möchten, möchten sie dafür einen leicht verständlichen Ansatz verwenden. Wie in diesem Tutorial gezeigt, können in Azure API Management mehrere Versionen bereitgestellt werden.

Hintergrundinformationen finden Sie unter Versionen und Revisionen.

In diesem Tutorial lernen Sie Folgendes:

  • Hinzufügen einer neuen Version zu einer vorhandenen API
  • Auswählen eines Versionsschemas
  • Hinzufügen der Version zu einem Produkt
  • Anzeigen der Version im Entwicklerportal

Version shown in Azure portal

Voraussetzungen

Hinzufügen einer neuen Version

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
  2. Klicken Sie auf APIs.
  3. Wählen Sie in der API-Liste Demo Conference API aus.
  4. Wählen Sie neben Demo Conference API das Kontextmenü ( ... ) aus.
  5. Wählen Sie Version hinzufügen aus.

API context menu - add version

Tipp

Versionen können auch beim Erstellen einer neuen API aktiviert werden. Wählen Sie auf dem Bildschirm API hinzufügen die Option Versionsverwaltung für diese API? aus.

Auswählen eines Schemas für die Versionsverwaltung

In Azure API Management legen Sie fest, wie Aufrufer die API-Version angeben, indem Sie ein Schema für die Versionsverwaltung auswählen: Pfad, Header oder Abfragezeichenfolge. Im folgenden Beispiel wird Pfad als Schema für die Versionsverwaltung verwendet.

Geben Sie die Werte aus der folgenden Tabelle ein. Wählen Sie anschließend Erstellen aus, um Ihre Version zu erstellen.

Add version window

Einstellung Wert Beschreibung
Name demo-conference-api-v1 Eindeutiger Name in Ihrer API Management-Instanz

Da eine Version eigentlich eine neue API ist, die auf der Revision einer API basiert, wird mit dieser Einstellung der Name der neuen API angegeben.
Versionsverwaltungsschema Pfad Die Art und Weise, wie Aufrufer die API-Version angeben
Version identifer (Versionsbezeichner) v1 Schemaspezifischer Indikator der Version. Bei Auswahl von Pfad wird das Suffix für den API-URL-Pfad verwendet.

Geben Sie bei Auswahl von Header oder Abfragezeichenfolge einen zusätzlichen Wert an: den Namen des Headers oder Abfragezeichenfolgenparameters.

Ein Verwendungsbeispiel wird angezeigt.
Produkte Unbegrenzt Optional ein oder mehrere Produkte, mit denen die API-Version verknüpft ist. Zur Veröffentlichung der API muss sie einem Produkt zugeordnet werden. Sie können die Version einem Produkt auch später hinzufügen.

Nach der Erstellung der Version wird sie nun in der API-Liste unter Demo Conference API angezeigt. Sie sehen jetzt zwei APIs: das Original und v1.

Versions listed under an API in the Azure portal

Nun können Sie v1 als eine API bearbeiten und konfigurieren, die vom Original getrennt ist. Änderungen an einer Version haben keine Auswirkungen auf die andere.

Hinweis

Wenn Sie einer API ohne Versionsverwaltung eine Version hinzufügen, wird außerdem automatisch ein Original erstellt. Diese Version reagiert auf die Standard-URL. Durch die Erstellung einer Originalversion wird sichergestellt, dass alle vorhandenen Aufrufer durch das Hinzufügen einer Version nicht beeinträchtigt werden. Wenn Sie Versionen gleich bei der Erstellung einer neuen API aktivieren, wird kein Original erstellt.

Hinzufügen der Version zu einem Produkt

Damit Aufrufern die neue Version angezeigt wird, muss sie einem Produkt hinzugefügt werden. Wenn Sie einem Produkt die Version noch nicht bereits hinzugefügt haben, können Sie das jederzeit nachholen.

So fügen Sie beispielsweise dem Produkt Unlimited die Version hinzu:

  1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
  2. Wählen Sie Produkte>Unlimited>APIs>+ Hinzufügen aus.
  3. Wählen Sie Demo Conference API mit Version v1 aus.
  4. Klicken Sie auf Auswählen.

Add version to product

Verwenden von Versionsgruppen

Beim Erstellen mehrerer Versionen wird vom Azure-Portal eine Versionsgruppe erstellt. Diese stellt eine Gruppe von Versionen für eine einzelne logische API dar. Wählen Sie den Namen einer API mit mehreren Versionen aus. Im Azure-Portal wird die zugehörige Versionsgruppe angezeigt. Sie können den Namen und die Beschreibung einer virtuellen Gruppe anpassen.

Mithilfe der Azure CLI können Sie direkt mit Versionsgruppen interagieren:

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

    Launch Cloud Shell in a new window

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie unter Windows oder macOS arbeiten, 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. Weitere Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterungen bei der ersten Verwendung, 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.

Führen Sie zum Anzeigen aller Versionsgruppen den Befehl az apim api versionset list aus:

az apim api versionset list --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --output table

Wird vom Azure-Portal eine Versionsgruppe für Sie erstellt, wird dabei ein alphanumerischer Name zugewiesen. Dieser wird in der Spalte Name der Liste angezeigt. Verwenden Sie diesen Namen in anderen Azure CLI-Befehlen.

Führen Sie den Befehl az apim api versionset show aus, um Details zu einer Versionsgruppe anzuzeigen:

az apim api versionset show --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

Weitere Informationen zu Versionsgruppen finden Sie unter Versionen in Azure API Management.

Anzeigen der Version im Entwicklerportal

Wenn Sie das Entwicklerportal ausprobiert haben, können Sie die API-Versionen dort anzeigen.

  1. Klicken Sie im oberen Menü auf Entwicklerportal.
  2. Klicken Sie auf APIs und anschließend auf Demo Conference API.
  3. Ein Dropdownmenü mit mehreren Versionen neben dem API-Namen sollte angezeigt werden.
  4. Klicken Sie auf v1.
  5. Beachten Sie die Anforderungs-URL des ersten Vorgangs in der Liste. Dort sehen Sie, dass der API-URL-Pfad v1 enthält.

Nächste Schritte

In diesem Tutorial haben Sie Folgendes gelernt:

  • Hinzufügen einer neuen Version zu einer vorhandenen API
  • Auswählen eines Versionsschemas
  • Hinzufügen der Version zu einem Produkt
  • Anzeigen der Version im Entwicklerportal

Fahren Sie mit dem nächsten Tutorial fort: