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 di criteri è un documento XML che descrive una sequenza di istruzioni in ingresso e in uscita eseguite in sequenza su una richiesta e una risposta 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 un criterio usando due opzioni nell'editor dei criteri nel portale:

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

In questo esempio, i criteri filtrano le richieste da determinati indirizzi IP in ingresso. L'ambito è un'API selezionata.

Nota

È possibile configurare 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 criteri in ingresso selezionare un criterio da aggiungere. Ad esempio, selezionare Filtra indirizzi IP.

   

   Suggerimento

   • I criteri visualizzati sono limitati alla sezione dei 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 e verrà visualizzato 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 Gestione API.

   I criteri di filtro ip vengono ora visualizzati 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 </> (editor di codice).

   

6. Per visualizzare i frammenti di codice XML dei criteri disponibili, selezionare Mostra frammenti di codice. Ad esempio, selezionare Limita indirizzi IP chiamante.

   

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

   <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 di un criterio e gli elementi figlio nell'ordine specificato nell'istruzione dei criteri.

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

   I criteri di filtro ip vengono ora visualizzati nella sezione Elaborazione in ingresso.

Configurare i criteri in ambiti diversi

Gestione API offre flessibilità per configurare le definizioni dei criteri in più ambiti, in ognuna delle sezioni dei criteri.

Importante

Non tutti i criteri possono essere applicati a ogni ambito o sezione dei criteri. Se i criteri da aggiungere non sono abilitati, assicurarsi di essere inclusi in una sezione dei criteri supportata e nell'ambito di tale criterio. Per esaminare le sezioni e gli ambiti dei criteri per un criterio, vedere la sezione Utilizzo negli argomenti di riferimento sui criteri.

Nota

La sezione Criteri back-end può contenere solo un elemento criteri. Per impostazione predefinita, Gestione API configura i forward-request criteri nella sezione Back-end 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 sinistro dell'istanza di Gestione API selezionare API Tutte le>API.

2. Selezionare la scheda Progettazione.

   

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

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

Ambito del prodotto

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

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

2. Nella finestra del prodotto selezionare Criteri.

   

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

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

Ambito dell’API

L'ambito 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 applicare i criteri.

2. Selezionare la scheda Progettazione.

3. Selezionare Tutte le operazioni.

   

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

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

Ambito dell'operazione

L'ambito dell'operazione è configurato per un'operazione 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 desidera applicare i criteri.

   

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

5. Selezionare Salva per propagare immediatamente le modifiche al gateway 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 ritipare codice XML.

Usare i include-fragment criteri 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 definizioni di criteri in più ambiti, più criteri possono essere applicati a una richiesta o una risposta API. 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 più ampio (padre). L'elemento base è incluso per impostazione predefinita in ogni sezione dei criteri.

Nota

Per visualizzare i criteri effettivi nell'ambito corrente, selezionare Calcola criteri effettivi nell'editor dei criteri.

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

1. Iniziare con la definizione nell'ambito più ristretto configurato, che Gestione API verrà applicato per primo.

   Ad esempio, quando si usano definizioni di criteri configurate nell'ambito globale e nell'ambito API, iniziare con la configurazione nell'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 inbound sezione configurata nell'ambito dell'API posizionare un base elemento per controllare dove ereditare i criteri configurati nella inbound sezione nell'ambito globale. Nell'esempio seguente i criteri ereditati dall'ambito globale vengono applicati prima del ip-filter criterio.

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

   Un criterio con ambito globale non ha un ambito padre e l'uso dell'elemento base in non ha alcun effetto.

Ottenere assistenza per la creazione di criteri con Microsoft Copilot per Azure (anteprima)

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

È possibile richiedere a Copilot per 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

Importante

Microsoft Copilot per Azure (anteprima) richiede la registrazione e attualmente è disponibile solo per i clienti e i partner aziendali approvati. Per altre informazioni, vedere Accesso limitato a Microsoft Copilot per Azure (anteprima).

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 con Microsoft Copilot per Azure