Comment puis-je utiliser les journaux API Gateway pour résoudre les problèmes d'API ?

Brève description

Pour résoudre les problèmes d’une API REST API Gateway ou une API WebSocket, activez la journalisation des exécutions, puis utilisez Amazon CloudWatch Logs pour accéder à vos journaux. Assurez-vous d'associer toutes les autorisations requises au rôle Gestion des identités et des accès AWS (AWS IAM) d’API Gateway. Pour obtenir des instructions, consultez la section Comment activer CloudWatch Logs pour résoudre les problèmes liés à mon API REST API Gateway ou à mon API WebSocket ?

Remarque : Les API HTTP prennent uniquement en charge la journalisation des accès. Pour plus d'informations sur la configuration de la journalisation pour ces API, consultez la section Configurer la journalisation pour les API HTTP dans API Gateway.

Résolution

Une fois que vous avez activé la journalisation, API Gateway crée automatiquement un groupe de journaux CloudWatch nommé API-Gateway-Execution-Logs/{rest-api-id}/{stage-name}. Utilisez ce groupe pour résoudre vos problèmes de manière plus approfondie. Pour plus d’informations, consultez la section Formats de journal CloudWatch pour API Gateway.

Vérifier les erreurs d'autorisation

Si vous activez les mécanismes d’autorisation AWS Lambda pour votre API, les journaux indiquent si la requête est autorisée et incluent les ID de la requête et du mécanisme d'autorisation.

Exemples de journaux autorisés :

Starting authorizer: 62mgrc for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0
Successfully completed authorizer execution

Exemples de journaux non autorisés :

Starting authorizer: 62mgrc for request: fd443056-60d0-425f-874e-e93e5d61351e  
Unauthorized request: fd443056-60d0-425f-874e-e93e5d61351e

Pour résoudre ce problème, consultez la section Pourquoi des erreurs « 401 Unauthorized » d'API Gateway s’affichent-elles après que j’ai créé un mécanisme d’autorisation Lambda ?

Mettre à jour la configuration de votre plan d'utilisation

Une fois le mécanisme d'autorisation Lambda journalisé, API Gateway vérifie le plan d'utilisation de la requête d'API. Si vous n'avez pas configuré de plan d'utilisation, les requêtes d'API ne sont pas prises en compte dans les limites de débit.

Exemples de journaux de plans d'utilisation :

Verifying Usage Plan for request: 3323ffe5-6ddf-45c8-896a-b45ec2284cc0. API Key: API Stage: <api_id>/<stage>
API Key authorized because method 'GET /' does not require API Key. Request will not contribute to throttle or quota limits
Usage Plan check succeeded for API Key and API Stage <api_id>/<stage>

Si vous configurez des API avec des clés d'API et que l'en-tête X-API-Key est manquant, les journaux renvoient une erreur similaire au message suivant :

« API Key not authorized because method 'GET /' requires API Key and API Key is not associated with a Usage Plan for API Stage <api_id>/<stage>: API Key was required but not present »

Pour résoudre ce problème, examinez la configuration de l'API. Vous devez associer la clé API au plan d'utilisation requis et inclure la clé dans la requête en tant qu'en-tête X-API-KEY avec la valeur correcte.

Si vous ajoutez la clé d'API correcte dans l'en-tête et qu'API Gateway limite la requête, les journaux renvoient une erreur similaire au message suivant :

« API Key **FGQes7 exceeded throttle limit for API Stage <api_id>/<stage>: Key throttle limit exceeded for Usage Plan ID iwuzkt. Limit: 5.00 Burst: 0
Method completed with status: 429 »

Pour résoudre ce problème, suivez les étapes décrites dans la section Comment résoudre les erreurs « 429 Too Many Requests » ou « Limit Exceeded » pour mon API avec API Gateway ?

Types de journaux de requêtes

Lorsque vous activez le suivi des données et les journaux d'erreurs et d'informations, les journaux API Gateway contiennent plus de détails pour vous aider à résoudre les problèmes. Pour savoir où la requête API Gateway échoue, consultez les types de journaux suivants pour de plus amples informations.

Remarque : Pour les journaux de requêtes, vous devez choisir Erreurs et journaux d'informations dans le menu déroulant Journaux CloudWatch. Puis, activez le Suivi des données pour les journaux d'exécution. Le suivi des données pouvant journaliser des données sensibles, il est déconseillé d’activer le Suivi de données pour les API de production.

Journaux de requêtes de méthode

Les journaux de requêtes de méthode incluent des informations détaillées reçues par une requête d'API, notamment le chemin de la requête, le paramètre de requête, l'en-tête et le corps de la requête.

Exemple de journal de requêtes de méthode :

(####) Method request path: {...}
(####) Method request query string: {...}
(####) Method request headers: {User-Agent=...}
(####) Method request body before transformations: ...

Journaux de requêtes de point de terminaison

Les journaux de requêtes de point de terminaison incluent des informations détaillées reçues par une requête d'API, notamment l'URI, les en-têtes de requête et le corps de la requête.

Exemple de journal de requêtes de point de terminaison :

(####) Endpoint request URI: ...
(####) Endpoint request headers: {...}
(####) Endpoint request body after transformations: {...}

Les données incluses dans les requêtes de point de terminaison sont envoyées à votre intégration principale en vue d’un traitement ultérieur.

Journaux de réponses de point de terminaison

Les journaux de réponses de point de terminaison incluent les données renvoyées par les intégrations du backend, notamment le code de statut, les en-têtes, le corps et la latence d'intégration.

Exemple de journal de réponses de point de terminaison :

(####) Received response. Status: YYY, Integration latency: ZZZ ms
(####) Endpoint response headers: {...}
(####) Endpoint response body before transformations: {...}

Journaux de réponses de méthode

Les journaux de réponses de méthode incluent les en-têtes et le corps envoyés au client après la transformation.

Exemple de journal de réponses de méthode :

(####) Method response body after transformations: ...
(####) Method response headers: {...}

Important : API Gateway limite les événements de journal à 1 024 octets. API Gateway tronque les événements de journal supérieurs à 1 024 octets, tels que les corps de requêtes et de réponses, avant que les journaux ne soient soumis aux journaux CloudWatch.

Informations connexes

Comment résoudre les problèmes liés aux journaux CloudWatch manquants pour les API REST API Gateway ?

Configurer la journalisation CloudWatch pour les API REST dans API Gateway

Surveiller l’exécution de l’API REST à l’aide des métriques Amazon CloudWatch

Surveiller l’exécution de l’API WebSocket à l’aide des métriques CloudWatch

Résolution de problèmes liés à Amazon API Gateway à l’aide des variables d'observabilité améliorées