Tutorial: Debuggen von APIs mit der Anforderungsablaufverfolgung

GILT FÜR: Alle API Management-Ebenen

In diesem Tutorial wird beschrieben, wie Sie die Verarbeitung von Anforderungen in Azure API Management überprüfen (verfolgen) können. Die Ablaufverfolgung ermöglicht Ihnen das Debuggen und das Behandeln von Problemen mit Ihrer API.

In diesem Tutorial lernen Sie Folgendes:

Voraussetzungen

• Machen Sie sich mit der Azure API Management-Terminologie vertraut.
• Bearbeiten Sie den folgenden Schnellstart: Erstellen einer neuen Azure API Management-Dienstinstanz
• Absolvieren Sie das folgende Tutorial: Importieren und Veröffentlichen Ihrer ersten API.

Ablaufverfolgung eines Anrufs im Portal

Führen Sie die folgenden Schritte aus, um eine API-Anforderung in der Testkonsole im Portal nachzuverfolgen. In diesem Beispiel wird davon ausgegangen, dass Sie eine Beispiel-API in einem vorherigen Tutorial importiert haben. Sie können ähnliche Schritte mit einer anderen API ausführen, die Sie importiert haben.

1. Melden Sie sich beim Azure-Portal an, und navigieren Sie zu Ihrer API Management-Instanz.

2. Wählen Sie APIs>APIs aus.

3. Wählen Sie die Petstore-API aus Ihrer API-Liste aus.

4. Wählen Sie die Registerkarte Testen aus.

5. Wählen Sie den Vorgang Haustier nach ID suchen aus.

6. Geben Sie im Abfrageparameter petId 1 ein.

7. Überprüfen Sie optional den Wert für den in der Anforderung verwendeten Ocp-Apim-Subscription-Key-Header, indem Sie das Auge-Symbol auswählen.

   Tipp

   Sie können den Wert von Ocp-Apim-Subscription-Key außer Kraft setzen, indem Sie einen Schlüssel für ein anderes Abonnement im Portal abrufen. Wählen Sie Abonnements aus, und öffnen Sie das Kontextmenü (...) für ein anderes Abonnement. Wählen Sie Schlüssel anzeigen/ausblenden aus, und kopieren Sie einen der Schlüssel. Sie können Schlüssel bei Bedarf auch erneut generieren. Wählen Sie dann in der Testkonsole + Kopfzeile hinzufügen aus, um einen Ocp-Apim-Subscription-Key-Header mit dem neuen Schlüsselwert hinzuzufügen.

8. Wählen Sie Ablaufverfolgung aus.

Überprüfen der Ablaufverfolgungsinformationen

1. Navigieren Sie nach Abschluss des Aufrufs in der HTTP-Antwort zur Registerkarte Ablaufverfolgung.

2. Wählen Sie einen der folgenden Links aus, um ausführliche Informationen zur Ablaufverfolgung anzuzeigen: Eingehend, Back-End, Ausgehend, Bei Fehler.

   

   • Eingehend: Hier werden die ursprüngliche Anforderung, die API Management vom Aufrufer empfangen hat, sowie die auf die Anforderung angewendeten Richtlinien angezeigt. Wenn Sie beispielsweise Richtlinien im Tutorial: Transformieren und Schützen Ihrer API hinzugefügt haben, werden sie hier angezeigt.

   • Back-End: Hier werden die Anforderungen, die API Management an das API-Back-End gesendet hat, sowie die erhaltene Antwort angezeigt.

   • Ausgehend: Hier werden die Richtlinien angezeigt, die auf die Antwort angewendet werden, bevor sie zurück an den Aufrufer gesendet wird.

   • Bei Fehler: Zeigt die Fehler an, die während der Verarbeitung der Anforderung aufgetreten sind, sowie die auf die Fehler angewendeten Richtlinien.

   Tipp

   Jeder Schritt zeigt zudem die Zeit an, die verstrichen ist, seit die Anforderung von API Management empfangen wurde.

Aktivieren der Ablaufverfolgung für eine API

