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

Articolo
06/25/2024

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 come tracing. 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.
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:

Usare le revisioni

Condividi tramite