Fehlerbehebung – Übersicht

Diese Seite enthält allgemeine Informationen zur Fehlerbehebung für API Gateway.

„gcloud api-gateway“-Befehle können nicht ausgeführt werden

Damit Sie die gcloud api-gateway ...-Befehle ausführen können, müssen Sie die Google Cloud CLI aktualisiert und die erforderlichen Google-Dienste aktiviert haben. Weitere Informationen finden Sie unter Entwicklungsumgebung konfigurieren.

Der Befehl „gcloud api-gateway api-configs create“ gibt an, dass das Dienstkonto nicht vorhanden ist.

Wenn Sie den Befehl gcloud api-gateway api-configs create ... ausführen und ein Fehler in der folgenden Form angezeigt wird:

ERROR: (gcloud.api-gateway.api-configs.create) FAILED_PRECONDITION:
Service Account "projects/-/serviceAccounts/service_account_email" does not exist

Führen Sie den Befehl noch einmal aus, aber fügen Sie dieses Mal die Option --backend-auth-service-account ein, um die E-Mail-Adresse des zu verwendenden Dienstkontos explizit anzugeben:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

Achten Sie darauf, dass Sie dem Dienstkonto bereits die erforderlichen Berechtigungen zugewiesen haben, wie unter Entwicklungsumgebung konfigurieren beschrieben.

Quelle von API-Fehlerantworten ermitteln

Wenn Anfragen an Ihre bereitgestellte API zu einem Fehler führen (HTTP-Statuscodes 400 bis 599), ist aus der Antwort selbst möglicherweise nicht ersichtlich, ob der Fehler vom Gateway oder von Ihrem Backend stammt. So ermitteln Sie die IP-Adresse:

Rufen Sie die Seite „Log-Explorer“ auf und wählen Sie Ihr Projekt aus.

Zum Log-Explorer
Filtern Sie mit der folgenden Log-Abfrage nach der relevanten Gateway-Ressource:
```
resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"
```
Wobei:
- GATEWAY_ID den Namen des Gateways angibt.
- GCP_REGION ist die Google Cloud Region für das bereitgestellte Gateway.
Suchen Sie den Logeintrag, der der HTTP-Fehlerantwort entspricht, die Sie untersuchen möchten. Filtern Sie beispielsweise nach httpRequest.status.
Prüfen Sie den Inhalt des Felds jsonPayload.responseDetails.

Wenn der Wert des Felds jsonPayload.responseDetails "via_upstream" ist, stammt die Fehlerantwort von Ihrem Backend. Sie müssen das Problem also direkt in Ihrem Backend beheben. Bei jedem anderen Wert stammt die Fehlermeldung vom Gateway. Weitere Tipps zur Fehlerbehebung finden Sie in den folgenden Abschnitten dieses Dokuments.

API-Anfrage gibt einen HTTP 403-Fehler zurück

Wenn eine Anfrage an eine bereitgestellte API den HTTP-Fehler 403 an den API-Client zurückgibt, ist die angeforderte URL gültig, der Zugriff ist jedoch aus irgendeinem Grund verboten.

Eine bereitgestellte API hat die Berechtigungen, die den Rollen zugeordnet sind, die dem Dienstkonto zugewiesen sind, das Sie beim Erstellen der API-Konfiguration verwendet haben. In der Regel ist der Grund für den HTTP-Fehler 403, dass das Dienstkonto nicht die erforderlichen Berechtigungen für den Zugriff auf den Backend-Dienst hat.

Wenn Sie die API und den Backend-Dienst im selben Google Cloud-Projekt definiert haben, muss dem Dienstkonto die Rolle Editor oder die Rolle zugewiesen sein, die für den Zugriff auf den Backend-Dienst erforderlich ist. Wenn der Back-End-Dienst beispielsweise mit Cloud Run-Funktionen implementiert ist, muss dem Dienstkonto die Rolle Cloud Function Invoker zugewiesen sein.

API-Anfrage gibt einen HTTP-Fehler `401` oder `500` zurück

Wenn eine Anfrage an eine bereitgestellte API den HTTP-Fehler 401 oder 500 an den API-Client zurückgibt, kann ein Problem mit dem Dienstkonto auftreten, das beim Erstellen der API-Konfiguration zum Aufrufen Ihres Backend-Dienstes verwendet wurde.

Eine bereitgestellte API hat die Berechtigungen, die den Rollen zugeordnet sind, die dem Dienstkonto zugewiesen sind, das Sie beim Erstellen der API-Konfiguration verwendet haben. Das Dienstkonto wird geprüft, um sicherzustellen, dass es vorhanden ist und vom API-Gateway verwendet werden kann, wenn die API bereitgestellt wird.

Wenn das Dienstkonto nach der Bereitstellung des Gateways gelöscht oder deaktiviert wird, kann Folgendes passieren:

Unmittelbar nach dem Löschen oder Deaktivieren des Dienstkontos werden möglicherweise 401-HTTP-Antworten in Ihren Gateway-Logs angezeigt. Wenn das Feld jsonPayload.responseDetails im jsonPayload des Logeintrags auf "via_upstream" gesetzt ist, ist das Löschen oder Deaktivieren des Dienstkontos die Ursache des Fehlers.
Möglicherweise wird auch der HTTP-Fehler 500 ohne entsprechenden Logeintrag in den Logs des API-Gateways angezeigt. Wenn unmittelbar nach dem Löschen oder Deaktivieren des Dienstkontos keine Anfragen an Ihr Gateway gesendet werden, werden die HTTP 401-Antworten möglicherweise nicht angezeigt. Die HTTP 500-Fehler ohne entsprechende API-Gateway-Logs sind ein Hinweis darauf, dass das Dienstkonto des Gateways möglicherweise nicht mehr aktiv ist.

Wenn das Back-End für die fehlgeschlagene Anfrage eine andere Google Cloud API (z. B. bigquery.googleapis.com) ist, sehen Sie in Ihren Gateway-Logs HTTP-401-Antworten, bei denen das Feld jsonPayload.responseDetails auf "via_upstream" gesetzt ist. Das liegt daran, dass API Gateway die Authentifizierung bei Back-Ends mit einem ID-Token durchführt, während für andere Google Cloud APIs ein Zugriffstoken erforderlich ist.

API-Anfragen mit hoher Latenz

Wie Cloud Run und Cloud Run Functions unterliegt API Gateway der Latenz für Kaltstarts. Wenn Ihr Gateway seit 15 bis 20 Minuten keinen Traffic empfangen hat, kommt es bei Anfragen, die innerhalb der ersten 10 bis 15 Sekunden nach dem Kaltstart an Ihr Gateway gesendet werden, zu einer Latenz von 3 bis 5 Sekunden.

Wenn das Problem nach der anfänglichen Aufwärmphase weiterhin besteht, prüfen Sie die Anfrageprotokolle der Backend-Dienste, die Sie in Ihrer API-Konfiguration konfiguriert haben. Wenn der Backend-Dienst beispielsweise mit Cloud Run Functions implementiert ist, sehen Sie sich die Cloud Logging-Einträge des zugehörigen Cloud Function-Anfragelogs an.

Loginformationen können nicht angezeigt werden

Wenn Ihre API korrekt reagiert, die Logs aber keine Daten enthalten, haben Sie in der Regel nicht alle von API Gateway benötigten Google-Dienste aktiviert.

Für API Gateway müssen Sie die folgenden Google-Dienste aktivieren:

Name	Titel
`apigateway.googleapis.com`	API Gateway API
`servicemanagement.googleapis.com`	Service Management API
`servicecontrol.googleapis.com`	Service Control API

Verwenden Sie die folgenden Befehle, um diese Dienste zu aktivieren:

gcloud services enable apigateway.googleapis.com
gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Weitere Informationen zu den gcloud-Diensten finden Sie unter gcloud-Dienste.