Die folgenden allgemeinen Schritte sind erforderlich, um die Ablaufverfolgung für eine Anforderung an API Management bei Verwendung von curl, eines REST-Clients wie Visual Studio Code mit der REST-Clienterweiterung oder einer Client-App zu aktivieren. Derzeit müssen diese Schritte mit der API Management-REST-API befolgt werden:

1. Abrufen einer Tokenanmeldeinformationen für die Ablaufverfolgung.
2. Fügen Sie den Tokenwert in einem Apim-Debug-Authorization-Anforderungsheader zum API Management-Gateway hinzu.
3. Rufen Sie eine Ablaufverfolgungs-ID im Apim-Trace-Id-Antwortheader ab.
4. Rufen Sie die Ablaufverfolgung ab, die der Ablaufverfolgungs-ID entspricht.

Die Schritte im Detail folgen.

1. Abrufen einer Tokenanmeldeinformation – Aufrufen der API des API Management-Gateways für Anmeldeinformationen zum Debuggen auflisten. Geben Sie im URI „verwaltet“ für das verwaltete Gateway der Instanz in der Cloud oder die Gateway-ID für ein selbst gehostetes Gateway ein. Um beispielsweise Anmeldeinformationen zur Ablaufverfolgung für die Instanz des verwalteten Gateways abzurufen, verwenden Sie eine Anforderung ähnlich der folgenden:

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

   Übergeben Sie im Anforderungstext die vollständige Ressourcen-ID der API, die Sie nachverfolgen möchten, und geben Sie purposes als tracing an. Standardmäßig laufen die in der Antwort zurückgegebenen Tokenanmeldeinformationen nach 1 Stunde ab, sie können jedoch einen anderen Wert in den Nutzdaten angeben. Zum Beispiel:

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

   Die Tokenanmeldeinformationen werden in der Antwort zurückgegeben, ähnlich dem folgenden Beispiel:

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

2. Fügen Sie den Tokenwert in einem Anforderungsheader hinzu: Um die Ablaufverfolgung für eine Anforderung an das API Management-Gateway zu aktivieren, senden Sie den Tokenwert in einem Apim-Debug-Authorization-Header. Um beispielsweise einen Aufruf der Petstore-API nachzuverfolgen, die Sie in einem vorherigen Tutorial importiert haben, können Sie eine Anforderung wie ähnlich der folgenden verwenden:

   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. Je nach Token enthält die Antwort einen der folgenden Header:

   • Wenn das Token gültig ist, enthält die Antwort einen Apim-Trace-Id-Header, dessen Wert die Ablaufverfolgungs-ID ist und der folgenden ähnelt:

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

   • Wenn das Token abgelaufen ist, enthält die Antwort einen Apim-Debug-Authorization-Expired-Header mit Informationen zum Ablaufdatum.

   • Wenn das Token für eine andere API abgerufen wurde, enthält die Antwort einen Apim-Debug-Authorization-WrongAPI-Header mit einer Fehlermeldung.

4. Ablaufverfolgung abrufen: Übergeben Sie die im vorherigen Schritt abgerufene Ablaufverfolgungs-ID an die Gateway-API Ablaufverfolgung auflisten. Um beispielsweise die Ablaufverfolgung für das verwaltete Gateway abzurufen, verwenden Sie eine Anforderung ähnlich der folgenden:

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

   Übergeben Sie im Anforderungstext die im vorherigen Schritt abgerufene Ablaufverfolgungs-ID.

   {
       "traceId": "0123456789abcdef...."
   }
   

   Der Antworttext enthält die Ablaufverfolgungsdaten für die vorherige API-Anforderung an das Gateway. Die Ablaufverfolgung ähnelt der Ablaufverfolgung, die Sie sehen können, wenn Sie einen Aufruf in der Testkonsole des Portals verfolgen.

Informationen zum Anpassen von Ablaufverfolgungsinformationen finden Sie in der Ablaufverfolgungsrichtlinie.

Nächste Schritte

In diesem Tutorial haben Sie Folgendes gelernt:

Fahren Sie mit dem nächsten Tutorial fort: