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 ein Fehler im folgenden Format 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, geben Sie aber dieses Mal mit der --backend-auth-service-account Option die E-Mail-Adresse des zu verwendenden Dienstkontos an:

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

Prüfen Sie, ob 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 einen Fehler zurückgeben (HTTP-Statuscodes 400 bis 599), ist aus der Antwort selbst möglicherweise nicht ersichtlich, ob der Fehler vom Gateway oder von Ihrem Back-End stammt. So ermitteln Sie die Quelle:

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

    Zum Log-Explorer

  2. Filtern Sie nach der relevanten Gateway-Ressource mit der folgenden Log-Abfrage:

    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 die Google Cloud Region für das bereitgestellte Gateway ist.

  3. Suchen Sie den Logeintrag, der der HTTP-Fehlerantwort entspricht, die Sie untersuchen möchten. Filtern Sie beispielsweise nach httpRequest.status.

  4. Prüfen Sie den Inhalt des Felds jsonPayload.responseDetails.

Wenn der Wert des Felds jsonPayload.responseDetails ist "via_upstream", stammt die Fehlerantwort von Ihrem Back-End und Sie müssen die Fehlerbehebung direkt dort durchführen. Bei jedem anderen Wert stammt die Fehlerantwort vom Gateway. Weitere Tipps zur Fehlerbehebung finden Sie in den folgenden Abschnitten dieses Dokuments.

API-Anfrage gibt einen HTTP-Fehler `403` 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 nicht zulässig.

Eine bereitgestellte API hat die Berechtigungen, die den Rollen zugeordnet sind, die dem Dienstkonto zugewiesen wurden, 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, prüfen Sie, ob dem Dienstkonto die Rolle Editor oder die Rolle zugewiesen ist, die für den Zugriff auf den Backend-Dienst erforderlich ist. Wenn der Backend-Dienst mit Cloud Run Functionsimplementiert ist, prüfen Sie, ob dem Dienstkonto die Cloud Function Invoker Rolle zugewiesen ist.

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 Back-End-Dienstes verwendet wurde.

Eine bereitgestellte API hat die Berechtigungen, die den Rollen zugeordnet sind, die dem Dienstkonto zugewiesen wurden, 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:

  1. Unmittelbar nach dem Löschen oder Deaktivieren des Dienstkontos werden in Ihren Gateway-Logs möglicherweise HTTP-Antworten mit dem Statuscode 401 angezeigt. Wenn das jsonPayload.responseDetails Feld auf "via_upstream" in der jsonPayload des Logeintrags gesetzt ist, ist das Löschen oder Deaktivieren des Dienstkontos die Ursache des Fehlers.

  2. 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-Antworten mit dem Statuscode 401 möglicherweise nicht angezeigt. Die HTTP-Fehler 500 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 ist (z. B. bigquery.googleapis.com), werden in Ihren Gateway-Logs HTTP-Antworten mit dem Statuscode 401 angezeigt wobei das Feld jsonPayload.responseDetails auf "via_upstream" gesetzt ist. Das liegt daran, dass sich API Gateway mit einem ID-Token bei Back-Ends authentifiziert, während andere Google Cloud APIs ein Zugriffstoken erfordern.

API-Anfrage gibt einen HTTP-Fehler 500 für eine Methode mit Kontingentbeschränkung zurück

Wenn Sie den folgenden Fehler erhalten, konnte das Gateway kein Kontingent für Ihre Anfrage zuweisen:

HTTP/2 500
{"code":500,"message":"Failed to call Service Control Quota."}

Dieser Fehler tritt häufig auf, wenn Sie eine Methode aufrufen, für die ein Kontingent konfiguriert ist, die Kontingentmesswerte für die API aber nicht mehr vorhanden sind. Auf einem gRPC-Gateway wird derselbe Fehler als gRPC-Statuscode Internal zurückgegeben.

