Esercitazione: Eseguire il debug delle API usando la traccia delle richieste

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

Questa esercitazione descrive come esaminare l'elaborazione delle richieste (traccia) in Azure Gestione API. La traccia consente di eseguire il debug e risolvere i problemi dell'API.

In questa esercitazione apprenderai a:

• Tracciare una chiamata di esempio nella console di test
• Rivedere i passaggi di elaborazione delle richieste
• Abilitare la traccia per un'API

Nota

Attualmente, la traccia delle richieste API non è supportata nei livelli Basic v2 e Standard v2.

Prerequisiti

• Acquisire familiarità con la terminologia di Gestione API di Azure.
• Completare la guida introduttiva seguente: Creare un'istanza di Gestione API di Azure.
• Completare l'esercitazione seguente: Importare e pubblicare la prima API.

Importante

• Gestione API la traccia delle richieste non può più essere abilitata impostando Intestazione Ocp-Apim-Trace in una richiesta e usando il valore dell'intestazione Ocp-Apim-Trace-Location nella risposta per recuperare la traccia.
• Per migliorare la sicurezza, la traccia è ora abilitata a livello di una singola API ottenendo un token limitato a tempo usando l'API REST Gestione API e passando il token in una richiesta al gateway. Per informazioni dettagliate, vedere più avanti in questa esercitazione.
• Prestare attenzione quando si abilita la traccia, in quanto può esporre informazioni riservate nei dati di traccia. Assicurarsi di disporre di misure di sicurezza appropriate per proteggere i dati di traccia.

Tracciare una chiamata nel portale

1. Accedere al portale di Azure e passare all'istanza di Gestione API.

2. Selezionare API.

3. Fare clic su Demo Conference API nell'elenco di API.

4. Selezionare la scheda Test.

5. Selezionare l'operazione GetSpeakers.

6. Facoltativamente, controllare il valore dell'intestazione Ocp-Apim-Subscription-Key usata nella richiesta selezionando l'icona "occhio".

   Suggerimento

   È possibile eseguire l'override del valore di Ocp-Apim-Subscription-Key recuperando una chiave per un'altra sottoscrizione nel portale. Selezionare Sottoscrizioni e aprire il menu di scelta rapida (...) per un'altra sottoscrizione. Selezionare Mostra/Nascondi chiavi e copiare una delle chiavi. Se necessario, è possibile rigenerare le chiavi. Nella console di test selezionare quindi + Aggiungi intestazione per aggiungere un'intestazioneOcp-Apim-Subscription-Key con il nuovo valore della chiave.

7. Selezionare Traccia.

Rivedere le informazioni di traccia

1. Al termine della chiamata, passare alla scheda Traccia nella risposta HTTP.

2. Selezionare uno dei collegamenti seguenti per passare a informazioni di traccia dettagliate: Inbound, Backend, Outbound, On error( Inbound, Outbound, On error).

   

   • In ingresso: mostra la richiesta originale che Gestione API ha ricevuto dal chiamante e i criteri applicati alla richiesta. Ad esempio, se sono stati aggiunti criteri in Esercitazione: Trasformare e proteggere l'API, verranno visualizzati qui.

   • Back-end: mostra le richieste che Gestione API ha inviato al back-end dell'API e la risposta che ha ricevuto.

   • In uscita: mostra tutti i criteri applicati alla risposta prima di restituirla al chiamante.

   • In caso di errore : mostra gli errori che si sono verificati durante l'elaborazione della richiesta e i criteri applicati agli errori.

   Suggerimento

   Ogni passaggio mostra inoltre il tempo trascorso da quando la richiesta è stata ricevuta da Gestione API.

Abilitare la traccia per un'API

È possibile abilitare la traccia per un'API quando si effettuano richieste di Gestione API usando curl, un client REST come Visual Studio Code con l'estensione client REST o un'app client.

Abilitare la traccia seguendo questa procedura usando le chiamate all'API REST Gestione API.

Nota

La procedura seguente richiede Gestione API API REST versione 2023-05-01-preview o successiva. È necessario assegnare il ruolo Collaboratore o superiore nell'istanza di Gestione API per chiamare l'API REST.

1. Ottenere le credenziali di traccia chiamando l'API List debug credentials (Elenco credenziali di debug). Passare l'ID del gateway nell'URI o usare "gestito" per il gateway gestito dell'istanza nel cloud. Ad esempio, per ottenere le credenziali di traccia per il gateway gestito, usare una chiamata simile alla seguente:

   POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
   

   Nel corpo della richiesta passare l'ID risorsa completo dell'API da tracciare e specificare purposes come tracing. Per impostazione predefinita, le credenziali del token restituite nella risposta scadono dopo 1 ora, ma è possibile specificare un valore diverso nel payload.

   {
       "credentialsExpireAfter": PT1H,
       "apiId": "<API resource ID>",
       "purposes: ["tracing"]
   }
   

   La credenziale del token viene restituita nella risposta, simile alla seguente:

   {
         "token": "aid=api-name&p=tracing&ex=......."
   }
   

2. Per abilitare la traccia per una richiesta al gateway Gestione API, inviare il valore del token in un'intestazioneApim-Debug-Authorization. Ad esempio, per tracciare una chiamata all'API conferenza demo, usare una chiamata simile alla seguente:

   curl -v GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&p=tracing&ex=......."
   

3. A seconda del token, la risposta contiene intestazioni diverse:

   • Se il token è valido, la risposta include un'intestazione Apim-Trace-Id il cui valore è l'ID traccia.
   • Se il token è scaduto, la risposta include un'intestazione Apim-Debug-Authorization-Expired con informazioni sulla data di scadenza.
   • Se il token è stato ottenuto per un'API errata, la risposta include un'intestazione Apim-Debug-Authorization-WrongAPI con un messaggio di errore.

4. Per recuperare la traccia, passare l'ID di traccia ottenuto nel passaggio precedente all'API di traccia elenco per il gateway. Ad esempio, per recuperare la traccia per il gateway gestito, usare una chiamata simile alla seguente:

   POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/managed/listTrace?api-version=2023-05-01-preview
   

   Nel corpo della richiesta passare l'ID di traccia ottenuto nel passaggio precedente.

   {
       "traceId": "<trace ID>"
   }
   

   Il corpo della risposta contiene i dati di traccia per la richiesta API precedente al gateway. La traccia è simile alla traccia che è possibile visualizzare tracciando una chiamata nella console di test del portale.

Per informazioni sulla personalizzazione delle informazioni di traccia, vedere i criteri di traccia .

Passaggi successivi

Questa esercitazione ha descritto come:

• Tracciare una chiamata di esempio
• Rivedere i passaggi di elaborazione delle richieste
• Abilitare la traccia per un'API

Passare all'esercitazione successiva:

Usare le revisioni