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 codice dei criteri

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.

Nota

È possibile configurare i criteri in altri ambiti, ad esempio per tutte le API, un prodotto o una singola operazione API. Per altri esempi, vedere Configurare l'ambito più avanti in questo articolo.

Per configurare un criterio:

Modulo

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

2. Selezionare un'API importata in precedenza.

3. Selezionare la scheda Progettazione.

4. Per applicare il criterio a tutte le operazioni, selezionare Tutte le operazioni.

5. Nella sezione Elaborazione in ingresso selezionare Aggiungi criteri.

   

6. In Aggiungi criterio in ingresso selezionare un criterio da aggiungere. Ad esempio, selezionare Filtrare gli indirizzi IP.

   

   Suggerimento

   • I criteri visualizzati sono limitati alla sezione di criteri che si sta configurando, in questo caso per l'elaborazione in ingresso.
   • Se non viene visualizzato un criterio desiderato, selezionare il riquadro Altri criteri. Verrà aperto l'editor di codice XML con un elenco completo dei criteri per tale sezione e ambito.

7. Selezionare Indirizzi IP consentiti>+ Aggiungi filtro IP e aggiungere il primo e l'ultimo indirizzo IP di un intervallo di indirizzi in ingresso autorizzati a effettuare richieste API. Aggiungere altri intervalli di indirizzi IP, se necessario.

   

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

   Il criterio ip-filter viene ora visualizzato nella sezione Elaborazione in ingresso.

Codice

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

2. Selezionare un'API importata in precedenza.

3. Selezionare la scheda Progettazione.

4. Per applicare il criterio a tutte le operazioni, selezionare Tutte le operazioni.

5. Nella sezione Elaborazione in ingresso selezionare l'icona dell'editor di codice (</>).

   

6. Per visualizzare i frammenti di codice XML per i criteri disponibili, selezionare Mostra frammenti. Ad esempio, selezionare Limita IP chiamanti.

   

7. Incollare o immettere il frammento di codice di criteri desiderato in uno dei blocchi appropriati e completare la configurazione del criterio.

   <policies>
       <inbound>
           <base />
           <ip-filter action="allow">
               <address-range from="10.100.7.0" to="10.100.127.0" />
           </ip-filter>
       </inbound>
       <backend>
           <base />
       </backend>
       <outbound>
           <base />
       </outbound>
       <on-error>
           <base />
       </on-error>
   </policies>
   

   Nota

   Impostare gli elementi e gli elementi figlio del criterio nell'ordine specificato nell'istruzione del criterio.

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

   Il criterio ip-filter viene ora visualizzato nella sezione Elaborazione in ingresso.

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.

Importante

Non tutti i criteri sono supportati in ogni ambito o sezione di criteri. Se il criterio che si vuole aggiungere non è abilitato, verificare di essere in una sezione e in un ambito supportati per il criterio. Per esaminare le sezioni e gli ambiti di un criterio, vedere la sezione relativa all'Utilizzo nelle Informazioni di riferimento per i criteri.

Nota

La sezione di criteri Backend può contenere un solo elemento di criterio. Per impostazione predefinita, Gestione API configura il criterio forward-request nella sezione Backend nell'ambito globale e l'elemento base in altri ambiti.

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.

Nota

Per visualizzare i criteri validi nell'ambito corrente, selezionare Calcola criterio valido nell'editor 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 configurato, che Gestione API applicherà per primo.

   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.

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.

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

Contenuto correlato

Per ulteriori informazioni sull'utilizzo dei criteri, vedere:

• Esercitazione: Trasformare e proteggere le API
• Impostare o modificare criteri
• Informazioni di riferimento sui criteri per un elenco completo delle istruzioni dei criteri e delle relative impostazioni
• Repository dei frammenti di codice dei criteri
• Creare criteri usando Microsoft Copilot in Azure