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

SI APPLICA A: Tutti i livelli di Gestione API

Quando l'API è pronta per l'uso e viene usata dagli sviluppatori, è infine necessario apportare modifiche a tale API e allo stesso tempo non interrompere i chiamanti dell'API. È anche utile informare gli sviluppatori delle modifiche apportate.

In Gestione API di Azure è possibile usare le revisioni per apportare modifiche che non causano un'interruzione alle API al fine di modellare e testare le modifiche in modo sicuro. Quando si è pronti, è sufficiente impostare una revisione come corrente e sostituire l'API in uso.

Per i concetti di base, vedere Versioni e revisioni e Controllo delle versioni delle API con Gestione API di Azure.

In questa esercitazione apprenderai a:

• Aggiungere una nuova revisione
• Apportare modifiche non di rilievo 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

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 anche 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. Selezionare API.

3. Selezionare Demo Conference API nell'elenco di API oppure l'API a cui si vuole aggiungere le revisioni.

4. Selezionare la scheda Revisioni.

5. Selezionare + Aggiungi revisione.

   

   Suggerimento

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

6. Fornire una descrizione per la nuova revisione, per ricordarsi per che cosa verrà usato.

7. Seleziona Crea.

8. La nuova revisione è stata creata.

   Nota

   L'API originale resta nella Revisione 1. Si tratta della revisione che gli utenti continueranno a chiamare fino a quando non si imposta come corrente una revisione diversa.

Apportare modifiche non di rilievo alla revisione

1. Selezionare Demo Conference API (API Demo Conference) nell'elenco di API.

2. Selezionare la scheda Progettazione nella parte superiore della schermata.

3. Si noti che il selettore di revisione (appena sopra la scheda Progettazione) mostra la revisione corrente come Revisione 2.

   Suggerimento

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

4. Selezionare + Aggiungi operazione.

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

6. Salvare la nuova operazione.

   

7. È stata ora apportata una modifica alla Revisione 2. Usare il selettore di revisione nella parte superiore della pagina per tornare alla Revisione 1.

8. 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. Selezionare la scheda Revisioni dal menu nella parte superiore della pagina.

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

3. Selezionare Imposta come corrente.

4. Selezionare Post to Public Change Log for this API(Pubblica nel log delle modifiche pubblico per questa API) per pubblicare delle note sulla modifica. Fornire una descrizione per la modifica che gli sviluppatori possono visualizzare, ad esempio: revisioni di test. Aggiunta una nuova operazione "test".

5. 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 la Avvio rapido di Bash in 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 Accedere tramite 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 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 apim 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 demo-conference-api --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 echo-api --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 demo-conference-api --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 demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

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

Nel portale per sviluppatori, è possibile esaminare le modifiche apportate all'API e il log delle modifiche.

1. Nel portale di Azure selezionare API.
2. Selezionare Portale per sviluppatori dal menu in alto.
3. Nel portale per sviluppatori selezionare API, quindi Demo Conference API.
4. Si noti che è ora disponibile la nuova operazione test.
5. Fare clic su Log delle modifiche accanto al nome dell'API.
6. Si noti che il registro modifiche è ora visualizzato nell’elenco.

Passaggi successivi

Questa esercitazione ha descritto come:

• Aggiungere una nuova revisione
• Apportare modifiche non di rilievo 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

Passare all'esercitazione successiva:

Pubblicare più versioni dell'API