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 eine Fehlermeldung in der folgenden Form 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, aber geben Sie dieses Mal die Option --backend-auth-service-account an, 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

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 zu einem Fehler führen (HTTP-Statuscodes 400 bis 599), ist möglicherweise nicht klar, ob der Fehler vom Gateway oder von Ihrem Backend stammt. So finden Sie das heraus:

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

    Zum Log-Explorer

  2. Filtern Sie mit der folgenden Logabfrage 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.

  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 "via_upstream" ist, stammt die Fehlerantwort von Ihrem Backend und Sie müssen die Fehlerbehebung direkt in Ihrem Backend durchführen. 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, bedeutet dies, dass die angeforderte URL gültig ist, der Zugriff jedoch aus irgendeinem Grund verboten ist.

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

API-Anfrage gibt den 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 mit Rollen verknüpft 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 401-HTTP-Antworten 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.

  2. Möglicherweise wird auch ein 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 jedoch ein Hinweis darauf, dass das Dienstkonto des Gateways möglicherweise nicht mehr aktiv ist.

Wenn das Backend für die fehlgeschlagene Anfrage eine andere Google Cloud -API ist (z. B. bigquery.googleapis.com), werden in Ihren Gateway-Logs 401-HTTP-Antworten angezeigt, wobei das Feld jsonPayload.responseDetails auf "via_upstream" gesetzt ist. Das liegt daran, dass sich API Gateway bei Back-Ends mit einem ID-Token authentifiziert, während andere Google Cloud APIs ein Zugriffstoken erfordern.

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

Wenn Sie die folgende Fehlermeldung 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 jedoch nicht mehr vorhanden sind. Auf einem gRPC-Gateway wird derselbe Fehler als gRPC-Statuscode Internal zurückgegeben.

Ursache in den Gateway-Logs bestätigen

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

    Zum Log-Explorer

  2. Führen Sie die folgende Logabfrage 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 sowie nach jsonPayload.responseDetails, da API Gateway für jede Kontingentablehnung denselben responseDetails-Wert 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 identifizieren die API-Konfiguration und die Methode, 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 Messwerte und Limits ersetzt. Es werden nur die Werte der zuletzt erstellten API-Konfiguration erzwungen.

Im Gegensatz dazu werden die von den einzelnen Methoden verwendeten 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, ein Kontingent für einen Messwert zuzuweisen, der in seiner eigenen Konfiguration, aber möglicherweise nicht in der API vorhanden ist. Wenn der Messwert nicht vorhanden ist, schlägt der Zuweisungsaufruf fehl und das Gateway lehnt die Anfrage ab.

In der folgenden Sequenz wird beispielsweise das erste Gateway beschädigt:

  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 kontingentierten Methoden von gateway-1 schlagen fehl, da quota-metric-v1 nicht mehr für die API definiert ist.

Die folgenden Änderungen können bei Gateways, die noch mit einer früheren API-Konfiguration bereitgestellt sind, zu Fehlern führen:

  • Umbenennen oder Entfernen eines Messwerts
  • Ändern des Messwerts, für den ein Kontingentlimit gilt.
  • Ändern des Messwerts, der in den Kontingentkosten pro Methode genannt wird (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 früheren API-Konfiguration bereitgestellt wurden.

Bereitgestellte Kontingentkonfigurationen vergleichen

  1. Listen Sie Ihre Gateways und die API-Konfiguration auf, die von jedem Gateway 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 erstellten zuerst aufgeführt werden:

    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. API-Definition anzeigen, 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 Befehl tr ist erforderlich, da das Feld contents 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 als noch in einem Gateway bereitgestellt angezeigt werden.

  5. Vergleichen Sie die Ergebnisse. Jeder Messwert, für den eine ältere API-Konfiguration ihre Methoden berechnet, 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 konsistent sind. Führen Sie dazu einen der folgenden Schritte 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 in ihren aktuellen API-Konfigurationen bei.

Um Zuordnungsfehler zu vermeiden, sollten Sie die Messwertnamen in den API-Konfigurationen einer API einheitlich halten. Wenn Sie ein Kontingent ändern, ändern Sie den Wert des Limits und nicht den Namen des Messwerts.

API-Anfragen mit hoher Latenz

Wie bei Cloud Run und Cloud Run Functions kann es auch bei API Gateway zu „Kaltstart“-Latenzen kommen. Wenn Ihr Gateway 15 bis 20 Minuten lang keinen Traffic erhalten hat, kommt es bei Anfragen an Ihr Gateway innerhalb der ersten 10 bis 15 Sekunden des Kaltstarts zu einer Latenz von 3 bis 5 Sekunden.

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

Log-Informationen können nicht angezeigt werden

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

Für API Gateway müssen die folgenden Google Cloud -Dienste aktiviert werden:

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 erforderlichen API-Namen 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 vorherigen 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.