Usare valori denominati nei criteri di Azure Gestione API

Gestione API criteri sono una potente funzionalità del sistema che consente 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 i valori di stringa costanti e i segreti in tutte le configurazioni e i criteri dell'API.

Valori denominati nel portale di Azure

Tipi valore

Tipo Descrizione
Pianura 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 semplici 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 di valore denominati, vedere le informazioni di riferimento sull'API REST Gestione API.

Segreti dell'insieme di credenziali delle chiavi

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é consente di migliorare Gestione API sicurezza:

  • I segreti archiviati negli insiemi di credenziali delle chiavi possono essere riutilizzati tra i servizi
  • I criteri di accesso granulare possono essere applicati 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 valore 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

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

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 l'accesso al controllo degli accessi in base al ruolo di Azure per un'identità gestita Gestione API.

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

    1. Nel menu a sinistra selezionare Criteri di accesso.
    2. Nella pagina Criteri di accesso selezionare + Crea.
    3. Nella scheda Autorizzazioni , in Autorizzazioni segrete selezionare Recupera ed Elenco, quindi selezionare Avanti.
    4. Nella scheda Entitàselezionare l'entità, cercare il nome della risorsa dell'identità gestita e quindi selezionare Avanti. 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 Key Vault Utente segreti.
    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 Verifica e assegna.

Requisiti per Key Vault firewall

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

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

  • In Key Vault firewall abilitare l'opzione Consenti ai servizi Microsoft attendibili di ignorare questa opzione del 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 ad Azure Gestione API. 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 dell'insieme di credenziali delle chiavi.

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 Gestione API.
  • Configurare una regola del gruppo di sicurezza di rete per consentire il traffico in uscita verso i tag del servizio AzureKeyVault e AzureActiveDirectory.

Per informazioni dettagliate, vedere Configurazione di rete durante la configurazione di Azure 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 dall'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 un identificatore del segreto dell'insieme di credenziali delle chiavi manualmente, 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 un'identità gestita assegnata dall'utente esistente. Informazioni su come aggiungere o modificare le identità gestite nel servizio Gestione API.

    Nota

    L'identità necessita delle autorizzazioni per ottenere ed elencare i segreti dall'insieme di credenziali delle chiavi. Se l'accesso all'insieme di credenziali delle chiavi non è già stato configurato, 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 salva.

  8. Selezionare Crea.

    Aggiungere il valore del segreto dell'insieme di credenziali delle chiavi

Aggiungere un valore normale o segreto a Gestione API

  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 Segreto.
  5. In Valore immettere una stringa o un'espressione di criteri.
  6. Aggiungere uno o più tag facoltativi per organizzare i valori denominati, quindi 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 al valore denominato vengono aggiornati automaticamente per usare il nuovo nome visualizzato.

Usare un valore denominato

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

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

Per usare un valore denominato in un criterio, inserire il nome visualizzato all'interno di una coppia doppia di parentesi graffe come {{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 con il relativo valore , @(DateTime.Now.ToString()). Poiché il valore è un'espressione di criteri, l'espressione viene valutata e il criterio passa alla fase di esecuzione.

È possibile testarlo nel portale di Azure o nel portale per sviluppatori chiamando un'operazione con criteri con valori denominati nell'ambito. Nell'esempio seguente viene chiamata un'operazione che contiene i due criteri di esempio precedenti set-header con valori denominati. Si noti che la risposta contiene due intestazioni personalizzate configurate usando criteri con valori denominati.

Testare la risposta dell'API

Se si esamina la traccia dell'API in uscita per una chiamata che include i due criteri di esempio precedenti con valori denominati, è possibile visualizzare i due set-header criteri con i valori denominati inseriti, nonché la valutazione dell'espressione dei criteri per il valore denominato che conteneva l'espressione criteri.

Traccia di Controllo API

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 di 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 la 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 il valore denominato viene fatto riferimento da qualsiasi criterio di Gestione API, non è possibile eliminarlo finché non si rimuove il valore denominato da tutti i criteri che lo usano.

Passaggi successivi