Tutorial: Sichere Durchführung geringfügiger API-Änderungen mithilfe von Revisionen

GILT FÜR: Alle API Management-Ebenen

Wenn Ihre API von Entwicklern verwendet wird, müssen Sie schließlich Änderungen an dieser API vornehmen, ohne Aufrufer Ihrer API zu unterbrechen. Außerdem empfiehlt es sich, Entwickler über die vorgenommenen Änderungen zu informieren.

Verwenden Sie in Azure API Management Revisionen, um geringfügige API-Änderungen vorzunehmen. Sie können Änderungen sicher modellen und testen. Wenn Sie bereit sind, aktualisieren Sie Ihre Revision und ersetzen Sie die aktuelle API.

Weitere Informationen finden Sie unter "Versionen und Überarbeitungen".

Tipp

API-Teams können dieses Feature in Arbeitsbereichen verwenden. Arbeitsbereiche bieten isolierten Adminzugriff auf APIs und ihre eigenen API-Runtimeumgebungen.

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.
• Absolvieren Sie den folgenden Schnellstart: Erstellen einer Azure API Management-Instanz.
• Absolvieren Sie 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 Swagger Petstore aus der API-Liste oder eine andere API aus, der Sie Überarbeitungen 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, um sich zu merken, wofür sie verwendet wird.

7. Klicken Sie auf Erstellen.

   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 Swagger Petstore aus der API-Liste aus.

2. Wählen Sie " Entwurf " am oberen Rand des Bildschirms aus.

   Die Revisionsauswahl (direkt über der Registerkarte „Entwurf“) zeigt Revision 2 als derzeit ausgewählt an.

   Tipp

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

3. Klicken Sie auf + Vorgang hinzufügen.

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

5. Speichern Sie Ihren neuen Vorgang.

   

   Sie haben nun eine Änderung an Revision 2 vorgenommen.

6. Kehren Sie mithilfe der Revisionsauswahl im oberen Seitenbereich zu Revision 1 zurück.

   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. Wählen Sie im Menü oben auf der Seite "Überarbeitungen" aus.

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

3. Wählen Sie Als aktuell festlegen aus.

4. Wenn Sie Notizen zu dieser Änderung posten möchten, wählen Sie für diese API die Option "In öffentliches Änderungsprotokoll posten" aus. Geben Sie eine Änderungsbeschreibung an, die die Entwickler sehen können, beispielsweise Testrevisionen. Neuer Vorgang „Test“ hinzugefügt.

   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 "Erste Schritte mit 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. Weitere Anmeldeoptionen finden Sie unter Authentifizieren bei Azure mithilfe 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 und Verwalten 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 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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --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 swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Anzeigen von Änderungen und Änderungsprotokoll im Entwicklerportal

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

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 Swagger Petstore aus.
5. Wie Sie sehen, ist Ihr neuer test-Vorgang nun verfügbar.
6. Wählen Sie das Änderungsprotokoll in der Nähe des API-Namens 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 Ihres API-URL-Pfads, jedoch vor der Abfragezeichenfolge, hinzu, um auf eine bestimmte Revision dieser API zuzugreifen. Sie können beispielsweise eine URL wie die folgende verwenden, um auf Revision 2 der Swagger Petstore-API zuzugreifen:

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

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ächster Schritt

Fahren Sie mit dem nächsten Tutorial fort:

Veröffentlichen mehrerer Versionen Ihrer API