Come impostare o modificare i criteri di Gestione API di Azure

SI APPLICA A: tutti i livelli di Gestione API

Questo articolo illustra come configurare i criteri nell'istanza di Gestione API modificando le definizioni dei criteri nel portale di Azure. Ogni definizione dei criteri è un documento XML che descrive una sequenza di istruzioni in ingresso e in uscita eseguite in sequenza in una richiesta e risposta dell'API.

L'editor dei criteri nel portale fornisce moduli guidati per gli editori di API per aggiungere e modificare i criteri nelle definizioni dei criteri. È anche possibile modificare il codice XML direttamente nell'editor del codice dei criteri.

Ulteriori informazioni sui criteri:

• Panoramica dei criteri
• Informazioni di riferimento sui criteri per un elenco completo delle istruzioni dei criteri e delle relative impostazioni
• Repository dei frammenti di criteri
• Toolkit delle politiche della Gestione API di Azure
• Creare criteri usando Microsoft Copilot in Azure

Prerequisiti

Se non si ha già un'istanza di Gestione API e un'API back-end, vedere:

• Creare un'istanza di Gestione API di Azure
• Importare e pubblicare un'API

Passare all'istanza di Gestione API

1. Nel portale di Azure cercare e selezionare Servizi gestione API:

   

2. Nella pagina Servizi Gestione API selezionare l'istanza di Gestione API:

   

Configurare i criteri nel portale

L'esempio seguente illustra come configurare criteri usando due opzioni nell'editor dei criteri nel portale:

• Un editor guidato basato su moduli per semplificare la configurazione di molti criteri
• Un editor di codice in cui è possibile aggiungere o modificare direttamente il codice XML

In questo esempio, il criterio filtra le richieste da determinati indirizzi IP in ingresso. L'ambito è un'API selezionata.

Per configurare un criterio:

Configurare i criteri in ambiti diversi

Gestione API offre la flessibilità di configurare le definizioni dei criteri in più ambiti, in ognuna delle sezioni del criterio.

Ambito Globale

L'ambito globale è configurato per Tutte le API nell'istanza di Gestione API.

1. Nel riquadro di spostamento a sinistra dell'istanza di Gestione API selezionare API>Tutte le API.

2. Selezionare la scheda Progettazione.

   

3. In una sezione di criteri selezionare + Aggiungi criterio per usare un editor di criteri basato su moduli oppure selezionare l'icona </> (editor di codice) per aggiungere e modificare direttamente codice XML.

4. Selezionare Salva per propagare immediatamente le modifiche al gateway di Gestione API.

Ambito del prodotto

L'ambito del prodotto è configurato per un prodotto selezionato.

1. Nel menu a sinistra selezionare Prodottie quindi selezionare un prodotto a cui applicare i criteri.

2. Nella finestra del prodotto selezionare Criteri.

   

3. In una sezione di criteri selezionare + Aggiungi criterio per usare un editor di criteri basato su moduli oppure selezionare l'icona </> (editor di codice) per aggiungere e modificare direttamente codice XML.

4. Selezionare Salva per propagare immediatamente le modifiche al gateway di Gestione API.

Ambito dell’API

L'ambito dell'API è configurato per Tutte le operazioni dell'API selezionata.

1. Nel riquadro di spostamento a sinistra dell'istanza di Gestione API selezionare API e quindi selezionare l'API a cui si vogliono applicare criteri.

2. Selezionare la scheda Progettazione.

3. Selezionare Tutte le operazioni.

   

4. In una sezione di criteri selezionare + Aggiungi criterio per usare un editor di criteri basato su moduli oppure selezionare l'icona </> (editor di codice) per aggiungere e modificare direttamente codice XML.

5. Selezionare Salva per propagare immediatamente le modifiche al gateway di Gestione API.

Ambito dell'operazione

L'ambito dell'operazione è configurato per un'operazione dell'API selezionata.

1. Nel riquadro di spostamento a sinistra dell'istanza di Gestione API selezionare API.

2. Selezionare la scheda Progettazione.

3. Selezionare l'operazione a cui si vogliono applicare criteri.

   

