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

Articolo
01/03/2025

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.

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 anche l'esercitazione seguente: Importare e pubblicare la prima API.

Aggiungere una nuova revisione

Accedere al portale di Azure e passare all'istanza di Gestione API.
Nel menu a sinistra, in API, selezionare API.
Selezionare Swagger Petstore dall'elenco api (o un'altra API a cui si desidera aggiungere revisioni).
Selezionare la scheda Revisioni.
Selezionare + Aggiungi revisione.

Suggerimento

È anche possibile scegliere Aggiungi revisione nel menu di scelta rapida (...) dell'API.
Fornire una descrizione della nuova revisione, per ricordarsi per che cosa verrà usato.
Seleziona Crea.
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 che non causano un'interruzione alla revisione

Selezionare Swagger Petstore nell'elenco api.
Selezionare la scheda Progettazione nella parte superiore della schermata.
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.
Selezionare + Aggiungi operazione.
Impostare la nuova operazione su POST e il Nome visualizzato, il Nome e l'URL dell'operazione come test.
Salvare la nuova operazione.
È stata ora apportata una modifica alla Revisione 2. 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
Interfaccia della riga di comando di Azure

Selezionare la scheda Revisioni dal menu nella parte superiore della pagina.
Aprire il menu di scelta rapida (...) per la Revisione 2.
Selezionare Imposta come corrente.
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".
La Revisione 2 è ora quella corrente.

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

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su 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.

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.

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.

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

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

Nel portale di Azure accedere all'istanza di Gestione API.
Nel menu a sinistra, in API, selezionare API.
Selezionare Portale per sviluppatori dal menu in alto.
Nel portale per sviluppatori selezionare API e quindi Swagger Petstore.
Si noti che è ora disponibile la nuova operazione test.
Fare clic su Log delle modifiche accanto al nome dell'API.
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.

Screenshot degli URL di revisione nel portale.

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

Passaggi successivi

Passare all'esercitazione successiva:

Pubblicare più versioni dell'API

Condividi tramite