Esercitazione: Usare l'estensione Azure Gestione API per Visual Studio Code per importare e gestire le API

SI APPLICA A: Consumo | Sviluppatore | Basic | Standard | Premium

Questa esercitazione illustra come usare l'estensione Gestione API per Visual Studio Code per operazioni comuni in Gestione API. Usare il noto ambiente Visual Studio Code per importare, aggiornare, testare e gestire le API.

Scopri come:

• Importare un'API in Gestione API
• Modificare l'API
• Applicare i criteri di Gestione API
• Testare l'API

Per un'introduzione a altre funzionalità Gestione API, vedere le esercitazioni Gestione API sull'uso del portale di Azure.

Prerequisiti

• Acquisire familiarità con la terminologia di Gestione API di Azure.
• Assicurarsi di aver installato Visual Studio Code e l'estensione azure Gestione API più recente per Visual Studio Code.
• Creare un'istanza di Gestione API.

Importare un'API

Nell'esempio seguente una specifica OpenAPI in formato JSON viene importata in Gestione API. Microsoft fornisce l'API back-end usata in questo esempio e la ospita in Azure all'indirizzo https://conferenceapi.azurewebsites.net.

1. In Visual Studio Code selezionare l'icona di Azure dalla barra attività.
2. Nel riquadro di Esplora risorse espandere l'istanza di Gestione API creata.
3. Fare clic con il pulsante destro del mouse su API e selezionare Import from OpenAPI Link (Importa da collegamento OpenAPI).
4. Quando richiesto, immettere i valori seguenti:

   1. Un collegamento OpenAPI per il contenuto in formato JSON. Per questo esempio: https://conferenceapi.azurewebsites.net?format=json.

      Questo file specifica il servizio back-end che implementa l'API di esempio, in questo caso https://conferenceapi.azurewebsites.net. Gestione API inoltra le richieste a questo servizio Web.

   2. Un nome di API, ad esempio demo-conference-api, univoca nell'istanza di Gestione API. Questo nome può contenere solo lettere, numeri e trattini. Il primo e l'ultimo carattere devono essere alfabetici o numerici. Questo nome viene usato nel percorso per chiamare l'API.

Dopo l'importazione, l'API viene visualizzata nel riquadro di Esplora risorse e le operazioni disponibili per le API vengono visualizzate nel nodo Operazioni.

Modificare l'API

È possibile modificare l'API in Visual Studio Code. Modificare ad esempio la descrizione JSON di Gestione risorse dell'API nella finestra dell'editor per rimuovere il protocollo http usato per accedere all'API.

Per modificare il formato OpenAPI, fare clic con il pulsante destro del mouse sul nome dell'API nel riquadro di Esplora risorse e selezionare Edit OpenAPI (Modifica OpenAPI). Apportare le modifiche necessarie e quindi selezionare File>Salva.

Applicare criteri all'API

Gestione API fornisce criteri che è possibile configurare per le API. I criteri sono una raccolta di istruzioni. Queste istruzioni vengono eseguite in sequenza nella richiesta o nella risposta di un'API. I criteri possono essere globali, che si applicano a tutte le API nell'istanza di Gestione API o specifiche di un prodotto, un'API o un'operazione API.

Questa sezione illustra come applicare criteri in uscita comuni all'API che trasformano la risposta dell'API. I criteri in questo esempio modificano le intestazioni della risposta e nascondono gli URL back-end originali visualizzati nel corpo della risposta.

1. Nel riquadro di Esplora risorse selezionare Criteri nell'API demo-conference-api importata. Il file dei criteri verrà aperto nella finestra dell'editor. Questo file consente di configurare i criteri per tutte le operazioni nell'API.

