Zelfstudie: Revisies gebruiken om onbreekbaar API-wijzigingen veilig aan te brengen

VAN TOEPASSING OP: Alle API Management-lagen

Wanneer uw API klaar is voor gebruik en wordt gebruikt door ontwikkelaars, moet u uiteindelijk wijzigingen aanbrengen in die API en tegelijkertijd geen aanroepers van uw API verstoren. Het is ook handig om ontwikkelaars te informeren over de aangebrachte wijzigingen.

Gebruik in Azure API Management revisies om vaste API-wijzigingen aan te brengen, zodat u wijzigingen veilig kunt modelleren en testen. Wanneer u klaar bent, kunt u een revisie actueel maken en uw huidige API vervangen.

Zie Versies en revisies voor achtergrond.

In deze zelfstudie leert u het volgende:

• Een nieuwe revisie toevoegen
• Vaste wijzigingen aanbrengen in uw revisie
• Uw revisie actualiseren en een logboekvermelding over de wijziging toevoegen
• Door de portal voor ontwikkelaars browsen om de wijzigingen en het logboek in te zien
• Toegang tot een API-revisie

Vereisten

• Leer de terminologie van Azure API Management.
• Lees de volgende snelstartgids: Een Azure API Management-exemplaar maken.
• Voltooi tevens de volgende zelfstudie: Uw eerste API importeren en publiceren.

Een nieuwe revisie toevoegen

1. Meld u aan bij Azure Portal en ga naar uw API Management-exemplaar.

2. Selecteer API's in het linkermenu onder API's.

3. Selecteer Swagger Petstore in de API-lijst (of een andere API waaraan u revisies wilt toevoegen).

4. Selecteer het tabblad Revisies.

5. Selecteer + Revisie toevoegen.

   

   Tip

   U kunt ook Revisie toevoegen selecteren in het contextmenu (...) van de API.

6. Geef een beschrijving op voor de nieuwe revisie om te onthouden waarvoor deze wordt gebruikt.

7. Selecteer Maken.

8. Uw nieuwe revisie wordt nu gemaakt.

   Notitie

   Uw oorspronkelijke API blijft in Revisie 1. Dit is de revisie die uw gebruikers blijven aanroepen, totdat u ervoor kiest om een andere revisie de huidige te maken.

Vaste wijzigingen aanbrengen in uw revisie

1. Selecteer Swagger Petstore in de API-lijst.

2. Selecteer boven in het scherm het tabblad Ontwerp.

3. U ziet dat de revisieselector (direct boven het tabblad Ontwerp) Revisie 2 aangeeft als de huidige selectie.

   Tip

   Gebruik de revisieselector om te schakelen tussen de wijzigingen waaraan u wilt werken.

4. Klik op + Bewerking toevoegen.

5. Stel de nieuwe bewerking in op POST en de weergavenaam, naam en URL van de bewerking als test.

6. Sla uw nieuwe bewerking op.

   

7. U hebt nu een wijziging aangebracht in Revisie 2. Gebruik de revisieselector bovenaan de pagina om over te schakelen naar Revisie 1.

8. U ziet dat de nieuwe bewerking niet wordt weergegeven in Revisie 1.

Uw revisie actualiseren en een logboekvermelding over de wijziging toevoegen

Portal

1. Klik op het tabblad Revisies in het menu aan de bovenkant van de pagina.

2. Open het contextmenu (... ) voor Revisie 2.

3. Selecteer Instellen als huidige.

4. Schakel het selectievakje Op het openbare wijzigingenlogboek voor deze API plaatsen in als u opmerkingen over deze wijziging wilt plaatsen. Geef een beschrijving op voor uw wijziging die de ontwikkelaars kunnen zien, bijvoorbeeld: Revisies testen. Nieuwe testbewerking toegevoegd.

5. Revisie 2 is nu actueel.

   

Azure-CLI

Ga als volgt te werk om Azure CLI te gebruiken:

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Gebruik deze procedure om een release te maken en bij te werken.

1. Voer de opdracht az api list uit om uw API-id's te zien:

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

   De API-id die in de volgende opdracht moet worden gebruikt, is de Name waarde. De API-revisie bevindt zich in de ApiRevision kolom.

2. Als u de release wilt maken, voert u met een releasenotitie de opdracht az apim api release create uit :

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

   De revisie die u uitbrengt, wordt de huidige revisie.

3. Gebruik de opdracht az apim api release list om uw releases te bekijken:

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

   De notities die u opgeeft, worden weergegeven in het wijzigingenlogboek. U kunt deze zien in de uitvoer van de vorige opdracht.

4. Wanneer u een release maakt, is de --notes parameter optioneel. U kunt de notities later toevoegen of wijzigen met behulp van de opdracht az apim api release update :

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

   Gebruik de waarde in de Name kolom voor de release-id.

U kunt elke release verwijderen door de opdracht az apim api release delete uit te voeren:

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

Door de portal voor ontwikkelaars browsen om de wijzigingen en het logboek in te zien

Als u de ontwikkelaarsportal hebt geprobeerd, kunt u de wijzigingen in de API en het wijzigingslogboek bekijken.

1. Blader in Azure Portal naar uw API Management-exemplaar.
2. Selecteer API's in het linkermenu onder API's.
3. Selecteer Ontwikkelaarsportal in het menu bovenaan.
4. Selecteer API's in de ontwikkelaarsportal en selecteer vervolgens Swagger Petstore.
5. U ziet dat uw nieuwe testbewerking nu beschikbaar is.
6. Selecteer Changelog bij de naam van de API.
7. U ziet dat uw wijzigingslogboekvermelding wordt weergegeven in de lijst.

Toegang tot een API-revisie

Elke revisie van uw API kan worden geopend met behulp van een speciaal gevormde URL. Voeg ;rev={revisionNumber} toe aan het einde van het API-URL-pad, maar vóór de querytekenreeks, om toegang te krijgen tot een specifieke revisie van die API. U kunt bijvoorbeeld een URL gebruiken die vergelijkbaar is met de volgende url voor toegang tot revisie 2 van de Swagger Petstore-API:

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

U vindt de URL-paden voor de revisies van uw API op het tabblad Revisies in Azure Portal.

Tip

U hebt toegang tot de huidige revisie van uw API met behulp van het API-pad zonder de ;rev tekenreeks, naast de volledige URL die aan uw API-pad wordt toegevoegd ;rev={revisionNumber} .

Samenvatting

In deze zelfstudie heeft u het volgende geleerd:

• Een nieuwe revisie toevoegen
• Vaste wijzigingen aanbrengen in uw revisie
• Uw revisie actualiseren en een logboekvermelding over de wijziging toevoegen
• Door de portal voor ontwikkelaars browsen om de wijzigingen en het logboek in te zien
• Toegang tot een API-revisie

Volgende stappen

Ga door naar de volgende zelfstudie:

Meerdere versies van uw API publiceren