Esercitazioni: Usare le revisioni per apportare modifiche che non causano un'interruzione alle API in modo sicuro

SI APPLICA A: Tutti i livelli di Gestione API

Quando l'API viene usata dagli sviluppatori, alla fine è necessario apportare modifiche a tale API senza interrompere i chiamanti dell'API. È anche utile informare gli sviluppatori delle modifiche apportate.

In Gestione API di Azure usare le revisioni per apportare modifiche all'API senza interruzioni. È possibile modellare e testare le modifiche in modo sicuro. Quando si è pronti, rendere attuale la revisione e sostituire l'API corrente.

Per altre informazioni, vedere Versioni e revisioni.

Suggerimento

I team API possono usare questa funzionalità nelle aree di lavoro. Le aree di lavoro forniscono accesso amministrativo isolato alle API e ai propri ambienti di runtime API.

In questa esercitazione apprenderai a:

• Aggiungere una nuova revisione
• Apportare modifiche che non causano un'interruzione alla revisione
• Rendere la revisione corrente e aggiungere una voce del registro modifiche
• Esplorare il portale per sviluppatori per visualizzare le modifiche e il registro modifiche
• Accedere a una revisione API

Prerequisiti

• Acquisire familiarità con la terminologia di Gestione API di Azure.
• Completare la guida introduttiva seguente: Creare un'istanza di Gestione API di Azure.
• Completare l'esercitazione seguente: Importare e pubblicare la prima API.

Aggiungere una nuova revisione

1. Accedere al portale di Azure e passare all'istanza di Gestione API.

2. Nel menu a sinistra, in API, selezionare API.

3. Selezionare Swagger Petstore dall'elenco delle API o un'API diversa a cui si desidera aggiungere revisioni.

4. Selezionare la scheda Revisioni.

5. Selezionare + Aggiungi revisione.

   

   Suggerimento

   È anche possibile scegliere Aggiungi revisione nel menu di scelta rapida (...) dell'API.

6. Specificare una descrizione per la nuova revisione, per aiutarti a ricordare a cosa serve.

7. Seleziona Crea.

   La nuova revisione è stata creata.

   Nota

   L'API originale resta nella Revisione 1. Questa è la revisione che gli utenti continuano a chiamare, fino a quando non si sceglie di rendere corrente una revisione diversa.

Apportare modifiche che non causano un'interruzione alla revisione

1. Selezionare Swagger Petstore nell'elenco api.

2. Selezionare Progetta nella parte superiore della schermata.

   Il selettore di revisione sopra la scheda progettazione mostra la revisione 2 come attualmente selezionata.

   Suggerimento

   Usare il selettore di revisione per alternare le revisioni su cui si intende lavorare.

3. Selezionare + Aggiungi operazione.

4. Impostare la nuova operazione su POST e il Nome visualizzato, il Nome e l'URL dell'operazione come test.

5. Salvare la nuova operazione.

   

   È stata ora apportata una modifica alla Revisione 2.

6. Usare il selettore di revisione nella parte superiore della pagina per tornare alla Revisione 1.

   Si noti che la nuova operazione non viene visualizzata in revisione 1.

Rendere la revisione corrente e aggiungere una voce del registro modifiche

Portale

1. Dal menu nella parte superiore della pagina selezionare Revisioni.

2. Aprire il menu di scelta rapida (...) per la Revisione 2.

3. Selezionare Imposta come corrente.

4. Se si vogliono pubblicare note su questa modifica, selezionare Registra nel log delle modifiche pubbliche per questa API. Fornire una descrizione per la modifica che gli sviluppatori possono visualizzare, ad esempio: revisioni di test. Aggiunta una nuova operazione "test".

   La Revisione 2 è ora quella corrente.

   

Interfaccia della riga di comando di Azure

Per iniziare a usare l'interfaccia della riga di comando di Azure:

• Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

  

• Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

  • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

  • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

  • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Utilizzare questa procedura per creare e aggiornare una versione.

1. Eseguire il comando az api list per visualizzare gli ID API:

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

   L'ID API da usare nel comando successivo è il valore Name. La revisione dell'API si trova nella colonna ApiRevision.

2. Per creare la versione, con una nota sulla versione, eseguire il comando az apim api release create:

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

   La revisione rilasciata diventa la revisione corrente.

3. Per visualizzare le versioni, usare il comando 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
   

   Le note specificate vengono visualizzate nel log delle modifiche. È possibile visualizzarli nell'output del comando precedente.

4. Quando si crea una versione, il parametro --notes è facoltativo. È possibile aggiungere o modificare le note in un secondo momento usando il comando 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."
   

   Usare il valore nella colonna Name per l'ID versione.

È possibile rimuovere qualsiasi versione eseguendo il comando az apim api release delete :

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

Esplorare il portale per sviluppatori per visualizzare le modifiche e il registro modifiche

Se si prova il portale per sviluppatori, è possibile esaminare le modifiche dell'API e il log delle modifiche.

1. Nel portale di Azure accedere all'istanza di Gestione API.
2. Nel menu a sinistra, in API, selezionare API.
3. Selezionare Portale per sviluppatori dal menu in alto.
4. Nel portale per sviluppatori selezionare API e quindi Swagger Petstore.
5. Si noti che è ora disponibile la nuova operazione test.
6. Selezionare Log delle modifiche accanto al nome dell'API.
7. Si noti che il registro modifiche è ora visualizzato nell’elenco.

Accedere a una revisione API

È possibile accedere a ogni revisione all'API usando un URL appositamente formato. Aggiungere ;rev={revisionNumber} alla fine del percorso dell'URL dell'API, ma prima della stringa di query, per accedere a una revisione specifica di tale API. Ad esempio, è possibile usare un URL simile al seguente per accedere alla revisione 2 dell'API Swagger Petstore:

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

È possibile trovare i percorsi URL per le revisioni dell'API alla scheda Revisioni nel portale di Azure.

Suggerimento

È possibile accedere alla revisione corrente dell'API usando il percorso API senza la stringa ;rev, oltre all'URL completo che aggiunge ;rev={revisionNumber} al percorso API.

Riepilogo

Questa esercitazione ha descritto come:

• Aggiungere una nuova revisione
• Apportare modifiche che non causano un'interruzione alla revisione
• Rendere la revisione corrente e aggiungere una voce del registro modifiche
• Esplorare il portale per sviluppatori per visualizzare le modifiche e il registro modifiche
• Accedere a una revisione API

Passo successivo

Passare all'esercitazione successiva:

Pubblicare più versioni dell'API