Condividi tramite

Criteri in Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

In Gestione API di Azure gli autori delle API possono modificare il comportamento dell'API tramite la configurazione usando i criteri. Questo articolo descrive come usare i criteri.

I criteri sono una raccolta di istruzioni che vengono eseguite in sequenza sulla richiesta o sulla risposta di un'API. Gestione API offre più di 75 criteri predefiniti che è possibile configurare per gestire scenari API comuni, ad esempio l'autenticazione, la limitazione della frequenza, la memorizzazione nella cache e la trasformazione di richieste o risposte. Per un elenco completo, vedere Riferimento ai criteri di Gestione API.

I criteri più diffusi includono:

  • Conversione del formato da XML a JSON.
  • Limitazione della frequenza delle chiamate per limitare il numero di chiamate in arrivo da uno sviluppatore.
  • Filtro delle richieste provenienti da determinati indirizzi IP.

I criteri vengono applicati all'interno del gateway tra il consumer di API e l'API gestita. Anche se il gateway riceve le richieste e le inoltra, senza modifiche, all'API sottostante, un criterio può applicare modifiche sia alla richiesta in ingresso che alla risposta in uscita.

Informazioni sulla configurazione dei criteri

Le definizioni dei criteri sono semplici documenti XML che descrivono una sequenza di istruzioni da applicare alle richieste e alle risposte. Per configurare le definizioni dei criteri, il portale offre queste opzioni:

  • Editor guidato basato su moduli per semplificare la configurazione di criteri comuni senza codificare XML
  • Editor di codice in cui è possibile inserire frammenti XML o modificare direttamente XML

Per altre informazioni sulla configurazione dei criteri, vedere Impostare o modificare i criteri.

La configurazione XML dei criteri è suddivisa in sezioni inbound, backend, outbound e on-error. Questa serie di dichiarazioni di politiche specificate viene eseguita in sequenza per una richiesta e una risposta. Ecco come appare:

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there's an error condition go here -->
  </on-error>
</policies>

Per esempi xml dei criteri, vedere repository dei frammenti di criteri di Gestione API.

Gestione degli errori

Se si verifica un errore durante l'elaborazione di una richiesta:

  • Tutti i passaggi rimanenti nelle sezioni inbound, backendo outbound vengono ignorati.
  • L'esecuzione passa alle istruzioni nella sezione on-error.

Inserendo le istruzioni dei criteri nella sezione on-error, è possibile:

  • Rivedere l'errore usando la proprietà context.LastError.
  • Esaminare e personalizzare la risposta di errore usando i set-body criteri.
  • Configurare ciò che accade se si verifica un errore.

Per altre informazioni, vedere Gestione degli errori nei criteri di Gestione API.

Espressioni di criteri

A meno che il criterio non specifichi diversamente, le espressioni di criteri possono essere usate come valori di attributo o valori di testo in uno dei criteri di Gestione API. Un'espressione di criteri è una delle seguenti:

  • Una singola istruzione C# racchiusa in @(expression)
  • Blocco di codice C# con più istruzioni, racchiuso in @{expression}, che restituisce un valore

Ogni espressione ha accesso alla variabile context fornita esplicitamente e a un subset consentito di tipi .NET Framework.

Le espressioni di criteri offrono un mezzo sofisticato per controllare il traffico e modificare il comportamento dell'API senza richiedere di scrivere codice specializzato o modificare i servizi back-end. Alcuni criteri sono basati su espressioni di criteri, ad esempio flusso di controllo e Imposta variabile.

Ambiti

