Freigeben über

Tutorial: Debuggen von APIs mit der Anforderungsablaufverfolgung

  • Artikel

GILT FÜR: Verbrauch | Developer | Basic | Standard | Premium

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:

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

Screenshot des API-Inspektors.

Hinweis

Derzeit wird die Ablaufverfolgung von API-Anforderungen in den Dienstebenen „Basic v2“ und „Standard v2“ nicht unterstützt.

Voraussetzungen

Wichtig

  • Die Anforderungsablaufverfolgung in API Management mithilfe des Headers Ocp-Apim-Trace in einer Anforderung und unter Verwendung des Werts des Antwortheaders Ocp-Apim-Trace-Location ist veraltet.
  • Um die Sicherheit zu verbessern, kann die Ablaufverfolgung jetzt auf der Ebene einer einzelnen API aktiviert werden, indem ein zeitlich begrenztes Token mithilfe der API Management-REST-API abgerufen und in einer Anforderung an das Gateway übergeben wird. Ausführliche Informationen finden Sie unter Aktivieren der Ablaufverfolgung einer API.
  • Gehen Sie beim Aktivieren der Ablaufverfolgung mit Bedacht vor, da sie vertrauliche Informationen in den Ablaufverfolgungsdaten verfügbar machen kann. Stellen Sie sicher, dass Sie über geeignete Sicherheitsmaßnahmen verfügen, um die Ablaufverfolgungsdaten zu schützen.

Ablaufverfolgung eines Anrufs im Portal

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

  2. Klicken Sie auf APIs.

  3. Wählen Sie in der API-Liste Demo Conference API aus.

  4. Wählen Sie die Registerkarte Testen aus.

  5. Wählen Sie den Vorgang GetSpeakers aus.

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

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

    Überprüfen der Antwortablaufverfolgung

    • 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

Sie können die Ablaufverfolgung für eine API aktivieren, wenn Sie Anforderungen an API Management mit curl, einem REST-Client wie Visual Studio Code mit der REST-Clienterweiterung oder einer Client-App stellen.

Aktivieren Sie die Ablaufverfolgung mithilfe der folgenden Schritte mit Aufrufen der API Management-REST-API.

Hinweis

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

  1. Rufen Sie Anmeldeinformationen für die Ablaufverfolgung ab, indem Sie die API List debug credentials aufrufen. Übergeben Sie die Gateway-ID im URI, oder verwenden Sie „managed“ für das verwaltete Gateway der Instanz in der Cloud. Um beispielsweise Anmeldeinformationen zur Ablaufverfolgung für das verwaltete Gateway abzurufen, verwenden Sie einen Aufruf ähnlich dem 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.

    {
    "credentialsExpireAfter": PT1H,
    "apiId": "<API resource ID>",
    "purposes": ["tracing"]
}

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

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

  2. Um die Ablaufverfolgung für eine Anforderung an das API Management-Gateway zu aktivieren, senden Sie den Tokenwert in einem Apim-Debug-Authorization-Header. Wenn Sie beispielsweise einen Aufruf der Demokonferenz-API nachverfolgen möchten, verwenden Sie einen Aufruf ähnlich dem folgenden:

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

  3. Je nach Token enthält die Antwort unterschiedliche Header:

    • Wenn das Token gültig ist, enthält die Antwort einen Apim-Trace-Id-Header, dessen Wert die Ablaufverfolgungs-ID ist.
    • Wenn das Token abgelaufen ist, enthält die Antwort einen Apim-Debug-Authorization-Expired-Header mit Informationen zum Ablaufdatum.
    • Wenn das Token für falsche API abgerufen wurde, enthält die Antwort einen Apim-Debug-Authorization-WrongAPI-Header mit einer Fehlermeldung.

  4. Um die Ablaufverfolgung abzurufen, übergeben Sie die im vorherigen Schritt abgerufene Ablaufverfolgungs-ID an die API List trace für das Gateway. Um beispielsweise die Ablaufverfolgung für das verwaltete Gateway abzurufen, verwenden Sie einen Aufruf ähnlich dem 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": "<trace ID>"
}

    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:

  • Verfolgen eines Beispielaufrufs
  • Überprüfen der Schritte zur Anforderungsverarbeitung
  • Aktivieren der Ablaufverfolgung für eine API

Fahren Sie mit dem nächsten Tutorial fort:

Gefahrloses Vornehmen geringfügiger Änderungen mithilfe von Revisionen