Usare i valori denominati nei criteri di Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

I criteri di Gestione API sono una potente funzionalità del sistema e consentono al server di pubblicazione di modificare il comportamento dell'API tramite la configurazione. I criteri sono una raccolta di istruzioni che vengono eseguite in modo sequenziale sulla richiesta o la risposta di un'API. Le istruzioni dei criteri possono essere costruite usando valori di testo letterali, espressioni di criteri e valori denominati.

I valori denominati sono una raccolta globale di coppie nome/valore in ogni istanza di Gestione API. Non esiste alcun limite imposto per il numero di elementi nella raccolta. I valori denominati possono essere usati per gestire valori stringa costanti e segreti all'interno dell'intera configurazione e di tutti i criteri delle API.

Tipi valore

Tipo	Descrizione
Normale	Stringa letterale o espressione di criteri
Segreto	Stringa letterale o espressione di criteri crittografata da Gestione API
Key vault	Identificatore di un segreto archiviato in un insieme di credenziali delle chiavi di Azure.

I valori o i segreti normali possono contenere espressioni di criteri. Ad esempio, l'espressione @(DateTime.Now.ToString()) restituisce una stringa contenente la data e l'ora correnti.

Per informazioni dettagliate sugli attributi dei valori denominati, vedere Informazioni di riferimento sull'API REST di Gestione API.

Segreti di Key Vault

I valori dei segreti possono essere archiviati come stringhe crittografate in Gestione API (segreti personalizzati) o facendo riferimento ai segreti in Azure Key Vault.

È consigliabile usare i segreti dell'insieme di credenziali delle chiavi perché consentono di migliorare la sicurezza di Gestione API:

• I segreti archiviati negli insiemi di credenziali delle chiavi possono essere riutilizzati nei servizi
• È possibile applicare criteri di accesso granulare ai segreti
• I segreti aggiornati nell'insieme di credenziali delle chiavi vengono ruotati automaticamente in Gestione API. Dopo l'aggiornamento nell'insieme di credenziali delle chiavi, un certificato denominato in Gestione API viene aggiornato entro 4 ore. È anche possibile aggiornare manualmente il segreto usando il portale di Azure o tramite l'API REST di gestione.

Prerequisiti

• Se non è ancora stata creata un'istanza del servizio Gestione API, vedere Creare un'istanza del servizio Gestione API.

Prerequisiti per l'integrazione dell'insieme di credenziali delle chiavi

• Se non si ha già un insieme di credenziali delle chiavi, crearne uno. Per la procedura per la creazione di un insieme di credenziali delle chiavi, vedere Avvio rapido: Creare un insieme di credenziali delle chiavi usando il portale di Azure.

  Per creare o importare un segreto nell'insieme di credenziali delle chiavi, vedere Avvio rapido: Impostare e recuperare un segreto da Azure Key Vault usando il portale di Azure.

• Abilitare un'identità gestita assegnata dal sistema o assegnata dall'utente nell'istanza di Gestione API.

Configurare l'accesso all'insieme di credenziali delle chiavi

1. Nel portale passare all'insieme di credenziali delle chiavi.

2. Nel menu a sinistra, selezionare Configurazione di accesso e prendere nota del modello di autorizzazione configurato.

3. A seconda del modello di autorizzazione, configurare un criterio di accesso dell'insieme di credenziali delle chiavi o un accesso al controllo degli accessi in base al ruolo di Azure per un'identità gestita di Gestione API.

   Per aggiungere un criterio di accesso dell'insieme di credenziali delle chiavi:
   

   1. Selezionare Criteri di accesso nel menu a sinistra.
   2. Nella pagina Criteri di accesso selezionare + Crea.
   3. Nella scheda Autorizzazioni, in Autorizzazioni segrete selezionare Ottieni e Elenco, quindi selezionare Avanti.
   4. Nella scheda Entità, Seleziona entità , cercare il nome della risorsa dell'identità gestita e quindi selezionareAvanti. Se si usa un'identità assegnata dal sistema, l'entità è il nome dell'istanza di Gestione API.
   5. Selezionare di nuovo Avanti. Nella scheda Rivedi e crea selezionare Crea.

   Per configurare l'accesso al controllo degli accessi in base al ruolo di Azure:
   

   1. Nel menu a sinistra selezionare Controllo di accesso (IAM).
   2. Nella pagina Controllo di accesso (IAM), selezionare Aggiungi assegnazione di ruolo.
   3. Nella scheda Ruolo selezionare Utente dei segreti dell'insieme di credenziali delle chiavi.
   4. Nella scheda Membri selezionare Identità gestita>+ Seleziona membri.
   5. Nella pagina Seleziona identità gestita, selezionare l'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente associata all'istanza di Gestione API e quindi selezionare Seleziona.
   6. Seleziona Rivedi + assegna.

Requisiti per il firewall di Key Vault

Se il firewall di Key Vault è abilitato nell'insieme di credenziali delle chiavi, sono necessari requisiti aggiuntivi:

• Per accedere all'insieme di credenziali delle chiavi, è necessario usare l'identità gestita assegnata dal sistema dell'istanza di Gestione API.

• Nel firewall di Key Vault, abilitare l'opzione Consenti ai servizi Microsoft attendibili di ignorare questo firewall.

• Assicurarsi che l'indirizzo IP del client locale sia autorizzato ad accedere temporaneamente all'insieme di credenziali delle chiavi mentre si seleziona un certificato o un segreto da aggiungere a Gestione API di Azure. Per altre informazioni, vedere Configurare le impostazioni di rete di Azure Key Vault.

  Dopo aver completato la configurazione, è possibile bloccare l'indirizzo client nel firewall Key Vault.

Requisiti della rete virtuale

Se l'istanza di Gestione API viene distribuita in una rete virtuale, configurare anche le impostazioni di rete seguenti:

• Abilitare un endpoint di servizio in Azure Key Vault nella subnet di Gestione API.
• Configurare una regola del gruppo di sicurezza di rete (NSG) per consentire il traffico in uscita ai tag del servizio AzureKeyVault e AzureActiveDirectory.

Per informazioni dettagliate, vedere Configurazione di rete durante la configurazione di Gestione API di Azure in una rete virtuale.

Aggiungere o modificare un valore denominato

Aggiungere un segreto dell'insieme di credenziali delle chiavi a Gestione API

Vedere Prerequisiti per l'integrazione dell'insieme di credenziali delle chiavi.

Importante

Quando si aggiunge un segreto dell'insieme di credenziali delle chiavi all'istanza di Gestione API, è necessario disporre delle autorizzazioni per elencare i segreti dell'insieme di credenziali delle chiavi.

Attenzione

Quando si usa un segreto dell'insieme di credenziali delle chiavi in Gestione API, prestare attenzione a non eliminare il segreto, l'insieme di credenziali delle chiavi o l'identità gestita usata per accedere all'insieme di credenziali delle chiavi.

1. Nel portale di Azure accedere all'istanza di Gestione API.

2. In API selezionare Valori denominati>+Aggiungi.

3. Immettere un identificatore Nome e immettere un Nome visualizzato usato per fare riferimento alla proprietà nei criteri.

4. In Tipo valore selezionare Insieme di credenziali delle chiavi.

5. Immettere l'identificatore di un segreto dell'insieme di credenziali delle chiavi (senza versione) oppure scegliere Seleziona per selezionare un segreto da un insieme di credenziali delle chiavi.

   Importante

   Se si immette manualmente un identificatore del segreto dell'insieme di credenziali delle chiavi, assicurarsi che non disponga di informazioni sulla versione. In caso contrario, il segreto non verrà ruotato automaticamente in Gestione API dopo un aggiornamento nell'insieme di credenziali delle chiavi.

6. In Identità client selezionare un'identità gestita assegnata dal sistema o da un utente esistente. Di seguito viene descritto come aggiungere o modificare le identità gestite nel servizio Gestione API.

   Nota

   L'identità deve disporre delle autorizzazioni per ottenere ed elencare i segreti dell'insieme di credenziali delle chiavi. Se non è già stato configurato l'accesso all'insieme di credenziali delle chiavi, Gestione API richiede di configurare automaticamente l'identità con le autorizzazioni necessarie.

7. Aggiungere uno o più tag facoltativi per organizzare i valori denominati, quindi selezionare Salva.

8. Seleziona Crea.

   

Aggiungere un valore normale o segreto a Gestione API

Portale

1. Nel portale di Azure accedere all'istanza di Gestione API.
2. In API selezionare Valori denominati>+Aggiungi.
3. Immettere un identificatore Nome e immettere un Nome visualizzato usato per fare riferimento alla proprietà nei criteri.
4. In Tipo valore selezionare Normale o Secreto.
5. In Valore immettere una stringa o un'espressione di criteri.
6. Aggiungere uno o più tag facoltativi per organizzare i valori denominati, quindi selezionare Salva.
7. Seleziona Crea.

Dopo aver creato il valore denominato, è possibile modificarlo selezionando il nome. Se si modifica il nome visualizzato, tutti i criteri che fanno riferimento a tale valore denominato vengono aggiornati automaticamente con il nuovo nome.

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.

Per aggiungere un valore denominato, usare il comando az apim nv create:

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

Dopo aver creato un valore denominato, è possibile aggiornarlo usando il comando az apim nv update. Per visualizzare tutti i valori denominati, eseguire il comando az apim nv list :

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

Per visualizzare i dettagli del valore denominato creato per questo esempio, eseguire il comando az apim nv show:

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Questo esempio è un valore segreto. Il comando precedente non restituisce il valore. Per visualizzare il valore, eseguire il comando az apim nv show-secret:

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Per aggiungere un valore denominato, usare il comando az apim nv delete:

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Usare un valore denominato

Gli esempi in questa sezione usano i valori denominati illustrati nella tabella seguente.

Nome	valore	Segreto
ContosoHeader	TrackingId	Falso
ContosoHeaderValue	••••••••••••••••••••••	Vero
ExpressionProperty	@(DateTime.Now.ToString())	Falso
ContosoHeaderValue2	This is a header value.	Falso

Per usare un valore denominato in un criterio, inserirne il nome visualizzato all'interno di parentesi graffe doppie, ad esempio {{ContosoHeader}}, come illustrato nell'esempio seguente:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

In questo esempio, la proprietà ContosoHeader viene usata come nome di un'intestazione in un criterio set-header e la proprietà ContosoHeaderValue viene usata come valore di tale intestazione. Quando questo criterio viene valutato durante una richiesta o una risposta al gateway di Gestione API, {{ContosoHeader}} e {{ContosoHeaderValue}} vengono sostituiti dai rispettivi valori.

I valori denominati possono essere usati come valori completi di attributo o di elemento, come illustrato nell'esempio precedente, ma possono anche essere inseriti all'interno di un'espressione di testo o combinati con una parte di un'espressione di testo, come illustrato nell'esempio seguente:

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

I valori denominati possono anche contenere espressioni di criteri. Nell'esempio seguente viene usata l'espressione ExpressionProperty.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

Quando questo criterio viene valutato, {{ExpressionProperty}} viene sostituito dal valore corrispondente, @(DateTime.Now.ToString()). Poiché il valore è un'espressione di criteri, l'espressione viene valutata e il criterio passa alla fase di esecuzione.

È possibile eseguirne i test nel portale di Azure o nel portale per sviluppatori chiamando un'operazione il cui ambito contiene criteri con valori denominati. Nell'esempio seguente viene chiamata un'operazione che contiene i due criteri di esempio precedenti set-header con valori denominati. La risposta contiene due intestazioni personalizzate che vengono configurate tramite criteri con valori denominati.

Se si osserva la traccia API in uscita relativa a una chiamata che include i due criteri con valori denominati degli esempi precedenti, è possibile vedere i due criteri set-header con i valori denominati inseriti, nonché la valutazione delle espressioni dei criteri per il valore denominato che contiene l'espressione.

L'interpolazione di stringhe può essere usata anche con valori denominati.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Il valore per CustomHeader sarà The URL encoded value is This+is+a+header+value..

Attenzione

Se un criterio fa riferimento a un segreto in Azure Key Vault, il valore dell'insieme di credenziali delle chiavi sarà visibile agli utenti che hanno accesso alle sottoscrizioni abilitate per traccia delle richieste API.

Sebbene i valori denominati possano contenere espressioni di criteri, non possono contenere altri valori denominati. Se il testo contenente un riferimento a un valore denominato viene usato per un valore, ad esempio Text: {{MyProperty}}, tale riferimento non verrà risolto e sostituito.

Eliminare un valore denominato

Per eliminare un valore denominato, selezionare il nome e quindi selezionare Elimina dal menu di scelta rapida (...).

Importante

Se in un criterio di Gestione API si fa riferimento al valore denominato, sarà possibile eliminarlo solo dopo aver rimosso il valore denominato da tutti i criteri che lo usano.

Passaggi successivi

• Ulteriori informazioni sull'uso dei criteri
  • Criteri di Gestione API
  • Riferimento ai criteri
  • Espressioni di criteri