Esercitazione: Eseguire il debug delle API usando la traccia delle richieste
SI APPLICA A: A consumo | Developer | Basic | Standard | Premium
Questa esercitazione descrive come esaminare l'elaborazione delle richieste (traccia) in Gestione API di Azure. 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
La traccia delle richieste dell'API non è attualmente 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
- Sarà presto deprecata la traccia delle richieste di Gestione API con l'intestazione Ocp-Apim-Trace in una richiesta e con il valore dell'intestazione di risposta Ocp-Apim-Trace-Location.
- Per migliorare la sicurezza, la traccia può ora essere abilitata a livello di una singola API ottenendo un token a tempo limitato tramite l'API REST Gestione API e passando il token in una richiesta al gateway. Per informazioni dettagliate, vedere Abilitare la traccia di un'API.
- Prestare attenzione quando si abilita la traccia, in quanto può esporre informazioni riservate nei dati di traccia. Assicurarsi di avere misure di sicurezza appropriate per proteggere i dati di traccia.
Tracciare una chiamata nel portale
Accedere al portale di Azure e passare all'istanza di Gestione API.
Selezionare API.
Fare clic su Demo Conference API nell'elenco di API.
Selezionare la scheda Test.
Selezionare l'operazione GetSpeakers.
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 + Aggiungi intestazione per aggiungere un'intestazione Ocp-Apim-Subscription-Key con il nuovo valore della chiave.
Selezionare Traccia.
Rivedere le informazioni di traccia
Al termine della chiamata, passare alla scheda Tracia nella Risposta HTTP.
Selezionare uno dei collegamenti seguenti per visualizzare informazioni di traccia dettagliate: inbound, back-end, outbound, In caso di errore.
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 a 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
I passaggi seguenti richiedono l'API REST Gestione API versione 2023-05-01-preview o successiva. Per chiamare l'API REST, è necessario avere il ruolo Collaboratore o un ruolo superiore nell'istanza di Gestione API.
Ottenere le credenziali di traccia chiamando l'API List debug credentials. Passare l'ID del gateway nell'URI o usare "managed" 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
cometracing
. Per impostazione predefinita, la credenziale del token restituita nella risposta scade 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, in modo analogo al seguente:
{ "token": "aid=api-name&p=tracing&ex=......." }
Per abilitare la traccia per una richiesta al gateway di Gestione API, inviare il valore del token in un'intestazione
Apim-Debug-Authorization
. Ad esempio, per tracciare una chiamata all'API Demo Conference, 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=......."
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 di 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.
- Se il token è valido, la risposta include un'intestazione
Per recuperare la traccia, passare l'ID di traccia ottenuto nel passaggio precedente all'API List trace 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 precedente dell'API 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 relativi alla 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: