Självstudie: Använda revisioner för att göra icke-inbrytande API-ändringar på ett säkert sätt

GÄLLER FÖR: Alla API Management-nivåer

När ditt API är redo att användas av utvecklare måste du så småningom göra ändringar i API:et och samtidigt inte störa anropare av ditt API. Det är också bra att informera utvecklarna om de ändringar du gjort.

I Azure API Management använder du revisioner för att göra icke-banbrytande API-ändringar så att du kan modellera och testa ändringar på ett säkert sätt. När du är klar kan du göra en revision aktuell och ersätta ditt aktuella API.

Bakgrund finns i Versioner och revisioner.

I den här självstudien lär du dig att:

• Lägga till en ny version
• Gör icke-inbrytningsändringar i revisionen
• Aktualisera dina revisioner och lägga till en ändringsloggpost
• Gå till utvecklarportalen för att se dina ändringar och ändringsloggen
• Få åtkomst till en API-revision

Förutsättningar

• Lär dig Azure API Management-terminologin.
• Slutför följande snabbstart: Skapa en Azure API Management-instans.
• Slutför även följande självstudie: Importera och publicera ditt första API.

Lägga till en ny version

1. Logga in på Azure Portal och gå till din API Management-instans.

2. I den vänstra menyn går du till API:er och väljer API:er.

3. Välj Demo Conference API i API-listan (eller ett annat API som du vill lägga till revisioner till).

4. Välj fliken Revisioner .

5. Välj + Lägg till revision.

   

   Dricks

   Du kan också välja Lägg till revision i snabbmenyn (...) för API:et.

6. Ange en beskrivning för den nya revisionen för att komma ihåg vad den används till.

7. Välj Skapa.

8. Nu skapas en ny version.

   Kommentar

   Det ursprungliga API:et ligger kvar i Revision 1. Det är den här revisionen dina användare fortsätter att anropa tills du väljer att aktualisera en annan revision aktuella.

Gör icke-inbrytningsändringar i revisionen

1. Välj Demo Conference API från listan över API.

2. Överst på skärmen väljer du fliken Design.

3. Observera att revisionsväljaren (direkt ovanför designfliken) Revision 2 som aktuellt val.

   Dricks

   Använd revisionsväljaren för att växla mellan de revisioner du vill arbeta med.

4. Välj + Lägg till åtgärd.

5. Ange post för den nya åtgärden och åtgärdens visningsnamn, namn och URL som test.

6. Spara den nya åtgärden.

   

7. Nu har du ändrat till Revision 2. Använd revisionsväljaren längst upp på sidan för att växla tillbaka till Revision 1.

8. Observera att den nya åtgärden inte visas i revision 1.

Aktualisera dina revisioner och lägga till en ändringsloggpost

Portal

1. Välj fliken Revisioner från menyn upptill på sidan.

2. Öppna snabbmenyn (...) för revision 2.

3. Välj Gör aktuell.

4. Markera kryssrutan Post to Public Change log (Publicera till offentlig ändring) för det här API :et om du vill publicera anteckningar om den här ändringen. Ange en beskrivning av din ändring som utvecklarna kan se, till exempel: Testa revisioner. Ny "teståtgärd" har lagts till.

5. Nu är Revision 2 aktuell.

   

Azure CLI

Så här börjar du använda Azure CLI:

• Använd Bash-miljön i Azure Cloud Shell. Mer information finns i Snabbstart för Bash i Azure Cloud Shell.

  

• Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du köra Azure CLI i en Docker-container. Mer information finns i Så här kör du Azure CLI i en Docker-container.

  • Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login. Slutför autentiseringsprocessen genom att följa stegen som visas i terminalen. Andra inloggningsalternativ finns i Logga in med Azure CLI.

  • När du uppmanas att installera Azure CLI-tillägget vid första användningen. Mer information om tillägg finns i Använda tillägg med Azure CLI.

  • Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.

Använd den här proceduren för att skapa och uppdatera en version.

1. Kör kommandot az apim api list för att se dina API-ID:n:

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

   API-ID:t som ska användas i nästa kommando är värdet Name . API-revisionen ApiRevision finns i kolumnen .

2. Om du vill skapa versionen kör du kommandot az apim api release create med en versionsanteckning:

   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.'
   

   Den revision som du släpper blir den aktuella revisionen.

3. Om du vill se dina versioner använder du kommandot 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
   

   De anteckningar som du anger visas i ändringsloggen. Du kan se dem i utdata från föregående kommando.

4. När du skapar en version är parametern --notes valfri. Du kan lägga till eller ändra anteckningarna senare med hjälp av kommandot az apim api release update :

   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."
   

   Använd värdet i Name kolumnen för versions-ID:t.

Du kan ta bort valfri version genom att köra kommandot az apim api release delete :

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

Gå till utvecklarportalen för att se dina ändringar och ändringsloggen

Om du har provat utvecklarportalen kan du granska API-ändringarna och ändringsloggen där.

1. I Azure Portal navigerar du till din API Management-instans.
2. I den vänstra menyn går du till API:er och väljer API:er.
3. Välj Utvecklarportal på den översta menyn.
4. I utvecklarportalen väljer du API:er och sedan Demo Conference API.
5. Lägg märke till att din nya teståtgärd nu är tillgänglig.
6. Välj Ändringslogg nära API-namnet.
7. Observera att din ändringsloggpost visas i listan.

Få åtkomst till en API-revision

Varje revision av API:et kan nås med hjälp av en särskilt utformad URL. Lägg till ;rev={revisionNumber} i slutet av DIN API-URL-sökväg, men innan frågesträngen, för att få åtkomst till en specifik revision av api:et. Du kan till exempel använda den här URL:en för att få åtkomst till revision 2 av Demo Conference-API:et:

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

Du hittar URL-sökvägarna för API:ets revisioner på fliken Revisioner i Azure Portal.

Dricks

Du kan komma åt den aktuella revisionen av ditt API med hjälp av API-sökvägen utan strängen ;rev , förutom den fullständiga URL:en som lägger ;rev={revisionNumber} till i din API-sökväg.

Sammanfattning

I den här självstudiekursen lärde du dig att:

• Lägga till en ny version
• Gör icke-inbrytningsändringar i revisionen
• Aktualisera dina revisioner och lägga till en ändringsloggpost
• Gå till utvecklarportalen för att se dina ändringar och ändringsloggen
• Få åtkomst till en API-revision

Nästa steg

Gå vidare till nästa kurs:

Publicera flera versioner av ditt API