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 \ --project=PROJECT_ID --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 la section Configurer votre environnement de développement.
Déterminer la source des réponses d'erreur de l'API
Si les requêtes envoyées à votre API déployée génèrent une erreur (codes d'état HTTP 400
à 599
), il est possible que la réponse elle-même ne permette pas de déterminer si l'erreur provient de la passerelle ou de votre backend.
Pour le savoir:
Accédez à la page "Explorateur de journaux", puis sélectionnez votre projet.
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.
Recherchez l'entrée de journal correspondant à la réponse d'erreur HTTP que vous souhaitez examiner. Par exemple, filtrez par
httpRequest.status
.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 devez résoudre directement le problème. Si la valeur est différente, la réponse d'erreur provient de la passerelle. Pour obtenir des conseils de dépannage supplémentaires, consultez les sections suivantes de ce document.
La requête API renvoie une erreur HTTP 403
Si une requête envoyée à une API déployée renvoie une erreur HTTP 403
au client de l'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 accordés au compte de service que vous avez utilisé lorsque vous avez créé la configuration de l'API. En règle générale, l'erreur HTTP 403
se produit lorsque le compte de service ne dispose pas des autorisations nécessaires pour accéder au service backend.
Si vous avez défini l'API et le service de backend dans le même projet Google Cloud, assurez-vous que le compte de service est associé au rôle Editor
ou au rôle nécessaire pour accéder au service de backend. Par exemple, si le service backend est implémenté à l'aide de fonctions Cloud Run, 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 envoyée à une API déployée renvoie une erreur HTTP 401
ou 500
au client de l'API, il est possible qu'il y ait un problème avec le compte de service utilisé lorsque vous avez créé la configuration de l'API pour appeler votre service backend.
Une API déployée dispose des autorisations associées aux rôles accordés au compte de service que vous avez utilisé lorsque vous avez créé 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 la passerelle API 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 :
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 la passerelle. Si le champ
response_code_details
est défini sur"via_upstream"
dans la sectionjsonPayload
de l'entrée de journal, cela signifie que la suppression ou la désactivation du compte de service est à l'origine de l'erreur.Une erreur HTTP
500
peut également s'afficher sans aucune entrée de journal correspondante dans les journaux de la passerelle API. Si aucune requête n'est envoyée à votre passerelle immédiatement après la suppression ou la désactivation du compte de service, vous ne verrez peut-être pas les réponses HTTP 401, mais les erreurs HTTP500
sans journaux de passerelle API correspondants indiquent que le compte de service de la passerelle n'est peut-être plus actif.
Requêtes API à latence élevée
Comme Cloud Run et les fonctions Cloud Run, API Gateway est soumis à la 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 dans les 10 à 15 premières secondes du démarrage à froid seront soumises à une latence de 3 à 5 secondes.
Si le problème persiste après la période de "préparation" initiale, vérifiez les journaux des requêtes du ou des services backend que vous avez configurés dans votre configuration d'API. Par exemple, si le service backend est implémenté à l'aide de fonctions Cloud Run, vérifiez les entrées Cloud Logging du journal des requêtes Cloud Function 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 Google suivants :
Nom | Titre |
---|---|
apigateway.googleapis.com |
API de la passerelle API |
servicemanagement.googleapis.com |
API Service Management |
servicecontrol.googleapis.com |
API Service Control |
Pour confirmer que les services requis sont activés, procédez comme suit :
gcloud services list
Si les services requis ne sont pas répertoriés, activez-les :
gcloud services enable apigateway.googleapis.comgcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
Pour en savoir plus sur les services gcloud
, consultez la section Services gcloud
.