Condividi tramite

Criteri in Gestione API di Azure

  • Articolo

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. 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 50 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 di chiamata 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. Mentre il gateway riceve le richieste e le inoltra, invariate, 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 istruzioni di criteri specificate viene eseguita in ordine per una richiesta e una risposta.

<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 is 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:

  • Esaminare l'errore usando la proprietà context.LastError.
  • Esaminare e personalizzare la risposta di errore usando il criterio di set-body.
  • 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 è:

  • un'unica istruzione C# racchiusa in @(expression), o
  • un 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, dalla più ampia alla più stretta:

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

Ambiti dei criteri

Informazioni utili

  • Per un controllo granulare per diversi consumer di API, è possibile configurare le definizioni dei criteri in più ambiti

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

  • 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 viene configurato usando 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, Cosmos DB o le origini dati SQL di Azure. Ad esempio, configurare un singolo criterio http-data-source 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. Non eredita anche i criteri configurati in altri ambiti.
  • Il gateway valuta un criterio con ambito resolver dopo i criteri inbound e backend configurati nella pipeline di esecuzione dei criteri.

Per altre informazioni, vedere Configurare un resolver GraphQL.

Ottenere assistenza nell'ambito della creazione di criteri con Microsoft Copilot in Azure (anteprima)

Microsoft Copilot in Azure (anteprima) offre funzionalità di creazione di criteri per Gestione API di Azure. Usare Copilot in Azure nel contesto dell'editor dei criteri di Gestione API per creare criteri che soddisfino i requisiti specifici senza conoscere la sintassi o farsi spiegare i criteri già configurati.

È possibile richiedere a Copilot in Azure di generare definizioni di criteri, quindi copiare i risultati nell'editor dei criteri e apportare eventuali modifiche necessarie. Porre domande per ottenere informazioni dettagliate su diverse opzioni, modificare i criteri forniti o chiarire i criteri già disponibili. Ulteriori informazioni

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:

  • L'istruzione cross-domain verrà eseguita per prima.
  • I criteri find-and-replace vengono eseguiti dopo qualsiasi criterio 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. Né i criteri di ambito globale né del prodotto verranno applicati.

Usare espressioni di criteri per modificare le richieste

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

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