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. È possibile usare i valori denominati per gestire i valori di stringa costanti e i segreti in tutte le configurazioni e i criteri dell'API.

Tipi di valori

Type	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 nel Key Vault perché consentono di migliorare la sicurezza di API Management:

Note

Attualmente, l'integrazione con l'insieme di credenziali delle chiavi per questo scenario non è disponibile nelle aree di lavoro.

• È possibile riutilizzare i segreti archiviati nei insiemi di credenziali chiave nei servizi.
• È possibile applicare criteri di accesso granulari ai segreti.
• I segreti aggiornati nell'insieme di credenziali delle chiavi vengono ruotati automaticamente in Gestione API. Dopo l'aggiornamento nel Key Vault, un valore specificato nella Gestione API viene aggiornato entro quattro ore. È anche possibile aggiornare manualmente il segreto usando il portale di Azure o tramite l'API REST di gestione.

Note

I segreti archiviati in Azure Key Vault devono essere compresi tra 1 e 4096 caratteri, perché Gestione API non può recuperare valori che superano questo limite.

Prerequisiti

• Se non è ancora stata creata un'istanza del servizio Gestione API, vedere Avvio rapido: Creare una nuova istanza di Gestione API di Azure usando il portale di Azure.

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

Note

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

• 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, andare all'insieme di credenziali delle chiavi.
2. Nel menu a sinistra selezionare Impostazioni Configurazione>di accesso. Si noti il 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 una policy di accesso del Key Vault:

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 Recupera ed Elenco e quindi selezionare Avanti.
4. Nella scheda Principale cercare il nome della risorsa per l'identità gestita, quindi selezionare Avanti. Se si usa un'identità assegnata dal sistema, l'entità è il nome dell'istanza di Gestione API.
5. Seleziona nuovamente 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 di segreti Key Vault, quindi selezionare Avanti.
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. Selezionare Rivedi e assegna.

Requisiti per il firewall di Key Vault

Se il firewall di Key Vault è abilitato nella tua Key Vault, devi soddisfare questi requisiti:

• Per accedere al Key Vault, è necessario usare l'identità gestita assegnata dal sistema dell'istanza di API Management.

• 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 del cliente nel firewall del 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 per 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 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. Aggiungere uno o più tag facoltativi per aiutare a organizzare i valori specificati.

5. Nell'elenco a discesa Tipo selezionare Key Vault.

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

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

   Note

   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.

8. Selezionare Salva e quindi 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. Nell'elenco a discesa Tipo, selezionare Plain o Secret.
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. Selezionare 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:

• Utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad 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, considerare l'esecuzione dell'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 Eseguire l'autenticazione ad Azure con 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 e gestire 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 . Sostituisci il nome del gruppo di risorse e il nome dell'istanza di API Management nei valori resource-group e service-name.

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	False
ContosoHeaderValue	••••••••••••••••••••••	True
ExpressionProperty	@(DateTime.Now.ToString())	False
ContosoHeaderValue2	This is a header value.	False

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.

È possibile usare i valori denominati come valori di attributo o elemento completi come illustrato nell'esempio precedente, ma possono anche essere inseriti o combinati con parte di un'espressione di testo letterale, 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 procede con l'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.

È anche possibile usare l'interpolazione di stringhe 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 una politica fa riferimento a un segreto in Azure Key Vault, il valore dal key vault è visibile agli utenti che hanno accesso alle sottoscrizioni abilitate per il tracciamento 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, 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.

Contenuti correlati

Altre informazioni sull'uso dei criteri:

• Criteri di Gestione API
• Riferimento ai criteri
• Espressioni di criteri