Tutorial: Gefahrloses Vornehmen geringfügiger API-Änderungen mithilfe von Revisionen

GILT FÜR: Alle API Management-Ebenen

Wenn Ihre API einsatzbereit ist und von Entwicklern verwendet wird, müssen Sie letztendlich Änderungen an der API vornehmen und dabei darauf achten, keine Aufrufe Ihrer API zu beeinträchtigen. Außerdem empfiehlt es sich, Entwickler über die vorgenommenen Änderungen zu informieren.

Nehmen Sie in Azure API Management mithilfe von Revisionen geringfügige API-Änderungen vor, um Änderungen sicher modellieren und testen zu können. Wenn Sie so weit sind, können Sie eine Revision als aktuelle Version festlegen und Ihre bisherige API ersetzen.

Hintergrundinformationen finden Sie unter Versionen und Revisionen.

In diesem Tutorial lernen Sie Folgendes:

• Hinzufügen einer neuen Revision
• Vornehmen geringfügiger Änderungen an Ihrer Revision
• Festlegen der Revision als aktuelle Revision und Hinzufügen eines Eintrags zum Änderungsprotokoll
• Anzeigen von Änderungen und Änderungsprotokoll im Entwicklerportal
• Zugreifen auf eine API-Revision

Voraussetzungen

• Machen Sie sich mit der Azure API Management-Terminologie vertraut.
• Bearbeiten Sie den folgenden Schnellstart: Erstellen einer neuen Azure API Management-Dienstinstanz
• Absolvieren Sie außerdem das folgende Tutorial: Importieren und Veröffentlichen Ihrer ersten API.

Hinzufügen einer neuen Revision

1. Melden Sie sich beim Azure-Portal an, und wechseln Sie zu Ihrer API Management-Instanz.

2. Wählen Sie im linken Menü unter APIs die Option APIs aus.

3. Wählen Sie in der API-Liste den Eintrag Demo Conference API aus (oder eine andere API, der Sie Revisionen hinzufügen möchten).

4. Wählen Sie die Registerkarte Revisionen aus.

5. Wählen Sie + Revision hinzufügen aus.

   

   Tipp

   Revision hinzufügen kann auch im Kontextmenü ( ... ) der API ausgewählt werden.

6. Geben Sie eine Beschreibung für Ihre neue Revision an, damit Sie wissen, wofür sie verwendet wird.

7. Klicken Sie auf Erstellen.

8. Die neue Revision wird erstellt.

   Hinweis

   Ihre ursprüngliche API bleibt in Revision 1. Dies ist die Revision, die weiterhin von den Benutzern aufgerufen wird, bis Sie beschließen, eine andere Revision zur aktuellen Revision zu machen.

Vornehmen geringfügiger Änderungen an Ihrer Revision

1. Wählen Sie in der API-Liste Demo Conference API aus.

2. Klicken Sie im oberen Seitenbereich auf die Registerkarte Entwurf.

3. Beachten Sie, dass die Revisionsauswahl (direkt über der Registerkarte „Entwurf“) Revision 2 als derzeit ausgewählt anzeigt.

   Tipp

   Mit der Revisionsauswahl können Sie zwischen Revisionen wechseln, die Sie bearbeiten möchten.

4. Klicken Sie auf + Vorgang hinzufügen.

5. Legen Sie den neuen Vorgang auf POST und Anzeigename, Name und URL des Vorgangs auf test fest.

6. Speichern Sie Ihren neuen Vorgang.

   

7. Sie haben nun eine Änderung an Revision 2 vorgenommen. Kehren Sie mithilfe der Revisionsauswahl im oberen Seitenbereich zu Revision 1 zurück.

8. Wie Sie sehen, ist der neue Vorgang in Revision 1 nicht vorhanden.

Festlegen der Revision als aktuelle Revision und Hinzufügen eines Eintrags zum Änderungsprotokoll

Portal

1. Klicken Sie im oberen Bereich der Seite auf die Registerkarte Revisionen.

2. Öffnen Sie das Kontextmenü (...) für Revision 2.

3. Wählen Sie Als aktuell festlegen aus.

4. Aktivieren Sie das Kontrollkästchen Post to Public Change log for this API (In öffentlichem Änderungsprotokoll für diese API veröffentlichen), wenn Sie Hinweise zu dieser Änderung veröffentlichen möchten. Geben Sie eine Änderungsbeschreibung an, die die Entwickler sehen können, beispielsweise Testrevisionen. Neuer Vorgang „Test“ hinzugefügt.

