Condividi tramite

Esercitazione: trasformare e proteggere l'API

SI APPLICA A: Tutti i livelli di Gestione API

In questa esercitazione vengono fornite informazioni sulla configurazione dei criteri per proteggere o trasformare l'API. I criteri sono una raccolta di istruzioni eseguite in sequenza nella richiesta o nella risposta di un'API che modifica il comportamento dell'API.

Suggerimento

I team API possono usare questa funzionalità nelle aree di lavoro. Le aree di lavoro forniscono accesso amministrativo isolato alle API e ai propri ambienti di runtime API.

Ad esempio, è possibile impostare un'intestazione di risposta personalizzata. In alternativa, configurare un criterio di limite di velocità per proteggere l'API back-end, in modo che gli sviluppatori non usino eccessivamente l'API. Questi esempi sono una semplice introduzione ai criteri di Gestione API. Per altre opzioni di criteri, vedere Criteri di API Management.

Nota

Per impostazione predefinita, API Management configura un criterio forward-request globale. Il criterio forward-request è necessario affinché il gateway completi una richiesta a un servizio back-end.

In questa esercitazione apprenderai a:

  • Trasformare un'API per impostare un'intestazione di risposta personalizzata
  • Proteggere un'API aggiungendo una politica di limitazione della velocità o throttling
  • Testare le trasformazioni

Screenshot dei criteri di Gestione API nel portale.

Prerequisiti

Passare all'istanza di Gestione API

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

    Screenshot che mostra i servizi gestione API nei risultati della ricerca.

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

    Screenshot che mostra un'istanza di Gestione API nella pagina Servizi Gestione API.

Testare la risposta originale

Per visualizzare la risposta originale:

  1. Nell'istanza del servizio Gestione API, selezionare API>API.
  2. Nell'elenco delle API selezionare Swagger Petstore.
  3. Nella parte superiore della schermata selezionare Test.
  4. Selezionare l'operazione GET Trova animali per stato e, facoltativamente, selezionare un valore diverso del parametro querydi stato.
  5. Selezionare Invia.

La risposta API originale avrà un aspetto simile al seguente:

Screenshot della risposta dell'API originale nel portale di Azure.

Trasformare un'API per aggiungere un'intestazione di risposta personalizzata

Gestione API include diversi criteri di trasformazione che è possibile usare per modificare payload di richiesta o risposta, intestazioni o codici di stato. In questo esempio viene impostata un'intestazione di risposta personalizzata nella risposta dell'API.

Impostare i criteri di trasformazione

Questa sezione illustra come configurare un'intestazione di risposta personalizzata usando i set-header criteri. Qui si usa un editor di criteri basato su form che semplifica la configurazione dei criteri.

  1. Selezionare Swagger Petstore>Progettazione>Tutte le operazioni.

  2. Nella sezione Elaborazione in uscita selezionare + Aggiungi criterio.

    Screenshot della navigazione ai criteri in uscita nel portale.

  3. Nella finestra Aggiungi criteri in uscita selezionare Imposta intestazioni.

    Screenshot della configurazione dei criteri di impostazione delle intestazioni nel portale.

  4. Per configurare la politica di impostazione delle intestazioni:

    1. In Nome immettere Personalizzato.
    2. In Valore selezionare + Aggiungi valore. Immettere Il valore personalizzato.
    3. Seleziona Salva.

    Dopo la configurazione, nella sezione Elaborazione in uscita viene visualizzato un elemento dei criteri set-header.

    Screenshot dei criteri in uscita di impostazione delle intestazioni nel portale.

Proteggere un'API aggiungendo criteri di limite di velocità

Questa sezione illustra come aggiungere protezione all'API back-end configurando i limiti di frequenza, in modo che gli sviluppatori non abusino dell'uso dell'API. In questo esempio viene illustrato come configurare i rate-limit-by-key criteri usando l'editor di codice. In questo esempio, il limite è impostato su tre chiamate per 15 secondi. Dopo 15 secondi, uno sviluppatore può ripetere la chiamata all'API.

Nota

Questo criterio non è supportato nel livello A consumo.

  1. Selezionare Swagger Petstore>Progettazione>Tutte le operazioni.

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

    Screenshot della navigazione nell'editor di codice del criterio in entrata nel portale.

  3. Posizionare il cursore all'interno dell'elemento <inbound> su una riga vuota. Selezionare quindi Mostra frammenti di codice nell'angolo in alto a destra della schermata.

    Screenshot della selezione dei frammenti da mostrare nell'editor dei criteri in entrata nel portale.

  4. Nella finestra a destra, in Criteri di restrizione dell'accesso selezionare + Limita frequenza delle chiamate per chiave.

    L'elemento <rate-limit-by-key /> viene aggiunto al cursore.

    Screenshot dell'inserimento del limite relativo alla frequenza delle chiamate per criterio chiave nel portale.

  5. Sostituire il codice <rate-limit-by-key /> nell'elemento <inbound> con il codice seguente. Quindi selezionare Salva.

    <rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />

Testare le trasformazioni

A questo punto, se si esamina il codice nell'editor di codice, i criteri sono simili al seguente codice:

<policies>
     <inbound>
         <rate-limit calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
         <base />
     </inbound>
     <outbound>
         <set-header name="Custom" exists-action="override">
             <value>"My custom value"</value>
           </set-header>
         <base />
     </outbound>
     <on-error>
         <base />
     </on-error>
 </policies>

La parte rimanente della sezione testa le trasformazioni dei criteri impostate in questo articolo.

Testare l'intestazione della risposta personalizzata

  1. Selezionare Swagger Petstore>Test.

  2. Selezionare l'operazione GET Trova animali per stato e, facoltativamente, selezionare un valore diverso del parametro di query dello stato. Selezionare Invia.

    Come si può notare, viene aggiunta l'intestazione della risposta personalizzata:

    Screenshot che mostra l'intestazione di risposta personalizzata nel portale.

Testare il limite di velocità

  1. Selezionare Swagger Petstore>Test.

  2. Selezionare l'operazione GET Trova animali domestici per stato . Selezionare Invia più volte in una riga.

    Dopo l'invio di troppe richieste nel periodo configurato, si ottiene la risposta 429 Troppe richieste .

    Screenshot che mostra Troppe richieste nella risposta nel portale.

  3. Attendere 15 secondi o più e quindi selezionare di nuovo Invia. Questa volta verrà visualizzata una risposta 200 OK.

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.

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

Riepilogo

In questo tutorial, hai imparato a:

  • Trasformare un'API per impostare un'intestazione di risposta personalizzata
  • Proteggere un'API aggiungendo un criterio di limite di velocità
  • Testare le trasformazioni

Passo successivo

Passare all'esercitazione successiva:

Monitorare l'API

  • Last updated on