2. Aggiornare il file con il contenuto seguente nell'elemento <outbound>:

   [...]
   <outbound>
       <set-header name="Custom" exists-action="override">
           <value>"My custom value"</value>
       </set-header>
       <set-header name="X-Powered-By" exists-action="delete" />
       <redirect-content-urls />
       <base />
   </outbound>
   [...]
   

   • Il primo criterio set-header aggiunge un'intestazione della risposta personalizzata a scopo dimostrativo.
   • Il secondo criterio set-header elimina l'eventuale intestazione X-Powered-By esistente. Questa intestazione può rivelare il framework dell'applicazione usato nel back-end dell'API, di conseguenza spesso gli autori la rimuovono.
   • Il criterio redirect-content-urls riscrive (maschera) i collegamenti nel corpo della risposta, in modo che facciano riferimento ai collegamenti equivalenti tramite il gateway di Gestione API.

3. Salvare il file. Se richiesto, selezionare Carica per caricare il file nel cloud.

Testare l'API

Per testare l'API, ottenere una chiave di sottoscrizione e quindi inviare una richiesta al gateway Gestione API.

Recuperare la chiave di sottoscrizione

È necessaria una chiave di sottoscrizione per l'istanza di Gestione API per testare l'API importata e i criteri applicati.

1. Nel riquadro di Esplora risorse fare clic con il pulsante destro del mouse sul nome dell'istanza di Gestione API.

2. Selezionare Copy Subscription Key (Copia chiave di sottoscrizione). Questa chiave è per la sottoscrizione di accesso predefinita creata quando si crea un'istanza di Gestione API.

   

   Attenzione

   La sottoscrizione all-access consente l'accesso a ogni API in questa istanza di Gestione API e deve essere usata solo dagli utenti autorizzati. Non usarlo mai per l'accesso all'API di routine o incorporare la chiave all-access nelle app client.

Testare un'operazione API

1. Nel riquadro di Esplora risorse espandere il nodo Operazioni nell'API demo-conference-api importata.
2. Selezionare un'operazione, ad esempio GetSpeakers, quindi fare clic con il pulsante destro del mouse sull'operazione e scegliere Operazione di test.
3. Nella finestra dell'editor, accanto a Ocp-Apim-Subscription-Key, sostituire {{SubscriptionKey}} con la chiave di sottoscrizione copiata.
4. Selezionare Invia richiesta.

Quando la richiesta ha esito positivo, il back-end risponde con 200 OK e alcuni dati.

Notare i dettagli seguenti nella risposta:

• Alla risposta viene aggiunta l'intestazione Custom.
• L'intestazione X-Powered-By non viene visualizzata nella risposta.
• Gli URL dei back-end API vengono reindirizzati al gateway di Gestione API, in questo caso https://apim-hello-world.azure-api.net/demo-conference-api.

Elaborazione delle richieste di traccia

Facoltativamente, è possibile ottenere informazioni dettagliate sulla traccia delle richieste per semplificare il debug e la risoluzione dei problemi dell'API.

Per la procedura per abilitare la traccia per un'API, vedere Abilitare la traccia per un'API. Per limitare la divulgazione involontaria di informazioni riservate, la traccia per impostazione predefinita è consentita solo per 1 ora.

Pulire le risorse

Quando non è più necessaria, rimuovere l'istanza di Gestione API facendo clic con il pulsante destro del mouse e scegliendo Apri nel portale per eliminare il servizio Gestione API e il relativo gruppo di risorse.

In alternativa, è possibile selezionare Elimina Gestione API per eliminare solo l'istanza di Gestione API. Questa operazione non ne elimina il gruppo di risorse.

Contenuto correlato

Questa esercitazione ha introdotto diverse funzionalità dell'estensione Gestione API per Visual Studio Code. È possibile usare queste funzionalità per importare e gestire le API. Contenuto del modulo:

• Importare un'API in Gestione API
• Modificare l'API
• Applicare i criteri di Gestione API
• Testare l'API

L'estensione Gestione API offre altre funzionalità da usare con le API. Ad esempio, è possibile usare criteri di debug (disponibili nel livello di servizio per sviluppatori) oppure creare e gestire valori denominati.