Teilen über

Tutorial: Debuggen von APIs mit der Anforderungsablaufverfolgung

GILT FÜR: Alle API Management-Ebenen

In diesem Lernprogramm wird beschrieben, wie Sie die Anforderungsverarbeitung in Azure API Management prüfen oder nachverfolgen. Das Tracing hilft Ihnen beim Debuggen und bei der Fehlerbehebung Ihrer API.

Tipp

API-Teams können dieses Feature in Arbeitsbereichen verwenden. Arbeitsbereiche bieten isolierten administrativen Zugriff auf APIs und ihre eigenen API-Runtimeumgebungen.

In diesem Tutorial lernen Sie Folgendes:

  • Ablaufverfolgung für einen Beispielaufruf in der Testkonsole
  • Überprüfen der Schritte zur Anforderungsverarbeitung
  • Ablaufverfolgung für eine API aktivieren

Screenshot des API-Inspektors.

Voraussetzungen

Wichtig

  • API Management unterstützt keine Abonnements mehr für die Ablaufverfolgung oder den Ocp-Apim-Trace-Header mehr.
  • Um die API-Sicherheit zu verbessern, kann die Ablaufverfolgung jetzt auf der Ebene einer einzelnen API aktiviert werden. Rufen Sie ein zeitlich begrenztes Token mithilfe der API Management-REST-API ab, und übergeben Sie das Token in einer Anforderung an das Gateway. Ausführliche Informationen finden Sie unter Aktivieren der Ablaufverfolgung einer API.
  • Achten Sie beim Aktivieren der Ablaufverfolgung. Es kann vertrauliche Informationen in den Tracing-Daten enthüllen. Stellen Sie sicher, dass Sie über geeignete Sicherheitsmaßnahmen verfügen, um die Tracking-Daten zu schützen.

Verfolgen eines Anrufs im Azure-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 AbfrageparameterpetId1 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 überschreiben, indem Sie einen Schlüssel für ein anderes Abonnement im Azure-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 Trace 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.

    Screenshot der Ablaufverfolgung der Überprüfungsantwort.

    • Eingehend. Zeigt die ursprüngliche Anforderungs-API-Verwaltung, die vom Aufrufer empfangen wurde, und die Richtlinien, die auf die Anforderung angewendet wurden. Wenn Sie beispielsweise Richtlinien im Tutorial: Transformieren und Schützen Ihrer API hinzugefügt haben, werden sie hier angezeigt.
    • Backend. Zeigt die von API Management an das API-Back-End gesendeten Anforderungen und die empfangene Antwort.
    • Ausgehend. Zeigt die Richtlinien an, die auf die Antwort angewendet wurden, bevor sie zurück an den Anrufer gesendet werden.
    • Bei einem Fehler. Zeigt die Fehler an, die während der Verarbeitung der Anforderung aufgetreten sind, und die Richtlinien, die auf die Fehler angewendet wurden.

    Tipp

    Jeder Schritt zeigt auch die verstrichene Zeit, da die API-Verwaltung die Anforderung empfängt.

Ablaufverfolgung für eine API aktivieren

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