Gestione API consente di definire i criteri negli ambiti seguenti, presentati qui dal più ampio al più stretto:

  • Globale (tutte le API)
  • Area di lavoro (tutte le API associate a un'area di lavoro selezionata)
  • Prodotto (tutte le API associate a un prodotto selezionato)
  • API (tutte le operazioni in un'API)
  • Operazione (singola operazione in un'API)

Quando si configura un criterio, è prima necessario selezionare l'ambito in cui si applicano i criteri.

Diagramma che illustra i cinque ambiti dei criteri.

Informazioni utili

  • Per un controllo con granularità fine per diversi consumer di API, è possibile configurare le definizioni dei criteri in più ambiti.

  • Non tutti i criteri sono supportati in ogni ambito e sezione dei criteri.

  • Quando si configurano definizioni di criteri in più ambiti, è possibile controllare l'ereditarietà dei criteri e l'ordine di valutazione dei criteri in ogni sezione dei criteri posizionando l'elemento base .

  • I criteri applicati alle richieste API sono interessati anche dal contesto della richiesta, inclusa la presenza o l'assenza di una chiave di sottoscrizione usata nella richiesta, l'ambito API o prodotto della chiave di sottoscrizione e se l'API o il prodotto richiede una sottoscrizione.

    Nota

    Se si usa una sottoscrizione con ambito API, una sottoscrizione all-API o la sottoscrizione predefinita all-access, i criteri configurati nell'ambito del prodotto non vengono applicati alle richieste da tale sottoscrizione.

Per altre informazioni, vedi:

Criteri del resolver GraphQL

In Gestione API un resolver GraphQL è configurato con criteri con ambito per un tipo di operazione e un campo specifici in uno schema GraphQL.

  • Gestione API supporta attualmente i resolver GraphQL che specificano l'API HTTP, Azure Cosmos DB o le origini dati SQL di Azure. Ad esempio, è possibile configurare un singolo http-data-source criterio con elementi per specificare una richiesta a (e facoltativamente risposta da) un'origine dati HTTP.
  • Non è possibile includere un criterio resolver nelle definizioni dei criteri in altri ambiti, ad esempio API, prodotto o tutte le API. La politica non eredita neanche le politiche configurate in altri ambiti.
  • Il gateway valuta un criterio con ambito resolver dopo tutti i criteri configurati inbound e backend nella pipeline di esecuzione dei criteri.

Per altre informazioni, vedere Configurare un resolver GraphQL.

Ricevere assistenza da Copilot

È possibile ottenere assistenza per l'intelligenza artificiale da Copilot per creare e modificare le definizioni dei criteri di Gestione API. È possibile usare Copilot per creare e aggiornare criteri che soddisfano i requisiti specifici senza dover conoscere la sintassi XML. È anche possibile ottenere spiegazioni dei criteri esistenti. Copilot può anche aiutare a tradurre i criteri configurati in altre soluzioni di gestione API.

Richiesta di esempio:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot è alimentato dall'IA, quindi sono possibili sorprese ed errori. Per altre informazioni, vedere Domande frequenti sull'uso generale di Copilot.

Esempi

Applicare i criteri specificati in ambiti diversi

Se si dispone di un criterio a livello globale e di un criterio configurato per un'API, possono essere applicati entrambi i criteri ogni volta che viene usata l'API specifica. Gestione API consente l'ordinamento deterministico delle istruzioni di criteri combinate tramite l'elemento base.

Definizione di criteri di esempio nell'ambito dell'API:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

Nella definizione di criteri di esempio precedente:

  • La dichiarazione cross-domain viene eseguita per prima.
  • La find-and-replace politica viene eseguita dopo qualsiasi politica in un ambito più ampio.

Nota

Se si rimuove l'elemento base nell'ambito dell'API, verranno applicati solo i criteri configurati nell'ambito dell'API. I criteri configurati per i prodotti e gli ambiti più ampi non verranno applicati.

Usare espressioni di criteri per modificare le richieste

L'esempio seguente usa espressioni di criteri e criteri set-header per aggiungere dati utente alle richieste in ingresso. L'intestazione aggiunta include l'ID utente associato alla chiave di sottoscrizione nella richiesta e l'area in cui il gateway elabora la richiesta è ospitato.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere: