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 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 génèrent une erreur (codes d'état HTTP 400 à 599), il n'est pas toujours évident de déterminer si l'erreur provient de la passerelle ou de votre backend. Pour le déterminer :

  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 pertinente à 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 correspond à la Google Cloud région 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. Examinez le contenu du champ jsonPayload.responseDetails.

Si la valeur du champ jsonPayload.responseDetails est "via_upstream", cela signifie que la réponse d'erreur provient de votre backend et que vous devez résoudre le problème directement dans votre backend. Si la valeur est différente, cela signifie que la réponse d'erreur provient de la passerelle. Consultez les sections suivantes de ce document pour obtenir d'autres conseils de dépannage.

Une 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 d'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 implémenté à l'aide de Cloud Run Functions, assurez-vous que le compte de service a le rôle Cloud Function Invoker qui lui est attribué.

Une 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 est possible qu'il y ait un problème lors de l'utilisation du compte de service utilisé lors de la création de la configuration d'API pour appeler votre service de backend.

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 d'API. Le compte de service est vérifié pour s'assurer qu'il existe et qu'il peut être utilisé par la passerelle API lorsque l'API est déployée.

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, des réponses HTTP 401 peuvent s'afficher 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 aucune entrée de journal correspondante dans les journaux d'API Gateway. Si aucune requête n'est adressée à votre passerelle immédiatement après la suppression ou la désactivation du compte de service, il est possible que les réponses HTTP 401 ne s'affichent pas, mais les erreurs HTTP 500 sans journaux de passerelle 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 Google Cloud API (par exemple, bigquery.googleapis.com), des réponses HTTP 401 s'affichent 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 Google Cloud API nécessitent un jeton d'accès.

Une requête API renvoie une erreur HTTP 500 pour une méthode appliquée par 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é sous la forme du 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 le code d'état ainsi que jsonPayload.responseDetails car API Gateway utilise la même responseDetails valeur 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. Examinez les champs jsonPayload.apiConfig et jsonPayload.apiMethod de toute entrée correspondante. Ils identifient la configuration d'API et la méthode dont la configuration de quota n'est pas valide.

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

Vous définissez des métriques et des 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 d'API que la passerelle diffuse. Si une passerelle exécute une configuration d'API plus ancienne, elle demande à Service Control d'allouer un quota par rapport à 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 appliquées par un quota de gateway-1 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 une limite de quota s'applique.
  • Modifier 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).

La modification de la valeur d'une limite n'entraîne pas d'erreurs. 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 d'API 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 correspond à la configuration d'API dont les métriques et les limites de quota sont appliquées à l'ensemble de l'API. Triez avec l'indicateur --format comme indiqué : cette commande n'est pas compatible avec l'indicateur --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, que base64 --decode ne peut pas lire directement.

    Pour une API gRPC, la configuration de 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 configuration d'API plus ancienne facture à ses méthodes doit également être définie dans la configuration d'API la plus récente. 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 qu'elle utilise la configuration d'API la plus récente, 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, assurez-vous que les noms de métriques sont cohérents dans toutes les configurations d'API 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 adressé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 "réchauffement" initiale, consultez 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 Cloud Run Functions, consultez les entrées Cloud Logging du journal des requêtes Cloud Functions associé.

Impossible d'afficher les informations de 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 suivants Google Cloud :

Nom Nom du service
API de la passerelle API apigateway.googleapis.com
API Service Management servicemanagement.googleapis.com
API Service Control servicecontrol.googleapis.com

Pour activer les services requis :

Google Cloud Console

  1. Dans la Google Cloud console, 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

Utilisez 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 gcloud Services.