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, impostare la revisione corrente. Allo stesso tempo, è possibile pubblicare una voce nel log delle modifiche per mantenere aggiornati gli utenti dell'API con le modifiche apportate. Il log delle modifiche viene pubblicato nel portale per sviluppatori.

Annotazioni

Il portale per sviluppatori non è disponibile nel livello a consumo.

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 nostra guida passo passo.

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.

Annotazioni

Deve ;rev={id} essere aggiunto all'ID API e non al percorso URI.

Revisione corrente

Una singola revisione può essere impostata come revisione corrente . Questa revisione è 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 New-AzApiManagementApiRelease cmdlet .

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 Update-AzApiManagementApiRelease cmdlet di PowerShell.

Attenzione

Se si modifica una revisione non corrente di un'API, non è possibile modificare le proprietà seguenti:

• Nome
• TIPO
• Description
• Sottoscrizione obbligatoria
• Versione dell'API
• Descrizione della versione dell'API
• Percorso
• Protocols

Queste proprietà possono essere modificate solo nella revisione corrente. Se le modifiche modificano una di queste proprietà in una revisione non corrente, viene visualizzato il messaggio Can't change property for non-current revision di errore.

Portare offline una revisione

Una revisione può essere portata offline, che 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.

Annotazioni

È consigliabile portare offline le revisioni quando non vengono usati per i test.

Versioni e revisioni

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

Se la revisione presenta 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, selezionare "Crea versione da revisione" nel menu di scelta rapida delle revisioni nella scheda Revisioni.