Hinweis

  • Diese Schritte erfordern Version „2023-05-01-preview“ oder höher der API Management-REST-API. Um die REST-API aufzurufen, muss Ihnen in der API Management-Instanz die Rolle „Mitwirkender“ oder höher zugewiesen sein.
  • Informationen zur Authentifizierung mit der REST-API finden Sie in der Azure REST-API-Referenz.

  1. Abrufen eines Debugtokens. Rufen Sie die API Liste der Debug-Anmeldeinformationen des API-Verwaltungsgateways auf. Geben Sie im URI managed für das verwaltete Gateway der Instanz in der Cloud oder die Gateway-ID für ein selbst gehostetes Gateway ein. Um beispielsweise Ablaufverfolgungsanmeldeinformationen für das verwaltete Gateway der Instanz abzurufen, stellen Sie eine Anforderung ähnlich dem folgenden Beispiel:

    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. Geben Sie purposes als tracing an. Standardmäßig laufen die in der Antwort zurückgegebenen Tokenanmeldeinformationen nach 1 Stunde ab. Sie können einen anderen Wert in der Nutzlast angeben. Die Ablaufzeit ist auf maximal 1 Stunde begrenzt. Beispiel:

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

    Hinweis

    Dies apiId kann nur aus der vollständigen Ressourcen-ID abgerufen werden, nicht aus dem Namen, der im Azure-Portal angezeigt wird.

    API-ID abrufen:

    az apim api list --resource-group <resource-group> --service-name <service-name> -o table

    Die Debuganmeldeinformationen werden in der Antwort zurückgegeben, ähnlich wie im 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-Verwaltungsgateway 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 Lernprogramm importiert haben, können Sie eine Anforderung ähnlich dem folgenden Beispiel 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. Die Antwort auswerten. Die Antwort kann je nach Status des Debugtokens einen der folgenden Header enthalten:

    Kopfzeile der Antwort Explanation
    Apim-Trace-Id Debugtoken gültig. Der Wert ist die Trace-ID, wie: Apim-Trace-Id: 0123456789abcdef....
    Apim-Debug-Authorization-Expired Das Token ist abgelaufen. Kopfzeile enthält Informationen zum Ablaufdatum.
    Apim-Debug-Authorization-WrongAPI Token, das für eine andere API abgerufen wurde. Kopfzeile enthält eine Fehlermeldung.

  4. Rufen Sie das Protokoll ab. Übergeben Sie die im vorherigen Schritt abgerufene Ablaufverfolgungs-ID an die Listenablaufverfolgungs-API des Gateways. Um beispielsweise die Ablaufverfolgung für das verwaltete Gateway abzurufen, verwenden Sie eine Anforderung ähnlich dem folgenden Beispiel:

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

Beispiel-HTTP-Datei für vs Code REST-Clienterweiterung

Um diese Schritte mit der Visual Studio Code REST Client-erweiterung zu automatisieren, können Sie die folgende Beispiel-.httpdatei verwenden:

@subscriptionId = // Your subscription ID
@resourceGroup = // Your resource group
@apimName = // Your API Management service name
@clientId = // Client ID from an app registration for authentication
@clientSecret = // Client secret from app registration
@externalHost = // The host name of the App Gateway or the fully qualified gateway URL
@subscriptionKey = // API Management subscription key
@apiEndPoint = // API URL
@requestBody = // Data to send
@tenantId = // Tenant ID
@apiId = // Api Id for which trace log is to be generated.

# @name login 
POST https://login.microsoftonline.com/{{tenantId}}/oauth2/token
content-type: application/x-www-form-urlencoded
 
grant_type=client_credentials&client_id={{clientId}}&client_secret={{clientSecret}}&resource=https%3A%2F%2Fmanagement.azure.com%2F
 
###
@authToken = {{login.response.body.$.access_token}}
###
# @name listDebugCredentials
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listDebugCredentials?api-version=2023-05-01-preview
Authorization: Bearer {{authToken}}

Content-Type: application/json
{
    "credentialsExpireAfter": "PT1H",
    "apiId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/apis/{{apiId}}",
    "purposes": ["tracing"]
}
 
###
@debugToken = {{listDebugCredentials.response.body.$.token}}
 
###
# @name callApi
POST {{apiEndPoint}} HTTP/1.1
Host: {{externalHost}}
Apim-Debug-Authorization: {{debugToken}}
Ocp-Apim-Subscription-Key: {{subscriptionKey}}
Content-Type: application/json

{{requestBody}}
 
###
@traceId = {{callApi.response.headers.Apim-Trace-Id}}
 
###
# @name getTrace
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroup}}/providers/Microsoft.ApiManagement/service/{{apimName}}/gateways/managed/listTrace?api-version=2024-06-01-preview
Authorization: Bearer {{authToken}}
Content-Type: application/json
 
{
    "traceId": "{{traceId}}"
}

Informationen zum Anpassen von Ablaufverfolgungsinformationen finden Sie in der Ablaufverfolgungsrichtlinie.

Zusammenfassung

In diesem Tutorial haben Sie gelernt, wie die folgenden Aufgaben ausgeführt werden:

  • Ablaufverfolgung für einen Beispielaufruf in der Testkonsole
  • Überprüfen der Schritte zur Anforderungsverarbeitung
  • Ablaufverfolgung für eine API aktivieren

Nächster Schritt

Fahren Sie mit dem nächsten Tutorial fort:

Verwenden Sie Revisionen

  • Last updated on