Revisioni in Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

Le revisioni consentono di apportare modifiche alle API in modo controllato e sicuro. Quando si desidera apportare modifiche, creare una nuova revisione. È quindi possibile modificare e testare l'API senza disturbare i consumer di API. Quando si è pronti, si imposta la revisione corrente. Allo stesso tempo, è possibile pubblicare una voce nel log delle modifiche, per tenere aggiornati i consumer di API sulle modifiche apportate. Il log delle modifiche viene pubblicato nel portale per sviluppatori.

Con le revisioni è possibile:

• Apportare in modo sicuro modifiche alle definizioni e ai criteri dell'API, senza disturbare l'API di produzione.
• Provare le modifiche prima di pubblicarle.
• Documentare le modifiche apportate, in modo che gli sviluppatori possano comprendere le novità.
• Eseguire il rollback se vengono riscontrati dei problemi.

Per iniziare a usare le revisioni, seguire la procedura dettagliata.

Accesso a revisioni specifiche

È possibile accedere a ogni revisione all'API usando un URL appositamente formato. Aggiungere ;rev={revisionNumber} alla fine dell'URL dell'API, ma prima della stringa di query, per accedere a una revisione specifica di tale API. Ad esempio, è possibile usare questo URL per accedere alla revisione 3 dell'API customers:

https://apis.contoso.com/customers;rev=3/leads?customerId=123

Per impostazione predefinita, ogni revisione ha le stesse impostazioni di sicurezza della revisione corrente. È possibile modificare deliberatamente i criteri per una revisione specifica se si vuole applicare una sicurezza diversa per ogni revisione. Ad esempio, è possibile aggiungere un criterio di filtro IP per impedire ai chiamanti esterni di accedere a una revisione ancora in fase di sviluppo.

Revisione corrente

Una singola revisione può essere impostata come revisione corrente. Questa revisione sarà quella usata per tutte le richieste API che non specificano un numero di revisione esplicito nell'URL. È possibile eseguire il rollback a una revisione precedente impostando tale revisione come corrente.

È possibile impostare una revisione come corrente usando il portale di Azure. Se si usa PowerShell, è possibile usare il cmdlet New-AzApiManagementApiRelease.

Descrizioni delle revisioni

Quando si crea una revisione, è possibile impostare una descrizione per scopi di rilevamento personalizzati. Le descrizioni non vengono visualizzate agli utenti dell'API.

Quando si imposta una revisione come corrente, è anche possibile specificare facoltativamente una nota del log delle modifiche pubblica. Il log delle modifiche è incluso nel portale per sviluppatori per consentire agli utenti dell'API di visualizzare. È possibile modificare la nota del log delle modifiche usando il cmdlet di PowerShell Update-AzApiManagementApiRelease.

Portare offline una revisione

Una revisione può essere portata offline, cosa che la rende inaccessibile ai chiamanti anche se tentano di accedere alla revisione tramite il relativo URL. È possibile contrassegnare una revisione come offline usando il portale di Azure.

Versioni e revisioni

Le versioni e le revisioni sono caratteristiche distinte. Ogni versione può avere più revisioni, proprio come un'API senza controllo delle versioni. È possibile usare le revisioni senza usare le versioni o in altro modo. In genere le versioni vengono usate per separare le versioni delle API con modifiche di rilievo, mentre le revisioni possono essere usate per delle modifiche secondarie e non di rilievo a un'API.

Se si ritiene che la revisione abbia delle modifiche di rilievo o se si desidera trasformare formalmente la revisione in una versione beta/test, è possibile creare una versione da una revisione. Usando il portale di Azure, fare clic su "Crea versione da revisione" nel menu di scelta rapida della revisione nella scheda Revisioni.