4. In una sezione di criteri selezionare + Aggiungi criterio per usare un editor di criteri basato su moduli oppure selezionare l'icona </> (editor di codice) per aggiungere e modificare direttamente codice XML.

5. Selezionare Salva per propagare immediatamente le modifiche al gateway di Gestione API.

Riutilizzare le configurazioni dei criteri

È possibile creare frammenti di criteri riutilizzabili nell'istanza di Gestione API. I frammenti di criteri sono elementi XML contenenti le configurazioni di uno o più criteri. I frammenti di criteri consentono di configurare i criteri in modo coerente e gestire le definizioni dei criteri senza dover ripetere o ridigitare codice XML.

Usare il criterio include-fragment per inserire un frammento di criteri in una definizione di criteri.

Usare l'elemento base per impostare l'ordine di valutazione dei criteri

Se si configurano le definizioni di criteri in più ambiti, è possibile che a una richiesta o una risposta API siano applicati più criteri. A seconda dell'ordine in cui vengono applicati i criteri dei diversi ambiti, la trasformazione della richiesta o della risposta potrebbe differire.

In Gestione API determinare l'ordine di valutazione dei criteri posizionando l'elemento base in ogni sezione della definizione dei criteri in ogni ambito. L'elemento base eredita i criteri configurati in tale sezione nell'ambito successivo più ampio (padre). L'elemento base è incluso per impostazione predefinita in ogni sezione dei criteri.

Per modificare l'ordine di valutazione dei criteri usando l'editor dei criteri:

1. Iniziare con la definizione con l'ambito più ristretto che hai configurato, che verrà applicata per prima da API Management.

   Ad esempio, quando si usano definizioni di criteri configurate a livello di ambito globale e ambito dell'API, iniziare con la configurazione con ambito dell'API.

2. Posizionare l'elemento base all'interno di una sezione per determinare dove ereditare tutti i criteri dalla sezione corrispondente nell'ambito padre.

   Ad esempio, in una sezione inbound configurata nell'ambito dell'API posizionare un elemento base per controllare dove ereditare i criteri configurati nella sezione inbound nell'ambito globale. Nell'esempio seguente, i criteri ereditati dall'ambito globale vengono applicati prima del criterio ip-filter.

   <policies>
     <inbound>
         <base />
           <ip-filter action="allow">
               <address>10.100.7.1</address>
           </ip-filter>
     </inbound>
     [...]
   </policies>
   

   Nota

   • È possibile posizionare l'elemento base prima o dopo qualsiasi elemento dei criteri in una sezione.
   • Se si vuole impedire l'ereditarietà dei criteri dall'ambito padre, rimuovere l'elemento base. Nella maggior parte dei casi, questo non è consigliato. Tuttavia, può essere utile in determinate situazioni, ad esempio quando si vogliono applicare criteri diversi a un'operazione specifica rispetto a quelli configurati per l'ambito API (tutte le operazioni).

3. Continuare a configurare l'elemento base nelle definizioni dei criteri in ambiti più ampi.

   I criteri con ambito globale non hanno un ambito padre e l'uso al loro interno dell'elemento base non produce alcun effetto.

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

• Microsoft Copilot in Azure offre assistenza per la creazione di criteri con i prompt del linguaggio naturale nel portale di Azure. È possibile creare criteri nell'editor dei criteri di Gestione API e chiedere a Copilot di spiegare le sezioni dei criteri.
• GitHub Copilot per Azure in Visual Studio Code offre assistenza per la creazione di criteri in Visual Studio Code ed è possibile usare l'estensione Gestione API di Azure per Visual Studio Code per velocizzare la configurazione dei criteri. È possibile richiedere a Copilot Chat o Copilot Edits con il linguaggio naturale di creare e perfezionare le definizioni dei criteri.

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.

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere:

• Esercitazione: trasformare e proteggere l'API
• Informazioni di riferimento sui criteri per un elenco completo delle istruzioni dei criteri e delle relative impostazioni
• Espressioni di politica
• Modificare o impostare criteri
• Riutilizzare le configurazioni dei criteri
• Repository dei frammenti di criteri
• Repository del playground dei criteri
• Toolkit delle politiche della Gestione API di Azure
• Ottenere assistenza da Copilot per creare, spiegare e risolvere le politiche