5. Revision 2 ist jetzt aktuell.

   

Azure-Befehlszeilenschnittstelle

So beginnen Sie mit der Verwendung der 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.

Verwenden Sie dieses Verfahren, um ein Release zu erstellen und zu aktualisieren.

1. Führen Sie zum Anzeigen der API-IDs den Befehl az apim api list aus:

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

   Bei der API-ID, die im nächsten Befehl verwendet werden soll, handelt es sich um den Wert Name. Die API-Revision befindet sich in der Spalte ApiRevision.

2. Führen Sie zum Erstellen des Release mit einem Versionshinweis den Befehl az apim api release create aus:

   az apim api release create --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --api-revision 2 --service-name apim-hello-world \
       --notes 'Testing revisions. Added new "test" operation.'
   

   Die von Ihnen veröffentlichte Revision wird zur aktuellen Revision.

3. Verwenden Sie zum Anzeigen der Releases den Befehl az apim api release list:

   az apim api release list --resource-group apim-hello-word-resource-group \
       --api-id echo-api --service-name apim-hello-world --output table
   

   Die von Ihnen angegebenen Hinweise werden im Änderungsprotokoll angezeigt. Sie werden in der Ausgabe des vorherigen Befehls angezeigt.

4. Der Parameter --notes ist beim Erstellen eines Release optional. Sie können die Hinweise später mithilfe des Befehls az apim api release update hinzufügen oder ändern:

   az apim api release update --resource-group apim-hello-word-resource-group \
       --api-id demo-conference-api --release-id 00000000000000000000000000000000 \
       --service-name apim-hello-world --notes "Revised notes."
   

   Verwenden Sie den Wert in der Spalte Name als Release-ID.

Releases können mithilfe des Befehls az apim api release delete entfernt werden:

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Anzeigen von Änderungen und Änderungsprotokoll im Entwicklerportal

Wenn Sie das Entwicklerportal ausprobiert haben, können Sie die API-Änderungen und das Änderungsprotokoll dort überprüfen.

1. Navigieren Sie im Azure-Portal zu Ihrer API Management-Instanz.
2. Wählen Sie im linken Menü unter APIs die Option APIs aus.
3. Wählen Sie im oberen Menü die Option Entwicklerportal aus.
4. Wählen Sie im Entwicklerportal die Option APIs und anschließend Demo Conference API aus.
5. Wie Sie sehen, ist Ihr neuer test-Vorgang nun verfügbar.
6. Wählen Sie in der Nähe des API-Namens die Option Änderungsprotokoll aus.
7. Der Änderungsprotokolleintrag ist in der Liste enthalten.

Zugreifen auf eine API-Revision

Auf jede Revision Ihrer API kann mit einer speziellen URL zugegriffen werden. Fügen Sie ;rev={revisionNumber} am Ende des API-URL-Pfads, jedoch vor der Abfragezeichenfolge ein, um auf eine bestimmte Revision dieser API zuzugreifen. Beispielsweise können Sie diese URL verwenden, um auf Revision 2 der Demo Conference-API zuzugreifen:

https://apim-hello-world.azure-api.net/conf;rev=2/speakers

Sie finden die URL-Pfade für die Revisionen Ihrer API auf der Registerkarte Revisionen im Azure-Portal.

Tipp

Sie können auf die aktuelle Revision Ihrer API zugreifen, indem Sie den API-Pfad ohne die Zeichenfolge ;rev verwenden, zusätzlich zur vollständigen URL, die ;rev={revisionNumber} an Ihren API-Pfad anfügt.

Zusammenfassung

In diesem Tutorial haben Sie Folgendes gelernt:

• Hinzufügen einer neuen Revision
• Vornehmen geringfügiger Änderungen an Ihrer Revision
• Festlegen der Revision als aktuelle Revision und Hinzufügen eines Eintrags zum Änderungsprotokoll
• Anzeigen von Änderungen und Änderungsprotokoll im Entwicklerportal
• Zugreifen auf eine API-Revision

Nächste Schritte

Fahren Sie mit dem nächsten Tutorial fort:

Veröffentlichen mehrerer Versionen Ihrer API