Condividi tramite

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

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

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

Screenshot che mostra il controllo API.

Prerequisiti

Importante

  • Gestione API non supporta più le sottoscrizioni per la traccia o Intestazione Ocp-Apim-Trace.
  • Per migliorare la sicurezza dell'API, la traccia può ora essere abilitata a livello di 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 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

Seguire questa procedura per tracciare una richiesta API nella console di test nel portale. Questo esempio presuppone che sia stata importata un'API di esempio in un'esercitazione precedente. È possibile seguire passaggi simili con un'API diversa importata.

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

  2. Selezionare API>.

  3. Selezionare Petstore API nell'elenco delle API.

  4. Selezionare la scheda Test.

  5. Selezionare l'operazione Trova animale domestico per ID .

  6. Nel parametro petId Query immettere 1.

  7. 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.

  8. Selezionare Traccia.

Rivedere le informazioni di traccia

  1. Al termine della chiamata, passare alla scheda Tracia nella Risposta HTTP.

  2. Selezionare uno dei collegamenti seguenti per visualizzare informazioni di traccia dettagliate: inbound, back-end, outbound, In caso di errore.

    Rivedere la traccia della risposta

    • 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, vengono 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

I passaggi generali seguenti sono necessari per abilitare la traccia per una richiesta di Gestione API quando si usa curl, un client REST come Visual Studio Code con l'estensione client REST o un'app client. Attualmente questi passaggi devono essere seguiti usando l'API REST Gestione API:

  1. Ottenere le credenziali del token per la traccia.
  2. Aggiungere il valore del token in un'intestazione Apim-Debug-Authorization di richiesta al gateway Gestione API.
  3. Ottenere un ID di traccia nell'intestazione della Apim-Trace-Id risposta.
  4. Recuperare la traccia corrispondente all'ID di traccia.

Seguire i passaggi dettagliati.

Nota

  • Questi passaggi richiedono Gestione API'API REST 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.
  • Per informazioni sull'autenticazione all'API REST, vedere Informazioni di riferimento sull'API REST di Azure.

  1. Ottenere le credenziali del token: chiamare l'API List debug credentials (Elenco credenziali di debug) del gateway Gestione API. Nell'URI immettere "managed" per il gateway gestito dell'istanza nel cloud o l'ID del gateway per un gateway self-hosted. Ad esempio, per ottenere le credenziali di traccia per il gateway gestito dell'istanza, usare una richiesta 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. Ad esempio:

    {
    "credentialsExpireAfter": PT1H,
    "apiId": ""/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/apis/{apiName}",
    "purposes": ["tracing"]
}

    La credenziale del token viene restituita nella risposta, in modo analogo al seguente:

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

  2. Aggiungere il valore del token in un'intestazione di richiesta: 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 Petstore importata in un'esercitazione precedente, è possibile usare una richiesta simile alla seguente:

    curl -v https://apim-hello-world.azure-api.net/pet/1 HTTP/1.1 -H "Ocp-Apim-Subscription-Key: <subscription-key>" -H "Apim-Debug-Authorization: aid=api-name&......."

  3. A seconda del token, la risposta contiene una delle intestazioni seguenti:

    • Se il token è valido, la risposta include un'intestazione Apim-Trace-Id il cui valore è l'ID traccia, simile al seguente:

      Apim-Trace-Id: 0123456789abcdef....

    • 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 diversa, la risposta include un'intestazione Apim-Debug-Authorization-WrongAPI con un messaggio di errore.

  4. Recuperare la traccia: passare l'ID di traccia ottenuto nel passaggio precedente all'API di traccia elenco del gateway. Ad esempio, per recuperare la traccia per il gateway gestito, usare una richiesta 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": "0123456789abcdef...."
}

    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 nella console di test
  • Rivedere i passaggi di elaborazione delle richieste
  • Abilitare la traccia per un'API

Passare all'esercitazione successiva:

Usare le revisioni