Présentation de la section de dépannage

Cette page fournit des informations générales de dépannage pour API Gateway.

Impossible d'exécuter les commandes "gcloud api-gateway"

Pour exécuter les commandes gcloud api-gateway ..., vous devez avoir mis à jour la Google Cloud CLI et activé les services Google nécessaires. Pour en savoir plus, consultez Configurer votre environnement de développement.

La commande "gcloud api-gateway api-configs create" indique que le compte de service n'existe pas

Si vous exécutez la commande gcloud api-gateway api-configs create ... et recevez une erreur au format suivant :

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

Exécutez à nouveau la commande, mais cette fois, incluez l'option --backend-auth-service-account pour spécifier explicitement l'adresse e-mail du compte de service à utiliser :

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

Assurez-vous d'avoir déjà attribué les autorisations nécessaires au compte de service, comme décrit dans Configurer votre environnement de développement.

Déterminer la source des réponses d'erreur de l'API

Si les requêtes adressées à votre API déployée entraînent une erreur (codes d'état HTTP 400 à 599), il n'est pas forcément évident de déterminer, à partir de la réponse elle-même, si l'erreur provient de la passerelle ou de votre backend. Pour le savoir :

  1. Accédez à la page "Explorateur de journaux" et sélectionnez votre projet.

    Accéder à l'explorateur de journaux

  2. Filtrez la ressource de passerelle appropriée à l'aide de la requête de journal suivante :

    resource.type="apigateway.googleapis.com/Gateway"
resource.labels.gateway_id="GATEWAY_ID"
resource.labels.location="GCP_REGION"

    Où :

    • GATEWAY_ID spécifie le nom de la passerelle.
    • GCP_REGION est la région Google Cloud de la passerelle déployée.

  3. Recherchez l'entrée de journal correspondant à la réponse d'erreur HTTP que vous souhaitez examiner. Par exemple, filtrez par httpRequest.status.

  4. Inspectez le contenu du champ jsonPayload.responseDetails.

Si la valeur du champ jsonPayload.responseDetails est "via_upstream", la réponse d'erreur provient de votre backend et vous devrez résoudre les problèmes directement sur votre backend. S'il s'agit d'une autre valeur, la réponse d'erreur provient de la passerelle. Consultez les sections suivantes de ce document pour obtenir d'autres conseils de dépannage.

La requête API renvoie une erreur HTTP 403

Si une requête adressée à une API déployée renvoie une erreur HTTP 403 au client API, cela signifie que l'URL demandée est valide, mais que l'accès est interdit pour une raison quelconque.

Une API déployée dispose des autorisations associées aux rôles attribués au compte de service que vous avez utilisé lors de la création de la configuration de l'API. En règle générale, l'erreur HTTP 403 est due au fait que le compte de service ne dispose pas des autorisations nécessaires pour accéder au service de backend.

Si vous avez défini l'API et le service de backend dans le même projet Google Cloud, assurez-vous que le rôle Editor ou le rôle nécessaire pour accéder au service de backend est attribué au compte de service. Par exemple, si le service de backend est mis en œuvre à l'aide de Cloud Run Functions, assurez-vous que le rôle Cloud Function Invoker est attribué au compte de service.

La requête API renvoie une erreur HTTP 401 ou 500

Si une requête adressée à une API déployée renvoie une erreur HTTP 401 ou 500 au client API, il peut y avoir un problème lors de l'utilisation du compte de service utilisé lors de la création de la configuration de l'API pour appeler votre service de backend.

Une API déployée dispose des autorisations associées aux rôles accordés au compte de service que vous avez utilisé lors de la création de la configuration de l'API. Le compte de service est vérifié pour s'assurer qu'il existe et qu'il peut être utilisé par API Gateway lors du déploiement de l'API.

Si le compte de service est supprimé ou désactivé après le déploiement de la passerelle, la séquence d'événements suivante peut se produire :

  1. Immédiatement après la suppression ou la désactivation du compte de service, vous pouvez voir des réponses HTTP 401 dans les journaux de votre passerelle. Si le champ jsonPayload.responseDetails est défini sur "via_upstream" dans le champ jsonPayload de l'entrée de journal, cela indique que la suppression ou la désactivation du compte de service est à l'origine de l'erreur.

  2. Vous pouvez également voir une erreur HTTP 500 sans entrée de journal correspondante dans les journaux d'API Gateway. Si aucune requête n'est envoyée à votre passerelle immédiatement après la suppression ou la désactivation du compte de service, il est possible que vous ne voyiez pas les réponses HTTP 401. Toutefois, les erreurs HTTP 500 sans journaux de passerelle d'API correspondants indiquent que le compte de service de la passerelle n'est peut-être plus actif.

Si le backend de la requête ayant échoué est une autre API Google Cloud (par exemple, bigquery.googleapis.com), vous verrez des réponses HTTP 401 dans les journaux de votre passerelle, avec le champ jsonPayload.responseDetails défini sur "via_upstream". En effet, API Gateway s'authentifie auprès des backends avec un jeton d'ID, tandis que d'autres API Google Cloud nécessitent un jeton d'accès.

La requête API renvoie une erreur HTTP 500 pour une méthode soumise à un quota

Si vous recevez l'erreur suivante, cela signifie que la passerelle n'a pas pu allouer de quota pour votre requête :

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

Cette erreur se produit généralement lorsque vous appelez une méthode pour laquelle un quota est configuré, mais que les métriques de quota n'existent plus pour l'API. Sur une passerelle gRPC, le même échec est renvoyé en tant que code d'état gRPC Internal.

Confirmer la cause dans les journaux de votre passerelle

  1. Accédez à la page "Explorateur de journaux" et sélectionnez votre projet.

    Accéder à l'explorateur de journaux

  2. Exécutez la requête de journal suivante :

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

    Où GATEWAY_ID spécifie le nom de la passerelle.

    La requête filtre sur le code d'état ainsi que sur jsonPayload.responseDetails, car API Gateway utilise la même valeur responseDetails pour chaque rejet de quota. Une requête qui a légitimement dépassé son quota produit la même valeur avec un httpRequest.status de 429.

  3. Inspectez les champs jsonPayload.apiConfig et jsonPayload.apiMethod de toute entrée correspondante. Ils identifient la configuration de l'API et la méthode dont la configuration de quota n'est pas valide.

Pourquoi une configuration d'API peut avoir une configuration de quota non valide

Vous définissez les métriques et les limites de quota dans une configuration d'API, mais API Gateway les applique à l'ensemble de l'API. Chaque fois que vous créez une configuration d'API, les métriques et les limites qu'elle déclare remplacent celles déclarées par les configurations d'API précédentes de l'API. Seules les valeurs de la configuration d'API la plus récente sont appliquées.

En revanche, les métriques consommées par chaque méthode sont définies dans la configuration de l'API diffusée par la passerelle. Si une passerelle exécute une ancienne configuration d'API, elle demande à Service Control d'allouer un quota pour une métrique qui existe dans sa propre configuration, mais qui n'existe peut-être pas dans l'API. Si la métrique n'existe pas, l'appel d'allocation échoue et la passerelle rejette la requête.

Par exemple, la séquence suivante laisse la première passerelle défectueuse :

  1. Vous créez la configuration d'API config-v1, qui déclare la métrique quota-metric-v1, et vous la déployez sur gateway-1.
  2. Vous créez la configuration d'API config-v2 pour la même API, qui déclare la métrique quota-metric-v2, et vous la déployez sur gateway-2.

gateway-2 fonctionne, mais les requêtes adressées aux méthodes de gateway-1 soumises à des quotas commencent à échouer, car quota-metric-v1 n'est plus défini pour l'API.

Les modifications suivantes peuvent entraîner des erreurs pour toute passerelle encore déployée avec une configuration d'API antérieure :

  • Renommer ou supprimer une métrique
  • Modifier la métrique à laquelle s'applique une limite de quota.
  • Modification de la métrique nommée dans les coûts de quota par méthode (x-google-quota pour les documents OpenAPI ou quota.metric_rules pour les configurations de service gRPC).

Modifier uniquement la valeur d'une limite ne génère pas d'erreur. Toutefois, comme les limites sont également appliquées au niveau de l'API, la nouvelle valeur est appliquée à chaque passerelle de cette API, y compris les passerelles déployées avec une configuration d'API antérieure.

Comparer les configurations de quota déployées

  1. Répertoriez vos passerelles et la configuration d'API que chacune d'elles diffuse :

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

  2. Répertoriez les configurations de l'API concernée, en commençant par la plus récente :

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

    La première entrée est la configuration d'API dont les métriques et les limites de quota sont appliquées à l'ensemble de l'API. Triez avec l'option --format comme indiqué : cette commande n'est pas compatible avec l'option --sort-by et ne renvoie pas les configurations d'API dans un ordre prévisible.

  3. Affichez la définition d'API à partir de laquelle une configuration d'API a été créée :

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

    La commande tr est requise, car le champ contents est encodé en base64url, ce que base64 --decode ne peut pas lire directement.

    Pour une API gRPC, la configuration du quota se trouve dans la configuration du service plutôt que dans un document OpenAPI. Remplacez donc openapiDocuments[0].document.contents par managedServiceConfigs[0].contents.

  4. Exécutez la commande de l'étape 3 pour la configuration d'API en haut de la liste de l'étape 2, puis pour chacune des autres configurations d'API que l'étape 1 indique comme étant toujours déployées sur une passerelle.

  5. Comparez les résultats. Chaque métrique qu'une ancienne configuration d'API facture pour ses méthodes doit également être définie dans la configuration d'API la plus récemment créée. Si une métrique est manquante dans cette configuration, les passerelles qui diffusent l'ancienne configuration d'API échouent.

Restaurer une configuration de quota valide

Vérifiez vos métriques et limites de quota pour vous assurer qu'elles sont cohérentes dans toutes les configurations actives. Pour ce faire, effectuez l'une des actions suivantes :

  • Mettez à jour chaque passerelle de l'API pour utiliser la configuration d'API la plus récemment créée, comme décrit dans Mettre à jour une passerelle.
  • Créez une configuration d'API qui déclare chaque métrique utilisée par les configurations d'API toujours déployées, et conservez les passerelles existantes sur leurs configurations d'API actuelles.

Pour éviter les erreurs d'allocation, veillez à ce que les noms des métriques soient cohérents dans les configurations d'une API. Lorsque vous modifiez un quota, modifiez la valeur de la limite plutôt que le nom de la métrique.

Requêtes API à latence élevée

Comme Cloud Run et Cloud Run Functions, API Gateway est soumis à une latence de "démarrage à froid". Si votre passerelle n'a pas reçu de trafic pendant 15 à 20 minutes, les requêtes envoyées à votre passerelle au cours des 10 à 15 premières secondes du démarrage à froid subiront une latence de 3 à 5 secondes.

Si le problème persiste après la période de "mise en route" initiale, vérifiez les journaux de requêtes des service de backend que vous avez configurés dans votre configuration d'API. Par exemple, si le service de backend est implémenté à l'aide de fonctions Cloud Run, vérifiez les entrées de journal Cloud Logging du journal des requêtes Cloud Functions associé.

Impossible d'afficher les informations du journal

Si votre API répond correctement, mais que les journaux ne contiennent aucune donnée, cela signifie généralement que vous n'avez pas activé tous les services Google requis par API Gateway.

API Gateway nécessite l'activation des services Google Cloud suivants :

Nom Nom du service
API API Gateway apigateway.googleapis.com
API Service Management servicemanagement.googleapis.com
API Service Control servicecontrol.googleapis.com

Pour activer les services requis :

Console Google Cloud

  1. Dans la console Google Cloud , accédez à la page API et services > Bibliothèque d'API.

    Accéder à la bibliothèque d'API

  2. Sur la page Bibliothèque d'API, saisissez le nom de l'API requise dans la barre de recherche.
  3. Dans les résultats de recherche, sélectionnez la page de l'API.
  4. Sur la page de l'API, cliquez sur Activer.
  5. Répétez ces étapes pour chacun des services listés dans le tableau précédent.

Google Cloud CLI

Exécutez les commandes suivantes pour activer les services :

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

Pour en savoir plus sur les services gcloud, consultez la section Services gcloud.