Wie kann ich API Gateway-Protokolle verwenden, um API-Probleme zu beheben?

Kurzbeschreibung

Um Probleme mit einer API Gateway-REST-API oder WebSocket-API zu beheben, aktiviere die Ausführungsprotokollierung und verwende dann Amazon CloudWatch Logs, um auf die Protokolle zuzugreifen. Stelle sicher, dass du an die AWS Identity and Access Management (IAM)-Rolle in API Gateway alle erforderlichen Berechtigungen anfügst. Eine Anleitung findest du unter Wie aktiviere ich CloudWatch Logs, um Probleme mit meiner API Gateway-REST-API oder WebSocket-API zu beheben?

Hinweis: HTTP-APIs unterstützen nur die Zugriffsprotokollierung. Weitere Informationen zur Konfiguration der Protokollierung für diese APIs findest du unter Konfigurieren der Protokollierung für HTTP-APIs in API Gateway.

Lösung

Nachdem du die Protokollierung aktiviert hast, erstellt API Gateway automatisch eine CloudWatch-Protokollgruppe mit dem Namen API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. Verwende diese Gruppe, um die Probleme weiter zu beheben. Weitere Informationen findest du unter CloudWatch-Protokollformate für API Gateway.

Auf Autorisierungsfehler prüfen

Wenn du AWS Lambda Authorizer für deine API aktivierst, geben die Protokolle an, ob die Anforderung autorisiert ist, und enthalten Genehmiger- und Anforderungs-IDs.

Beispiel für autorisierte Protokolle:

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Beispiel für nicht autorisierte Protokolle:

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

Informationen zur Behebung dieses Problems findest du unter Warum erhalte ich den API Gateway-Fehler „401 Unauthorized“, nachdem ich einen Lambda-Genehmiger erstellt habe?

Deine Nutzungsplankonfiguration aktualisieren

Nachdem die Lambda-Genehmigerprotokolle erstellt wurden, überprüft API Gateway den Nutzungsplan für die API-Anforderung. Wenn du keinen Nutzungsplan konfiguriert hast, werden API-Anforderungen nicht auf die Drosselungslimits angerechnet.

Beispiele für Nutzungsplanprotokolle:

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

Wenn du APIs mit API-Schlüsseln konfigurierst und der X-API-Key-Header fehlt, geben die Protokolle einen Fehler zurück, welcher der folgenden Meldung ähnelt:

„API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present“

Überprüfe die API-Konfiguration, um dieses Problem zu beheben. Du musst den API-Schlüssel mit dem erforderlichen Nutzungsplan verknüpfen und den Schlüssel als X-API-KEY-Header mit dem richtigen Wert in die Anforderung aufnehmen.

Wenn du den richtigen API-Schlüssel im Header hinzufügst und API Gateway die Anforderung drosselt, geben die Protokolle einen Fehler zurück, welcher der folgenden Meldung ähnelt:

„API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429“

Um dieses Problem zu beheben, führe die Schritte unter Wie kann ich die Fehler „429 Too Many Requests“ oder „Limit Exceeded“ für meine API mit API Gateway beheben? aus

Typen von Anforderungsprotokollen

Wenn du die Datenverfolgung sowie Fehler- und Informationsprotokolle aktivierst, enthalten die API Gateway-Protokolle weitere Details, die dir bei der Problembehandlung helfen. Um herauszufinden, wo die API Gateway-Anforderung fehlschlägt, findest du weitere Informationen in den folgenden Protokolltypen.

Hinweis: Für Anforderungsprotokolle musst du im Dropdown-Menü CloudWatch-Protokolle die Option Fehler- und Info-Protokolle auswählen. Aktiviere dann die Ablaufverfolgung von Daten für die Ausführungsprotokolle. Da die Ablaufverfolgung von Daten sensible Daten protokollieren kann, empfiehlt es sich nicht, die Ablaufverfolgung von Daten für Produktions-APIs zu aktivieren.

Methodenanforderungsprotokolle

Methodenanforderungs-Protokolle enthalten detaillierte Informationen, die eine API-Anforderung erhält, einschließlich des Anforderungspfads, des Abfrageparameters, des Anforderungs-Headers und des Anforderungstexts.

Beispiel für ein Methodenanforderungsprotokoll:

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

Endpunkt-Anforderungsprotokolle

Die Endpunkt-Anforderungsprotokolle enthalten detaillierte Informationen, die eine API-Anforderung erhält, einschließlich des URI, der Anforderungs-Header und des Anforderungstexts.

Beispiel für ein Endpunkt-Anforderungsprotokoll:

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

Die in Endpunktanforderungen enthaltenen Daten werden zur weiteren Verarbeitung an die Backend-Integration gesendet.

Endpunkt-Antwortprotokolle

Die Endpunkt-Antwortprotokolle enthalten die Daten, welche die Backend-Integrationen zurückgeben, einschließlich Statuscode, Header, Text und Integrationslatenz.

Beispiel für ein Endpunkt-Antwortprotokoll:

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

Methodenantwortprotokolle

Methodenantwortprotokolle enthalten die Header und den Text, die nach der Transformation an den Client gesendet werden.

Beispiel für ein Methodenantwortprotokoll:

(####) Method response body after transformations: ...
(####) Method response headers: {...}

Wichtig: API Gateway begrenzt Protokollereignisse auf 1024 Byte. API Gateway kürzt Protokollereignisse, die größer als 1024 Byte sind, wie z. B. Anforderungs- und Antworttext, bevor die Protokolle an CloudWatch-Protokolle übermittelt werden.

Ähnliche Informationen

Wie behebe ich fehlende CloudWatch-Protokolle für API Gateway-REST-APIs?

CloudWatch-Protokollierung für REST-APIs in API Gateway einrichten

Überwachung der Ausführung der REST-API mit Amazon-CloudWatch-Metriken

Ausführung der WebSocket-API mit CloudWatch-Metriken überwachen

Problembehandlung bei Amazon-API Gateway mit erweiterten Beobachtbarkeits-Variablen