Esercitazione: trasformare e proteggere l'API

Articolo
01/03/2025

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.

Ad esempio, è possibile impostare un'intestazione di risposta personalizzata. In alternativa, proteggere l'API back-end configurando un criterio di limite di frequenza, in modo che l'API non venga usata dagli sviluppatori. 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 un criterio per il limite di frequenza (limitazione delle richieste)
Testare le trasformazioni

Prerequisiti

Acquisire familiarità con la terminologia di Gestione API di Azure.
Comprendere il concetto di criteri in Gestione API di Azure.
Completare la guida introduttiva seguente: Creare un'istanza di Gestione API di Azure. Per questa esercitazione, è consigliabile usare uno dei livelli classici o v2, ad esempio il livello Developer o il livello Basic v2. Il livello Consumo non supporta tutti i criteri usati in questa esercitazione.
Completare anche l'esercitazione seguente: Importare e pubblicare la prima API.

Passare all'istanza di Gestione API

Nel portale di Azure cercare e selezionare Servizi Gestione API.
Nella pagina Servizi Gestione API selezionare l'istanza di Gestione API.

Testare la risposta originale

Per visualizzare la risposta originale:

Nell'istanza del servizio Gestione API, selezionare API.
Selezionare Swagger Petstore nell'elenco delle API.
Selezionare la scheda Test nella parte superiore della schermata.
Selezionare l'operazione GET Trova animali domestici per stato e, facoltativamente, selezionare un valore diverso del parametro query di stato. Selezionare Invia.

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

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.

Selezionare Swagger Petstore>Design>All operations (Progettazione tutte le operazioni).
Nella sezione Elaborazione in uscita selezionare + Aggiungi criterio.
Nella finestra Aggiungi criteri in uscita selezionare Imposta intestazioni.
Per configurare i criteri di impostazione delle intestazioni, eseguire le operazioni seguenti:
1. In Nome immettere Personalizzato.
2. In Valore selezionare + Aggiungi valore. Immettere "My custom value" (Il mio valore personalizzato).
3. Seleziona Salva.
Dopo la configurazione, nella sezione Elaborazione in uscita viene visualizzato un elemento dei criteri set-header.

Proteggere un'API aggiungendo criteri relativi ai limiti di frequenza (limitazione delle richieste)

Questa sezione illustra come aggiungere protezione all'API back-end configurando limiti di velocità, in modo che l'API non venga usata eccessivamente dagli sviluppatori. 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 Consumo.

Selezionare Swagger Petstore>Design>All operations (Progettazione tutte le operazioni).
Nella sezione Elaborazione in ingresso selezionare l'icona dell'editor di codice (</>).
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.
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.
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

Selezionare Swagger Petstore>Test.
Selezionare l'operazione GET Trova animali domestici per stato e, facoltativamente, selezionare un valore diverso del parametro query di stato. Selezionare Invia.

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

Testare il limite di frequenza (limitazione delle richieste)

Selezionare Swagger Petstore>Test.
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 .
Attendere 15 secondi o più e quindi selezionare di nuovo Invia. Questa volta verrà visualizzata una risposta 200 OK.

Riepilogo

Questa esercitazione ha descritto come:

Trasformare un'API per impostare un'intestazione di risposta personalizzata
Proteggere un'API aggiungendo un criterio per il limite di frequenza (limitazione delle richieste)
Testare le trasformazioni

Passaggi successivi

Passare all'esercitazione successiva:

Monitorare l'API

Condividi tramite