Tutorial: Veröffentlichen mehrerer Versionen Ihrer API
GILT FÜR: Alle API Management-Ebenen
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
Voraussetzungen
- Machen Sie sich mit der Azure API Management-Terminologie vertraut.
- Bearbeiten Sie den folgenden Schnellstart: Erstellen einer neuen Azure API Management-Dienstinstanz
- Schließen Sie darüber hinaus das folgende Tutorial ab: Importieren und Veröffentlichen Ihrer ersten API.
Hinzufügen einer neuen Version
- Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
- Klicken Sie auf APIs.
- Wählen Sie Swagger Petstore aus der API-Liste aus.
- Wählen Sie das Kontextmenü (...) neben Swagger Petstore aus.
- Wählen Sie Version hinzufügen aus.
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.
| Einstellung | Wert | Beschreibung |
|---|---|---|
| Versionsbezeichner | v1 | Schemaspezifischer Indikator der Version. Bei Auswahl von Pfad wird das Suffix für den API-URL-Pfad verwendet. |
| Versionsverwaltungsschema | Pfad | Die Art und Weise, wie Aufrufer die API-Version angeben Geben Sie bei Auswahl von Header oder Abfragezeichenfolge einen anderen Wert an: den Namen des Headers oder Abfragezeichenfolgenparameters. Ein Verwendungsbeispiel wird angezeigt. |
| Vollständiger Name der API-Version | swagger-petstore-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. |
| Produkte | Unbegrenzt (in bestimmten Dienstebenen bereitgestellt) | 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 Swagger Petstore angezeigt. Sie sehen jetzt zwei APIs: das Original und v1.
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.
Bearbeiten einer Version
Nachdem Sie die Version hinzugefügt haben, können Sie sie jetzt als eine API bearbeiten und konfigurieren, die von einem Original getrennt ist. Änderungen an einer Version haben keine Auswirkungen auf die andere. Fügen Sie z. B. API-Vorgänge hinzu, oder entfernen Sie diese, oder bearbeiten Sie die OpenAPI-Spezifikation. Weitere Informationen finden Sie unter Bearbeiten einer API.
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:
- Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
- Wählen Sie Produkte>Unlimited>APIs>+ Hinzufügen aus.
- Wählen Sie Swagger Petstore, Version v1.
- Klicke auf Auswählen.
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 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.
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.
- Klicken Sie im oberen Menü auf Entwicklerportal.
- Wählen Sie APIs und dann Swagger Petstore aus.
- Ein Dropdownmenü mit mehreren Versionen neben dem API-Namen sollte angezeigt werden.
- Klicken Sie auf v1.
- 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: