Diese Seite wurde von der Cloud Translation API übersetzt.

Fehlerbehebung – Übersicht

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

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

Wenn Sie die gcloud api-gateway ...-Befehle ausführen möchten, 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 eine Fehlermeldung wie die folgende erhalten:

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, diesmal aber mit der Option --backend-auth-service-account, um die E-Mail-Adresse des zu verwendenden Dienstkontos anzugeben:

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --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), geht aus der Antwort selbst möglicherweise nicht hervor, ob der Fehler vom Gateway oder von Ihrem Backend stammt. So ermitteln Sie das:

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

Zum Log-Explorer
Filtern Sie mit der folgenden Protokollabfrage nach der entsprechenden 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 Region Google Cloud für das bereitgestellte Gateway.
Suchen Sie den Logeintrag, der mit der HTTP-Fehlerantwort übereinstimmt, die Sie untersuchen möchten. Beispiel: Filtern Sie 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 aus Ihrem Backend. Sie müssen dann direkt Ihr Backend beheben. Wenn es sich um einen anderen Wert handelt, stammt die Fehlerantwort 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 zwar gültig, der Zugriff ist aber aus irgendeinem Grund nicht zulässig.

Eine bereitgestellte API hat die Berechtigungen, die den Rollen zugewiesen sind, die dem Dienstkonto gewährt wurden, das Sie beim Erstellen der API-Konfiguration verwendet haben. In der Regel liegt der Grund für den HTTP-403-Fehler darin, 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 Backend-Dienst beispielsweise mit Cloud Run-Funktionen implementiert ist, muss dem Dienstkonto die Rolle Cloud Function Invoker zugewiesen sein.

API-Anfrage gibt einen HTTP-`401`- oder `500`-Fehler 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 zugewiesen sind, die dem Dienstkonto zugewiesen sind, das Sie beim Erstellen der API-Konfiguration verwendet haben. Es wird geprüft, ob das Dienstkonto 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 es zu der folgenden Abfolge von Ereignissen kommen:

Unmittelbar nach dem Löschen oder Deaktivieren des Dienstkontos werden in Ihren Gateway-Logs möglicherweise HTTP-Antworten vom Typ 401 angezeigt. Wenn das Feld response_code_details im Abschnitt jsonPayload des Logeintrags auf "via_upstream" festgelegt ist, ist das Löschen oder Deaktivieren des Dienstkontos die Ursache für den Fehler.
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.

API-Anfragen mit hoher Latenz

Wie Cloud Run und Cloud Run Functions unterliegt auch API Gateway der Latenz beim Kaltstart. Wenn Ihr Gateway 15 bis 20 Minuten lang keinen Traffic erhalten hat, haben Anfragen an Ihr Gateway innerhalb der ersten 10 bis 15 Sekunden nach dem Kaltstart eine Latenz von 3 bis 5 Sekunden.

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

Protokollinformationen können nicht angezeigt werden

Wenn Ihre API richtig antwortet, die Protokolle aber keine Daten enthalten, haben Sie in der Regel nicht alle von API Gateway erforderlichen 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

Mit dem folgenden Befehl bestätigen Sie, dass die erforderlichen Dienste aktiviert sind:

gcloud services list

Wenn die erforderlichen Dienste nicht aufgeführt sind, müssen Sie sie 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.