Ursache in den Gateway-Logs prüfen

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

    Zum Log-Explorer

  2. Führen Sie die folgende Log-Abfrage aus:

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
jsonPayload.responseDetails="service_control_quota_error"
httpRequest.status=500

    Dabei gibt GATEWAY_ID den Namen des Gateways an.

    Die Abfrage filtert nach dem Statuscode und nach jsonPayload.responseDetails, da API Gateway denselben responseDetails Wert für jede Kontingentablehnung verwendet. Eine Anfrage, die ihr Kontingent rechtmäßig überschritten hat, erzeugt denselben Wert mit einem httpRequest.status von 429.

  3. Prüfen Sie die Felder jsonPayload.apiConfig und jsonPayload.apiMethod aller übereinstimmenden Einträge. Sie geben die API-Konfiguration und die Methode an, deren Kontingentkonfiguration ungültig ist.

Warum eine API-Konfiguration eine ungültige Kontingentkonfiguration haben kann

Sie definieren Kontingentmesswerte und -limits in einer API-Konfiguration, aber API Gateway wendet sie auf die gesamte API an. Jedes Mal, wenn Sie eine API-Konfiguration erstellen, werden die darin deklarierten Messwerte und Limits durch die in den vorherigen API-Konfigurationen der API deklarierten Werte ersetzt. Nur die Werte aus der zuletzt erstellten API-Konfiguration werden erzwungen.

Im Gegensatz dazu werden die von jeder Methode verbrauchten Messwerte in der API-Konfiguration definiert, die vom Gateway bereitgestellt wird. Wenn ein Gateway eine ältere API-Konfiguration ausführt, fordert es Service Control auf, Kontingent für einen Messwert zuzuweisen, der in der eigenen Konfiguration vorhanden ist, aber möglicherweise nicht in der API. Wenn der Messwert nicht vorhanden ist, schlägt der Zuweisungsaufruf fehl und das Gateway lehnt die Anfrage ab.

Die folgende Sequenz führt beispielsweise dazu, dass das erste Gateway nicht mehr funktioniert:

  1. Sie erstellen die API-Konfiguration config-v1, die den Messwert quota-metric-v1 deklariert, und stellen sie in gateway-1 bereit.
  2. Sie erstellen die API-Konfiguration config-v2 für dieselbe API, die den Messwert quota-metric-v2 deklariert, und stellen sie in gateway-2 bereit.

gateway-2 funktioniert, aber Anfragen an die Methoden mit Kontingentbeschränkung von gateway-1 schlagen fehl, da quota-metric-v1 nicht mehr für die API definiert ist.

Die folgenden Änderungen können zu Fehlern für jedes Gateway führen, das noch mit einer älteren API-Konfiguration bereitgestellt wird:

  • Umbenennen oder Entfernen eines Messwerts
  • Ändern des Messwerts, auf den ein Kontingentlimit angewendet wird
  • Ändern des Messwerts, der in den Kontingentkosten pro Methode angegeben ist (x-google-quota für OpenAPI-Dokumente oder quota.metric_rules für gRPC-Dienstkonfigurationen)

Wenn Sie nur den Wert eines Limits ändern, treten keine Fehler auf. Da Limits jedoch auch auf API-Ebene angewendet werden, wird der neue Wert auf jedem Gateway dieser API erzwungen, einschließlich Gateways, die mit einer älteren API-Konfiguration bereitgestellt wurden.

Bereitgestellte Kontingentkonfigurationen vergleichen

  1. Listen Sie Ihre Gateways und die API-Konfiguration auf, die jeweils bereitgestellt wird:

    gcloud api-gateway gateways list \
 --format="table(name.basename(),apiConfig)"

  2. Listen Sie die API-Konfigurationen der betroffenen API auf, wobei die zuletzt erstellte zuerst angezeigt wird:

    gcloud api-gateway api-configs list --api=API_ID \
 --format="table(name.basename(),createTime:sort=1:reverse)"

    Der erste Eintrag ist die API-Konfiguration, deren Kontingentmesswerte und -limits für die gesamte API erzwungen werden. Sortieren Sie mit dem Flag --format wie gezeigt. Dieser Befehl unterstützt das Flag --sort-by nicht und gibt API-Konfigurationen nicht in einer vorhersehbaren Reihenfolge zurück.

  3. Zeigen Sie die API-Definition an, aus der eine API-Konfiguration erstellt wurde:

    gcloud api-gateway api-configs describe CONFIG_ID --api=API_ID \
 --view=FULL --format="value(openapiDocuments[0].document.contents)" \
 | tr '_-' '/+' | base64 --decode

    Der tr Befehl ist erforderlich, da das contents Feld base64url-codiert ist, was base64 --decode nicht direkt lesen kann.

    Bei einer gRPC-API befindet sich die Kontingentkonfiguration in der Dienstkonfiguration und nicht in einem OpenAPI-Dokument. Ersetzen Sie daher openapiDocuments[0].document.contents durch managedServiceConfigs[0].contents.

  4. Führen Sie den Befehl in Schritt 3 für die API-Konfiguration oben in der Liste aus Schritt 2 aus und dann für jede der anderen API-Konfigurationen, die in Schritt 1 noch als in einem Gateway bereitgestellt angezeigt werden.

  5. Vergleichen Sie die Ergebnisse. Jeder Messwert, der von einer älteren API-Konfiguration für ihre Methoden verwendet wird, muss auch in der zuletzt erstellten API-Konfiguration definiert sein. Wenn ein Messwert in dieser Konfiguration fehlt, schlagen die Gateways fehl, die die ältere API-Konfiguration bereitstellen.

Gültige Kontingentkonfiguration wiederherstellen

Prüfen Sie Ihre Kontingentmesswerte und -limits, um sicherzustellen, dass sie in allen aktiven Konfigurationen einheitlich sind. Führen Sie dazu eine der folgenden Aktionen aus:

  • Aktualisieren Sie jedes Gateway der API, um die zuletzt erstellte API-Konfiguration zu verwenden, wie unter Gateway aktualisieren beschrieben.
  • Erstellen Sie eine neue API-Konfiguration, die alle Messwerte deklariert, die von den noch bereitgestellten API-Konfigurationen verwendet werden, und behalten Sie die vorhandenen Gateways mit ihren aktuellen API-Konfigurationen bei.

Um Zuweisungsfehler zu vermeiden, müssen die Messwertnamen in allen API-Konfigurationen einer API einheitlich sein. Wenn Sie ein Kontingent ändern, ändern Sie den Wert des Limits und nicht den Namen des Messwerts.

API-Anfragen mit hoher Latenz

Wie Cloud Run und Cloud Run Functions unterliegt auch API Gateway der Latenz beim Kaltstart. Wenn Ihr Gateway seit 15 bis 20 Minuten keinen Traffic empfangen hat, tritt bei Anfragen an Ihr Gateway innerhalb der ersten 10 bis 15 Sekunden des Kaltstarts eine Latenz von 3 bis 5 Sekunden auf.

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

Loginformationen können nicht angezeigt werden

Wenn Ihre API korrekt antwortet, die Logs aber keine Daten enthalten, bedeutet das in der Regel, dass Sie nicht alle Google-Dienste aktiviert haben, die für API Gateway erforderlich sind.

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

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

So aktivieren Sie die erforderlichen Dienste:

Google Cloud Console

  1. Rufen Sie in der Google Cloud Console die Seite APIs und Dienste > API-Bibliothek auf.

    Zur API-Bibliothek

  2. Geben Sie auf der Seite API-Bibliothek den Namen der erforderlichen API in die Suchleiste ein.
  3. Wählen Sie in den Suchergebnissen die API-Seite aus.
  4. Klicken Sie auf der API-Seite auf Aktivieren.
  5. Wiederholen Sie diese Schritte für jeden der in der obigen Tabelle aufgeführten Dienste.

Google Cloud CLI

Verwenden Sie die folgenden Befehle, um die 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.