Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Surveillance des API REST dans API Gateway Dans cette section, vous pouvez apprendre à surveiller votre API à l’aide des métriques CloudWatch, de CloudWatch Logs, de Firehose et d’AWS X-Ray. En combinant les journaux d’exécution CloudWatch et les métriques CloudWatch, vous pouvez enregistrer les erreurs et les suivis d’exécution, ainsi que surveiller les performances de votre API. Vous pouvez également journaliser les appels d’API à Firehose. Vous pouvez également utiliser AWS X-Ray pour suivre les appels via les services en aval qui composent votre API. **Note** API Gateway peut ne pas générer de journaux et de métriques dans les cas suivants : Nombre d’erreurs de demande d’entité 413 trop important 431 Erreurs trop nombreuses dans les champs de l’en-tête de requête Nombre d’erreurs de demande 429 trop important Erreurs de la série 400 provenant de demandes envoyées à un domaine personnalisé qui n’a pas de mappage d’API Erreurs de la série 500 causées par des défaillances internes API Gateway ne génère pas de journaux et de métriques lors du test d’une méthode d’API REST. Les entrées CloudWatch sont simulées. Pour plus d’informations, consultez [Utilisation de la console API Gateway pour tester une méthode API REST](how-to-test-method.md). **Topics** + [Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon](monitoring-cloudwatch.md) + [Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway](set-up-logging.md) + [Journalisation des appels d’API REST adressés à Amazon Data Firehose dans API Gateway](apigateway-logging-to-kinesis.md) + [Variables pour la journalisation des accès pour API Gateway](api-gateway-variables-for-access-logging.md) + [Suivi des demandes des utilisateurs adressées aux API REST à l’aide de X-Ray dans API Gateway](apigateway-xray.md) # Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon Vous pouvez surveiller l'exécution des API en utilisant CloudWatch, qui collecte et traite les données brutes d'API Gateway en near-real-time métriques lisibles. Ces statistiques sont enregistrées pour une durée de 15 mois et, par conséquent, vous pouvez accéder aux informations historiques et acquérir un meilleur point de vue de la façon dont votre service ou application web s’exécute. Par défaut, les données métriques d'API Gateway sont automatiquement envoyées par CloudWatch intervalles d'une minute. Pour plus d'informations, consultez [Qu'est-ce qu'Amazon CloudWatch ?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) dans le *guide de CloudWatch l'utilisateur Amazon*. Les métriques présentées par API Gateway fournissent des informations permettant différents types d’analyse. La liste suivante présente certaines utilisations courantes des métriques qui sont des suggestions pour vous aider à démarrer : + Surveillez les métriques **IntegrationLatency** pour mesurer la réactivité du serveur principal. + Surveillez les métriques **Latency** pour mesurer la réactivité globale de vos appels d’API. + Surveillez les métriques **CacheHitCount** et **CacheMissCount** pour optimiser les capacités de cache afin d'atteindre les performances souhaitées. **Topics** + [Dimensions et métriques Amazon API Gateway](api-gateway-metrics-and-dimensions.md) + [Afficher les métriques CloudWatch avec le tableau de bord API dans API Gateway](how-to-api-dashboard.md) + [Afficher les métriques d'API Gateway dans la CloudWatch console](metrics_dimensions_view_in_cloud_watch.md) + [Afficher les événements du journal d'API Gateway dans la CloudWatch console](view-cloudwatch-log-events-in-cloudwatch-console.md) + [Outils de surveillance intégrés AWS à API Gateway](monitoring_automated_manual.md) # Dimensions et métriques Amazon API Gateway Les métriques et les dimensions qu'API Gateway envoie à Amazon CloudWatch sont répertoriées ci-dessous. Pour de plus amples informations, veuillez consulter [Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon](monitoring-cloudwatch.md). ## Métriques API Gateway Amazon API Gateway envoie des données métriques à CloudWatch chaque minute. L’espace de noms `AWS/ApiGateway` inclut les métriques suivantes. | Métrique | Description | | --- | --- | | 4XXError | Nombre d’erreurs côté client capturées dans une période donnée. API Gateway compte les codes d'état de réponse de la passerelle modifiés comme 4 XXError erreurs. La statistique `Sum` représente cette métrique, à savoir le nombre total d'erreurs 4XXError sur la période nommée. La statistique `Average` représente le taux d'erreurs 4XXError, à savoir le nombre total d'erreurs 4XXError divisé par le nombre total de demandes pendant la période. Le dénominateur correspond à la métrique Count (ci-dessous). Unit: Count | | 5XXError | Nombre d’erreurs côté serveur capturées dans une période donnée. La statistique `Sum` représente cette métrique, à savoir le nombre total d'erreurs 5XXError sur la période nommée. La statistique `Average` représente le taux d'erreurs 5XXError, à savoir le nombre total d'erreurs 5XXError divisé par le nombre total de demandes pendant la période. Le dénominateur correspond à la métrique Count (ci-dessous). Unit: Count | | CacheHitCount | Le nombre de demandes servies depuis le cache de l’API sur une période donnée. La statistique `Sum` représente cette métrique, à savoir le nombre total d’accès au cache sur la période donnée. La statistique `Average` représente le taux d’accès au cache, à savoir le nombre total d’accès au cache divisé par le nombre total de demandes pendant la période. Le dénominateur correspond à la métrique Count (ci-dessous). Unit: Count | | CacheMissCount | Nombre de demandes traitées à partir du backend sur une période donnée lorsque la mise en cache des API est activée. La statistique `Sum` représente cette métrique, à savoir le nombre total d’échecs d’accès au cache sur la période nommée. La statistique `Average` représente le taux d’échecs d’accès au cache, à savoir le nombre total d’accès au cache divisé par le nombre total de demandes pendant la période. Le dénominateur correspond à la métrique Count (ci-dessous). Unit: Count | | Count | Nombre total de demandes d’API sur une période donnée. La statistique `SampleCount` représente cette métrique. Unit: Count | | IntegrationLatency | Délai entre le moment de la transmission de la demande au backend par API Gateway et celui de la réception de la réponse du backend. Unit: Millisecond | | Latency | Délai entre le moment de la réception par API Gateway d’une demande d’un client et celui du renvoi de la réponse au client. La latence prend en compte la latence d’intégration et autres surcharges d’API Gateway. Unit: Millisecond | ## Dimensions pour les métriques Vous pouvez utiliser les dimensions du tableau suivant pour filtrer les métriques API Gateway. **Note** API Gateway supprime les caractères non ASCII de la ApiName dimension avant d'envoyer des métriques à. CloudWatch Si l’APIName ne contient aucun caractère ASCII, l’API ID est utilisé comme ApiName. | Dimension | Description | | --- | --- | | ApiName | Filtre les métriques API Gateway à la recherche de l’API REST avec le nom d’API spécifié. | | ApiName, Method, Resource, Stage | Filtre les métriques API Gateway à la recherche de la méthode d’API avec le nom d’API, l’étape, la ressource et la méthode spécifiés. API Gateway n'enverra pas ces métriques à moins que vous n'ayez explicitement activé CloudWatch les métriques détaillées. Dans la console, choisissez une étape, puis pour **Journaux et suivi**, sélectionnez **Modifier**. Sélectionnez **Métriques détaillées**, puis cliquez sur **Enregistrer les modifications**. Vous pouvez également appeler la AWS CLI commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) pour mettre à jour la `metricsEnabled` propriété en. `true` L’activation de ces métriques implique des frais supplémentaires pour votre compte. Pour plus d'informations sur les tarifs, consultez [Amazon CloudWatch Pricing](https://aws.amazon.com/cloudwatch/pricing/). | | ApiName, Stage | Filtre les métriques API Gateway pour trouver la ressource d’étape d’API avec le nom d’API et l’étape spécifiés. | # Afficher les métriques CloudWatch avec le tableau de bord API dans API Gateway Vous pouvez utiliser le tableau de bord API de la console API Gateway pour afficher les métriques CloudWatch de votre API déployée dans API Gateway. Celles-ci sont présentées sous forme de récapitulatif de l'activité de l'API au fil du temps. **Topics** + [Prérequis](#how-to-api-dashboard-prerequisites) + [Examen des activités de l'API dans le tableau de bord](#how-to-api-dashboard-console) ## Prérequis 1. Vous devez avoir créé une API dans API Gateway. Suivez les instructions de la section [Développez REST APIs dans API Gateway](rest-api-develop.md). 1. Vous devez avoir déployé l'API au moins une fois. Suivez les instructions de la section [Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md). ## Examen des activités de l'API dans le tableau de bord 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Choisissez une API. 1. Dans le panneau de navigation principal, choisissez **Tableau de bord**. 1. Pour **Étape**, choisissez l'étape souhaitée. 1. Choisissez **Plage de dates** pour spécifier une plage de dates. 1. Actualisez la page, si nécessaire, et affichez les diverses métriques présentées dans des graphiques distincts intitulés **Appels d'API**, **Latence**, **Latence d'intégration**, **Latence**, **Erreur 4xx** et **Erreur 5xx**. **Astuce** Pour examiner les métriques CloudWatch au niveau de la méthode, assurez-vous d'avoir activé CloudWatch Logs à ce niveau-là. Pour de plus amples informations sur la configuration de la journalisation au niveau de la méthode, veuillez consulter [Remplacement des paramètres au niveau de l’étape](set-up-stages.md#how-to-method-override). # Afficher les métriques d'API Gateway dans la CloudWatch console Les métriques sont d’abord regroupées par espace de noms de service, puis par les différentes combinaisons de dimension au sein de chaque espace de noms. Pour afficher les métriques au niveau de la méthode pour votre API, activez les métriques détaillées. Pour de plus amples informations, veuillez consulter [Modification des paramètres d’étape](set-up-stages.md#how-to-stage-settings). **Pour afficher les métriques d'API Gateway à l'aide de la CloudWatch console** 1. Ouvrez la CloudWatch console à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Si nécessaire, changez la Région AWS. Dans la barre de navigation, sélectionnez la région dans laquelle se trouvent vos AWS ressources. 1. Dans le panneau de navigation, sélectionnez ‎**Métriques**. 1. Sous l’onglet **Toutes les métriques**, choisissez **API Gateway**. 1. Pour voir les métriques par étape, choisissez le volet **By Stage**. Sélectionnez ensuite votre nom APIs et le nom de la métrique. 1. Pour voir les métriques par API spécifique, choisissez le volet **By Api Name**. Sélectionnez ensuite votre nom APIs et le nom de la métrique. **Pour afficher les métriques à l'aide de la AWS CLI** 1. Utilisez la commande [list-metrics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/list-metrics.html) suivante pour répertorier les métriques : ``` aws cloudwatch list-metrics --namespace "AWS/ApiGateway" ``` Après avoir créé une métrique, attendez jusqu’à 15 minutes pour qu’elle apparaisse. Pour consulter les statistiques métriques plus rapidement, utilisez [get-metric-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html)ou [get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/update-domain-name.html). 1. Utilisez la [get-metrics-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html)commande suivante pour afficher la moyenne sur une période en utilisant des intervalles de 5 minutes : ``` aws cloudwatch get-metric-statistics --namespace AWS/ApiGateway --metric-name Count --start-time 2011-10-03T23:00:00Z --end-time 2017-10-05T23:00:00Z --period 300 --statistics Average ``` # Afficher les événements du journal d'API Gateway dans la CloudWatch console La section suivante explique les prérequis nécessaires et explique comment afficher les événements du journal d'API Gateway dans la CloudWatch console. ## Conditions préalables 1. Vous devez avoir créé une API dans API Gateway. Suivez les instructions de la section [Développez REST APIs dans API Gateway](rest-api-develop.md). 1. Vous devez avoir déployé et invoqué l’API au moins une fois. Suivez les instructions de [Déploiement d’une API REST dans API Gateway](how-to-deploy-api.md) et [Invocation d’une API REST dans API Gateway](how-to-call-api.md). 1. Les CloudWatch journaux doivent être activés pour une étape. Suivez les instructions de la section [Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway](set-up-logging.md). ## Pour afficher les demandes et réponses d'API enregistrées à l'aide de la CloudWatch console 1. Ouvrez la CloudWatch console à l'adresse [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/). 1. Si nécessaire, changez la Région AWS. Dans la barre de navigation, sélectionnez la région dans laquelle se trouvent vos AWS ressources. Pour plus d’informations, consultez [Régions et points de terminaison](https://docs.aws.amazon.com/general/latest/gr/rande.html). 1. Dans le panneau de navigation de gauche, choisissez **Logs** (Journaux), **Log groups** (Groupes de journaux). 1. Dans le tableau **Log Groups**, choisissez un groupe de journaux portant le nom **API-Gateway-Execution-Logs\$1** \$1\$1/\$1stage-name\$1. rest-api-id 1. Sous la table **Flux de journaux**, choisissez un flux de journaux. Vous pouvez utiliser l’horodatage pour aider à localiser le flux de journal qui vous intéresse. 1. Choisissez **Texte** pour afficher du texte brut ou choisissez **Row** pour afficher l’événement ligne par ligne. **Important** CloudWatch vous permet de supprimer des groupes de journaux ou des flux. Ne supprimez pas manuellement les groupes ou flux de journaux API Gateway ; laissez API Gateway gérer ces ressources. La suppression manuelle de groupes ou de flux de journaux peut entraîner la non journalisation des demandes et réponses d’API. Si tel est le cas, vous pouvez supprimer l’intégralité du groupe de journaux pour l’API et redéployer l’API. La raison en est que l’API Gateway crée des groupes ou flux de journaux pour une étape d’API au moment de son déploiement. # Outils de surveillance intégrés AWS à API Gateway AWS fournit différents outils que vous pouvez utiliser pour surveiller API Gateway. Vous pouvez configurer certains de ces outils pour qu’ils effectuent la surveillance automatiquement, tandis que d’autres nécessitent une intervention manuelle. Nous vous recommandons d’automatiser le plus possible les tâches de supervision. ## Outils de surveillance automatisés dans AWS Vous pouvez utiliser les outils de surveillance automatique pour surveiller API Gateway et signaler un problème éventuel : + **Amazon CloudWatch Alarms** : surveillez une seule métrique sur une période que vous spécifiez et effectuez une ou plusieurs actions en fonction de la valeur de la métrique par rapport à un seuil donné sur un certain nombre de périodes. L'action est une notification envoyée à une rubrique Amazon Simple Notification Service (Amazon SNS) ou à une politique Amazon EC2 Auto Scaling. CloudWatch les alarmes n'appellent pas d'actions simplement parce qu'elles sont dans un état particulier ; l'état doit avoir changé et être maintenu pendant un certain nombre de périodes. Pour de plus amples informations, veuillez consulter [Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon](monitoring-cloudwatch.md). + **Amazon CloudWatch Logs** — Surveillez, stockez et accédez à vos fichiers journaux depuis AWS CloudTrail ou d'autres sources. Pour plus d'informations, voir [Qu'est-ce que CloudWatch les journaux ?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/WhatIsCloudWatchLogs.html) dans le *guide de CloudWatch l'utilisateur Amazon*. + **Amazon EventBridge (anciennement CloudWatch Events) : associez** les événements et acheminez-les vers une ou plusieurs fonctions ou flux cibles afin d'apporter des modifications, de capturer des informations d'état et de prendre des mesures correctives. Pour plus d'informations, consultez [Qu'est-ce qu'Amazon EventBridge ?](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) dans le *guide de EventBridge l'utilisateur*. + **AWS CloudTrail Surveillance des journaux** : partagez les fichiers journaux entre les comptes, surveillez les fichiers CloudTrail CloudWatch journaux en temps réel en les envoyant à Logs, écrivez des applications de traitement des journaux en Java et vérifiez que vos fichiers journaux n'ont pas changé après leur livraison par CloudTrail. Pour plus d'informations, consultez la section [Utilisation des fichiers CloudTrail journaux](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-working-with-log-files.html) dans le *guide de AWS CloudTrail l'utilisateur*. ## Outils de surveillance manuelle Un autre élément important de la surveillance d'API Gateway consiste à surveiller manuellement les éléments non couverts par les CloudWatch alarmes. L'API Gateway et CloudWatch les autres tableaux de bord de AWS console fournissent une at-a-glance vue de l'état de votre AWS environnement. Nous recommandons de consulter également les fichiers journaux sur l’exécution des API. + Le tableau de bord API Gateway présente les statistiques suivantes pour une étape d’API donnée sur une durée définie : + **Appels d’API** + **Accès au cache**, uniquement lorsque la mise en cache des API est activée. + **Échec de cache**, uniquement lorsque la mise en cache des API est activée. + **Latence** + **Latence d’intégration** + **Erreur 4XX** + **Erreur 5XX** + La page d' CloudWatch accueil indique : + Alarmes et statuts en cours + Graphiques des alarmes et des ressources + Statut d’intégrité du service En outre, vous pouvez CloudWatch effectuer les opérations suivantes : + Créer des [tableaux de bord personnalisés](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html) pour surveiller les services de votre choix + Représenter graphiquement les données de métriques pour résoudre les problèmes et découvrir les tendances + Recherchez et parcourez tous les indicateurs de vos AWS ressources + Créer et modifier des alarmes pour être informé des problèmes ## Création d' CloudWatch alarmes pour surveiller API Gateway Vous pouvez créer une CloudWatch alarme qui envoie un message Amazon SNS lorsque l'alarme change d'état. Une alarme surveille une seule métrique pendant une durée que vous définissez et exécute une ou plusieurs actions en fonction de la valeur de la métrique par rapport à un seuil donné pendant un certain nombre de périodes. L’action est une notification envoyée à une rubrique Amazon SNS ou à une politique Auto Scaling. Les alarmes déclenchent des actions uniquement pour les changements d'état prolongés. CloudWatch les alarmes n'appellent pas d'actions simplement parce qu'elles sont dans un état particulier ; l'état doit avoir changé et être maintenu pendant un certain nombre de périodes. # Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway Pour résoudre les problèmes liés à l'exécution des demandes ou à l'accès des clients à votre API, vous pouvez activer Amazon CloudWatch Logs pour enregistrer les appels d'API. Pour plus d'informations sur CloudWatch, voir[Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon](monitoring-cloudwatch.md). ## CloudWatch formats de journal pour API Gateway Il existe deux types de connexion à l'API CloudWatch : la journalisation de l'exécution et la journalisation des accès. Lors de la journalisation de l'exécution, API Gateway gère les CloudWatch journaux. Le processus comprend la création de groupes de journaux et de flux de journaux, et la génération de rapports dans les flux de journaux sur toutes les demandes et réponses des utilisateurs. Les données journalisées incluent les erreurs ou les suivis d’exécution (comme valeurs des paramètres des demandes ou réponses, ou données utiles), les données utilisées par les mécanismes d’autorisation Lambda (anciennement appelés mécanismes d’autorisation personnalisée), et indiquent, entre autres, si des clés d’API sont requises, si les plans d’utilisation sont activés, ainsi que d’autres informations. API Gateway supprime les en-têtes d’autorisation, les valeurs des clés d’API et d’autres paramètres de demande sensibles similaires des données journalisées. Pour renforcer votre niveau de sécurité, nous vous recommandons d’utiliser la journalisation des exécutions au niveau `ERROR` ou `INFO`. Vous devrez peut-être le faire pour vous conformer aux différents cadres de conformité. Pour plus d’informations, consultez [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) dans le *Guide de l’utilisateur AWS Security Hub *. Lorsque vous déployez une API, API Gateway crée un groupe de journaux et, sous celui-ci, les flux de journaux. Le groupe de journaux est nommé selon le format `API-Gateway-Execution-Logs_{rest-api-id}/{stage_name}`. Dans chaque groupe de journaux, les journaux sont ensuite divisés en flux de journaux, qui sont ordonnés par **Heure du dernier événement** à mesure que les données sont rapportées. Dans la journalisation des accès, vous, en tant que développeur d’API, souhaitez enregistrer qui a accédé à votre API et comment l’appelant à eu accès à l’API. Vous pouvez créer votre propre groupe de journaux ou en choisir un existant, qui peut être géré par API Gateway. Pour spécifier les détails d’accès, vous devez sélectionner des variables [`$context`](api-gateway-variables-for-access-logging.md), un format de journal et une destination de groupe de journaux. Le format du journal d’accès doit inclure au moins `$context.requestId` ou `$context.extendedRequestId`. À titre de bonne pratique, incluez `$context.requestId` et `$context.extendedRequestId` dans le format de votre journal. **`$context.requestId`** Cela journalise la valeur dans l’en-tête `x-amzn-RequestId`. Les clients peuvent écraser la valeur de l’en-tête `x-amzn-RequestId` avec une valeur au format d’un identifiant unique universel (UUID). API Gateway renvoie cet ID de demande dans l’en-tête de réponse `x-amzn-RequestId`. API Gateway remplace les demandes remplacées IDs qui ne sont pas au format UUID par celles figurant `UUID_REPLACED_INVALID_REQUEST_ID` dans vos journaux d'accès. **`$context.extendedRequestId`** extendedRequestID est un ID unique généré par API Gateway. API Gateway renvoie cet ID de demande dans l’en-tête de réponse `x-amz-apigw-id`. Un appelant API ne peut pas fournir ni remplacer cet ID de demande. Vous devrez peut-être fournir cette valeur au AWS Support pour résoudre les problèmes liés à votre API. Pour de plus amples informations, veuillez consulter [Variables pour la journalisation des accès pour API Gateway](api-gateway-variables-for-access-logging.md). Choisissez un format de journal également adopté par votre backend analytique, comme [Common Log Format](https://httpd.apache.org/docs/current/logs.html#common) (CLF), JSON, XML ou CSV. Vous pouvez ensuite y renseigner les journaux d’accès directement pour que vos mesures soient calculées et renvoyées. [Pour définir le format du journal, définissez l'ARN du groupe de journaux sur la propriété [accessLogSettings/DestinationArn de la](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#destinationArn) scène.](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html) Vous pouvez obtenir un ARN de groupe de journaux dans la CloudWatch console. Pour définir le format du journal d'accès, définissez le format choisi sur la propriété [accessLogSetting/format](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html#format) de la [scène](https://docs.aws.amazon.com/apigateway/latest/api/API_Stage.html). Quelques exemples de certains formats de journaux d’accès utilisés couramment sont affichés dans la console API Gateway et répertoriés ci-dessous. + `CLF` ([Format de journal commun](https://httpd.apache.org/docs/current/logs.html#common)): ``` $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime]"$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId ``` + `JSON`: ``` { "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId","ip": "$context.identity.sourceIp", "caller":"$context.identity.caller", "user":"$context.identity.user", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod", "resourcePath":"$context.resourcePath", "status":"$context.status", "protocol":"$context.protocol", "responseLength":"$context.responseLength" } ``` + `XML`: ``` $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user $context.requestTime $context.httpMethod $context.resourcePath $context.status $context.protocol $context.responseLength ``` + `CSV` (valeurs séparées par des virgules) : ``` $context.identity.sourceIp,$context.identity.caller,$context.identity.user,$context.requestTime,$context.httpMethod,$context.resourcePath,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId ``` ## Autorisations pour la CloudWatch journalisation Pour activer CloudWatch les journaux, vous devez autoriser API Gateway à lire et à écrire les journaux CloudWatch de votre compte. [Amazon APIGateway PushToCloudWatchLogs](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAPIGatewayPushToCloudWatchLogs.html) dispose de toutes les autorisations requises. **Note** API Gateway appelle AWS Security Token Service pour assumer le rôle IAM. Assurez-vous donc que celui-ci AWS STS est activé pour la région. Pour plus d'informations, consultez [la section Gestion du AWS STS dans une AWS région](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html). [https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) Vous devez définir la [cloudWatchRolepropriété Arn](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateAccount.html#cloudWatchRoleArn) séparément pour chaque AWS région dans laquelle vous souhaitez activer CloudWatch les journaux. Si vous recevez un message d'erreur lors de la définition de l'ARN du rôle IAM, vérifiez les paramètres de votre AWS Security Token Service compte pour vous assurer qu' AWS STS il est activé dans la région que vous utilisez. Pour plus d'informations sur l'activation AWS STS, consultez [la section Gestion du AWS STS dans une AWS région](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) dans le *guide de l'utilisateur IAM*. ## Configuration de la journalisation des CloudWatch API à l'aide de la console API Gateway Pour configurer la journalisation de CloudWatch l'API, vous devez avoir déployé l'API sur une étape. Vous devez également avoir configuré [un ARN de rôle CloudWatch Logs approprié](#set-up-access-logging-permissions) pour votre compte. 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Dans le volet de navigation principal, choisissez **Paramètres**, puis sous **Journalisation**, choisissez **Modifier**. 1. Pour l'**ARN du rôle de CloudWatch journal**, entrez l'ARN d'un rôle IAM avec les autorisations appropriées. Vous devez le faire une fois pour chaque création Compte AWS à l' APIs aide d'API Gateway. 1. Dans le volet de navigation principal, choisissez **APIs**, puis effectuez l'une des opérations suivantes : 1. Choisissez une API existante, puis une étape. 1. Créez une API et déployez-la dans une étape. 1. Dans le volet de navigation principal, choisissez **Étapes**. 1. Dans la section **Journaux et suivi**, choisissez **Modifier**. 1. Pour activer la journalisation de l’exécution : 1. Sélectionnez un niveau de journalisation dans le menu déroulant **CloudWatch Logs**. Les niveaux de journalisation sont les suivants : + **Désactivé** – La journalisation n’est pas activée pour cette étape. + **Erreurs uniquement** – La journalisation n’est activée que pour les erreurs. + **Journaux d’erreurs et d’informations** – La journalisation est activée pour tous les événements. 1. (Facultatif) Sélectionnez **Suivi des données** pour activer la journalisation du suivi des données pour votre étape. Cela peut être utile pour résoudre les problèmes APIs, mais peut entraîner l'enregistrement de données sensibles. **Note** Nous vous recommandons de ne pas utiliser le **suivi des données** pour la production APIs. 1. (Facultatif) Sélectionnez **Mesures détaillées** pour activer les CloudWatch mesures détaillées. Pour plus d'informations sur CloudWatch les métriques, consultez[Surveillez l'exécution de l'API REST avec CloudWatch les métriques Amazon](monitoring-cloudwatch.md). 1. Pour activer la journalisation des accès : 1. Activez **Journalisation des accès personnalisée**. 1. Pour **ARN de destination des journaux d’accès**, entrez l’ARN d’un groupe de journaux. Le format ARN est le suivant : `arn:aws:logs:{region}:{account-id}:log-group:log-group-name`. 1. Dans **Format des journaux**, entrez un format de journal. Vous pouvez choisir **CLF**, **JSON**, **XML** ou **CSV**. Pour en savoir plus sur les exemples de formats de journal, consultez [CloudWatch formats de journal pour API Gateway](#apigateway-cloudwatch-log-formats). 1. Sélectionnez **Enregistrer les modifications**. **Note** Vous pouvez activer la journalisation de l’exécution et la journalisation de l’accès indépendamment l’une de l’autre. API Gateway est maintenant prêt à enregistrer les demandes adressées à votre API. Vous n’avez pas besoin de redéployer l’API lorsque vous mettez à jour les paramètres de l’étape, les journaux ou variables de l’étape. ## Configurer la journalisation des CloudWatch API à l'aide de CloudFormation Utilisez l'exemple de CloudFormation modèle suivant pour créer un groupe de CloudWatch journaux Amazon Logs et configurer la journalisation de l'exécution et des accès pour une étape. Pour activer CloudWatch les journaux, vous devez autoriser API Gateway à lire et à écrire les journaux CloudWatch de votre compte. Pour en savoir plus, consultez [Associer le compte au rôle IAM](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-account.html#aws-resource-apigateway-account--examples) dans le *Guide de l’utilisateur AWS CloudFormation *. ``` TestStage: Type: AWS::ApiGateway::Stage Properties: StageName: test RestApiId: !Ref MyAPI DeploymentId: !Ref Deployment Description: "test stage description" MethodSettings: - ResourcePath: "/*" HttpMethod: "*" LoggingLevel: INFO AccessLogSetting: DestinationArn: !GetAtt MyLogGroup.Arn Format: $context.extendedRequestId $context.identity.sourceIp $context.identity.caller $context.identity.user [$context.requestTime] "$context.httpMethod $context.resourcePath $context.protocol" $context.status $context.responseLength $context.requestId MyLogGroup: Type: AWS::Logs::LogGroup Properties: LogGroupName: !Join - '-' - - !Ref MyAPI - access-logs ``` # Journalisation des appels d’API REST adressés à Amazon Data Firehose dans API Gateway Pour déboguer les problèmes d’accès client à votre API, vous pouvez journaliser les appels d’API adressés à Amazon Data Firehose. Pour plus d’informations sur Firehose, consultez [What Is Amazon Data Firehose?](https://docs.aws.amazon.com/firehose/latest/dev/what-is-this-service.html) Pour la journalisation des accès, vous pouvez uniquement activer CloudWatch Firehose, mais vous ne pouvez pas activer les deux. Cependant, vous pouvez activer la journalisation CloudWatch des exécutions et Firehose pour la journalisation des accès. **Topics** + [Formats des journaux Firehose pour API Gateway](#apigateway-kinesis-log-formats) + [Autorisations pour la journalisation de Firehose](#set-up-kinesis-access-logging-permissions) + [Configuration de la journalisation des accès de Firehose à l’aide de la console API Gateway](#set-up-kinesis-access-logging-using-console) ## Formats des journaux Firehose pour API Gateway [La journalisation Firehose utilise le même format que CloudWatch la journalisation.](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html) ## Autorisations pour la journalisation de Firehose Lorsque la journalisation des accès de Firehose est activée pour une étape, API Gateway crée un rôle lié à un service dans votre compte si ce rôle n’existe pas déjà. Le rôle est nommé `AWSServiceRoleForAPIGateway` et la politique gérée `APIGatewayServiceRolePolicy` lui est attachée. Pour de plus amples informations sur les rôles liés à un service, veuillez consulter [Utilisation des rôles liés à un service](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). **Note** Le nom de votre flux Firehose doit être `amazon-apigateway-{your-stream-name}`. ## Configuration de la journalisation des accès de Firehose à l’aide de la console API Gateway Pour configurer la journalisation d’API, vous devez avoir déployé l’API dans une étape. Vous devez également avoir créé un flux Firehose. 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Effectuez l’une des actions suivantes : 1. Choisissez une API existante, puis une étape. 1. Créez une API et déployez-la à une étape. 1. Dans le volet de navigation principal, choisissez **Étapes**. 1. Dans la section **Journaux et suivi**, choisissez **Modifier**. 1. Pour activer la journalisation des accès pour un flux Firehose : 1. Activez **Journalisation des accès personnalisée**. 1. Pour **ARN de destination des journaux d’accès**, entrez l’ARN d’un flux Firehose. Le format ARN est le suivant : `arn:aws:firehose:{region}:{account-id}:deliverystream/amazon-apigateway-{your-stream-name}`. **Note** Le nom de votre flux Firehose doit être `amazon-apigateway-{your-stream-name}`. 1. Pour **Format des journaux**, entrez un format de journal. Vous pouvez choisir **CLF**, **JSON**, **XML** ou **CSV**. Pour en savoir plus sur les exemples de formats de journal, consultez [CloudWatch formats de journal pour API Gateway](set-up-logging.md#apigateway-cloudwatch-log-formats). 1. Sélectionnez **Enregistrer les modifications**. API Gateway est maintenant prêt à journaliser dans Firehose les demandes adressées à votre API. Vous n’avez pas besoin de redéployer l’API lorsque vous mettez à jour les paramètres de l’étape, les journaux ou les variables de l’étape. # Variables pour la journalisation des accès pour API Gateway Dans la journalisation des accès, vous, en tant que développeur d’API, souhaitez enregistrer qui a accédé à votre API et comment l’appelant à eu accès à l’API. Vous pouvez créer votre propre groupe de journaux ou en choisir un existant, qui peut être géré par API Gateway. Pour spécifier les détails d’accès, vous pouvez utiliser les variables `$context` suivantes (sensibles à la casse). Pour obtenir la liste des variables de référence pour les transformations de données, consultez [Variables pour les transformations de données pour API Gateway](api-gateway-mapping-template-reference.md). | Paramètre | Description | | --- | --- | | \$1context.accountId | ID de AWS compte du propriétaire de l'API. | | \$1context.apiId | Identifiant qu’API Gateway attribue à votre API. | | \$1context.authorize.error | Message d’erreur d’autorisation. | | \$1context.authorize.latency | Latence d’autorisation en millisecondes. | | \$1context.authorize.status | Code de statut renvoyé à la suite d’une tentative d’autorisation. | | \$1context.authorizer.claims.property | Propriété des requêtes renvoyées depuis le groupe d’utilisateurs Amazon Cognito une fois que l’appelant de la méthode a été authentifié avec succès. Pour de plus amples informations, veuillez consulter [Contrôlez l'accès à REST APIs en utilisant les groupes d'utilisateurs Amazon Cognito comme autorisateur](apigateway-integrate-with-cognito.md). L’appel de `$context.authorizer.claims` renvoie la valeur null. | | \$1context.authorizer.error | Message d’erreur renvoyé par un mécanisme d’autorisation. | | \$1context.authorizer.integrationLatency | Latence d’intégration du mécanisme d’autorisation en millisecondes (ms). | | \$1context.authorizer.integrationStatus | Code de statut renvoyé par un mécanisme d’autorisation Lambda. | | \$1context.authorizer.latency | Latence du mécanisme d’autorisation en millisecondes (ms). | | \$1context.authorizer.principalId | Identifiant utilisateur principal associé au jeton envoyé par le client et retourné par un mécanisme d’autorisation Lambda API Gateway (anciennement appelé Custom Authorizer). Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | Valeur obtenue à l’aide de stringify de la paire clé-valeur spécifiée du mappage `context` renvoyé par une fonction du mécanisme d’autorisation Lambda API Gateway. Par exemple, si le mécanisme d’autorisation retourne le mappage `context` suivant : 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
l’appel de `$context.authorizer.key` renvoie la chaîne `"value"`, l’appel de `$context.authorizer.numKey` renvoie la chaîne `"1"` et l’appel de `$context.authorizer.boolKey` renvoie la chaîne `"true"`. En effet*property*, le seul caractère spécial pris en charge est le trait de soulignement`(_)`. Pour de plus amples informations, veuillez consulter [Utilisation des mécanismes d’autorisation Lambda API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.requestId | ID de demande du AWS point de terminaison. | | \$1context.authorizer.status | Code de statut renvoyé par un mécanisme d’autorisation. | | \$1context.authenticate.error | Message d’erreur renvoyé à la suite d’une tentative d’authentification. | | \$1context.authenticate.latency | Latence d’authentification en millisecondes. | | \$1context.authenticate.status | Code de statut renvoyé à la suite d’une tentative d’authentification. | | \$1context.awsEndpointRequestId | ID de demande du AWS point de terminaison. | | \$1context.cipherSuite | Chiffre, au format IANA, négocié lors de la prise de contact TLS entre le client et API Gateway. | | \$1context.customDomain.basePathMatched | Chemin d’accès d’un mappage d’API correspondant à une demande entrante. Applicable lorsqu’un client utilise un nom de domaine personnalisé pour accéder à une API. Par exemple, si un client envoie une demande à `https://api.example.com/v1/orders/1234` et que cette demande correspond au mappage d’API dont le chemin d’accès est `v1/orders`, la valeur est `v1/orders`. Pour en savoir plus, consultez la section [Utilisez les mappages d'API pour connecter les étapes d'API à un nom de domaine personnalisé pour REST APIs](rest-api-mappings.md). | | \$1context.customDomain.routingRuleIdMatched | Règle de routage à laquelle une demande entrante a correspondu. Applicable lorsqu’un client utilise un nom de domaine personnalisé pour accéder à une API. Pour en savoir plus, veuillez consulter la section [Règles de routage pour connecter les étapes de l'API à un nom de domaine personnalisé pour REST APIs](rest-api-routing-rules.md). | | \$1context.deploymentId | ID de déploiement de l’API. | | \$1context.domainName | Nom de domaine complet utilisé pour invoquer l’API. Il doit être identique à l’en-tête `Host` entrant. | | \$1context.domainPrefix | Première étiquette de `$context.domainName`. | | \$1context.endpointType | Type de point de terminaison de l’API. | | \$1context.error.message | Chaîne contenant un message d’erreur API Gateway. Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans la journalisation des accès. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | La valeur entre guillemets de \$1context.error.message, à savoir "\$1context.error.message". | | \$1context.error.responseType | Un [type](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Cette variable ne peut être utilisée que pour une simple substitution de variables dans un modèle de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)mappage corporel, qui n'est pas traité par le moteur Velocity Template Language, et dans la journalisation des accès. Pour plus d’informations, consultez [Surveillez WebSocket l'exécution des API à l'aide de CloudWatch métriques](apigateway-websocket-api-logging.md) et [Configuration de réponses de passerelle pour personnaliser des réponses d’erreur](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Chaîne contenant un message d’erreur de validation détaillé. | | \$1context.extendedRequestId | L’ID généré et attribué par API Gateway à la demande d’API. L’ID de requête étendu contient des informations utiles pour le débogage et le dépannage. | | \$1context.httpMethod | Méthode HTTP utilisée. Les valeurs valides sont les suivantes : `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` et `PUT`. | | \$1context.identity.accountId | L'ID de AWS compte associé à la demande. | | \$1context.identity.apiKey | Pour les méthodes d’API qui nécessitent une clé d’API, cette variable est la clé d’API associée à la demande de méthode. Pour les méthodes qui ne nécessitent aucune clé d’API, cette variable est null. Pour de plus amples informations, veuillez consulter [Plans d'utilisation et clés d'API pour REST APIs dans API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | ID de la clé d’API associé à une demande d’API qui nécessite une clé d’API. | | \$1context.identity.caller | Identifiant principal de l’appelant qui a signé la demande. Pris en charge pour les ressources qui utilisent l’autorisation IAM. | | \$1context.identity.cognitoAuthenticationProvider | Liste séparée par des virgules de tous les fournisseurs d’authentification Amazon Cognito utilisés par l’appelant à l’origine de la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Par exemple, pour une identité provenant d’un groupe d’utilisateurs Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Pour plus d’informations sur les fournisseurs d’authentification Amazon Cognito disponibles, consultez [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) dans le *Guide du développeur Amazon Cognito*. | | \$1context.identity.cognitoAuthenticationType | Type d’authentification Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. Les valeurs possibles incluent `authenticated` pour les identités authentifiées et `unauthenticated` pour les identités non authentifiées. | | \$1context.identity.cognitoIdentityId | ID d’identité Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | ID de groupe d’identités Amazon Cognito de l’appelant effectuant la demande. Disponible uniquement si la demande a été signée avec les informations d’identification Amazon Cognito. | | \$1context.identity.principalOrgId | [ID d’organisation AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | Adresse IP source de la connexion TCP immédiate envoyant la demande au point de terminaison API Gateway. | | \$1context.identity.clientCert.clientCertPem | Certificat client codé PEM présenté par le client lors de l’authentification TLS mutuelle. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. | | \$1context.identity.clientCert.subjectDN | Nom distinctif de l’objet du certificat présenté par un client. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. | | \$1context.identity.clientCert.issuerDN | Nom distinctif de l’émetteur du certificat présenté par un client. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. | | \$1context.identity.clientCert.serialNumber | Numéro de série du certificat. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. | | \$1context.identity.clientCert.validity.notBefore | Date avant laquelle le certificat n’est pas valide. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. | | \$1context.identity.clientCert.validity.notAfter | Date après laquelle le certificat n’est pas valide. Présent lorsqu’un client accède à une API à l’aide d’un nom de domaine personnalisé pour lequel l’authentification TLS mutuelle est activée. Présent uniquement dans les journaux d’accès si l’authentification TLS mutuelle échoue. | | \$1context.identity.vpcId | ID du VPC qui fait la demande au point de terminaison API Gateway. | | \$1context.identity.vpceId | ID du point de terminaison de VPC qui envoie la demande au point de terminaison API Gateway. Présent uniquement lorsque vous disposez d’une API privée. | | \$1context.identity.user | Identifiant principal de l’utilisateur qui sera autorisé à accéder aux ressources. Pris en charge pour les ressources qui utilisent l’autorisation IAM. | | \$1context.identity.userAgent | En-tête [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) de l’appelant d’API. | | \$1context.identity.userArn | ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification. Pour de plus amples informations, veuillez consulter [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.integration.error | Message d’erreur renvoyé à partir d’une intégration. | | \$1context.integration.integrationStatus | Pour l'intégration du proxy Lambda, le code d'état est renvoyé par le code de fonction Lambda principal AWS Lambda, et non par le code de fonction Lambda principal. | | \$1context.integration.latency | Latence d’intégration en millisecondes (ms). Équivalent à \$1context.integrationLatency. | | \$1context.integration.requestId | ID de demande du AWS point de terminaison. Équivalent à \$1context.awsEndpointRequestId. | | \$1context.integration.responseTransferMode | Le mode de transfert des réponses de votre intégration. Il peut correspondre à BUFFERED ou STREAMED. | | \$1context.integration.status | Code de statut renvoyé à partir d’une intégration. Pour les intégrations de proxy Lambda, code de statut que votre code de fonction Lambda renvoie. | | \$1context.integration.timeToAllHeaders | Le délai entre le moment où API Gateway établit la connexion d'intégration et le moment où il reçoit tous les en-têtes de réponse d'intégration du client. | | \$1context.integration.timeToFirstContent | Le délai entre le moment où API Gateway établit la connexion d'intégration et le moment où il reçoit les premiers octets de contenu. | | \$1context.integrationLatency | Latence d’intégration en millisecondes (ms). | | \$1context.integrationStatus | Pour l'intégration du proxy Lambda, ce paramètre représente le code d'état renvoyé par le code de fonction Lambda principal AWS Lambda, et non par le code de fonction Lambda principal. | | \$1context.isCanaryRequest | Renvoie `true` si la demande a été dirigée vers le canary et `false` si la demande n’a pas été dirigée vers le canary. Présent uniquement lorsqu’un canary a été activé. | | \$1context.path | Chemin d’accès de la demande. Par exemple, pour une URL de demande autre que de proxy de https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, la valeur \$1context.path est /\$1stage\$1/root/child. | | \$1context.protocol | Protocole de demande, par exemple, HTTP/1.1. API Gateway APIs peut accepter les requêtes HTTP/2, mais API Gateway envoie des demandes aux intégrations de backend à l'aide du protocole HTTP/1.1. Par conséquent, le protocole de requête est enregistré comme HTTP/1.1 même si un client envoie une requête qui utilise HTTP/2. | | \$1context.requestId | Un ID pour la demande. Les clients peuvent remplacer cet ID de demande. Utiliser `$context.extendedRequestId` pour un ID de demande unique généré par API Gateway. | | \$1context.requestOverride.header.header\$1name | Remplacement de l’en-tête de la requête. Si ce paramètre est défini, il contient les en-têtes à utiliser à la place des **HTTP Headers (En-têtes HTTP)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | Remplacement du chemin de la requête. Si ce paramètre est défini, il contient le chemin de requête à utiliser à la place des **URL Path Parameters (Paramètres de chemin d’URL)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | Remplacement de la chaîne d’interrogation de la requête. Si ce paramètre est défini, il contient les chaînes d’interrogation de la requête à utiliser à la place des **URL Query String Parameters (Paramètres de chaîne de requête d’URL)** qui sont définis dans le volet **Integration Request (Demande d’intégration)**. Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseLatency | Latence de la réponse en millisecondes (ms). | | \$1context.responseLength | La longueur de la charge utile de la réponse en octets. | | \$1context.responseOverride.header.header\$1name | Remplacement de l’en-tête de la réponse. Si ce paramètre est défini, il contient l’en-tête qui est renvoyé à la place du Response header (En-tête de réponse) qui est défini comme le Default mapping (Mappage par défaut) dans le volet Integration Response (Réponse d’intégration). Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | Remplacement du code de statut de la réponse. Si ce paramètre est défini, il contient le code du statut qui est renvoyé à la place du Method response status (Statut de la réponse de méthode) qui est défini comme le Default mapping (Mappage par défaut) dans le volet Integration Response (Réponse d’intégration). Pour de plus amples informations, veuillez consulter [Remplacez les paramètres de demande et de réponse et les codes d'état de votre API pour REST APIs dans API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | Durée des demandes au format [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | Heure de la demande au format [Epoch](https://en.wikipedia.org/wiki/Unix_time), en millisecondes. | | \$1context.resourceId | Identifiant attribué par API Gateway à votre ressource. | | \$1context.resourcePath | Chemin de votre ressource. Par exemple, pour l’URI de demande autre que de proxy de `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, la valeur `$context.resourcePath` est `/root/child`. Pour de plus amples informations, veuillez consulter [Didacticiel : création d’une API REST avec une intégration HTTP sans proxy](api-gateway-create-api-step-by-step.md). | | \$1context.stage | Étape de déploiement de la demande d’API (par exemple, `Beta` ou `Prod`). | | \$1context.status | Statut de la réponse de la méthode. | | \$1context.tlsVersion | Version TLS négociée lors de la prise de contact TLS entre le client et API Gateway. | | \$1context.waf.error | Le message d'erreur renvoyé par AWS WAF. | | \$1context.waf.latency | La AWS WAF latence en ms. | | \$1context.waf.status | Le code d'état renvoyé par AWS WAF. | | \$1context.xrayTraceId | ID du suivi X-Ray. Pour de plus amples informations, veuillez consulter [Configuration AWS X-Ray avec API Gateway REST APIs](apigateway-enabling-xray.md). | | \$1context.wafResponseCode | Réponse reçue de [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` ou `WAF_BLOCK`. N’est pas défini si l’étape n’est pas associée à une liste ACL web. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | ARN complet de la liste ACL web utilisée pour déterminer s’il convient d’autoriser ou de bloquer la demande. N’est pas défini si l’étape n’est pas associée à une liste ACL web. Pour de plus amples informations, veuillez consulter [AWS WAF À utiliser pour protéger votre REST APIs dans API Gateway](apigateway-control-access-aws-waf.md). | # Suivi des demandes des utilisateurs adressées aux API REST à l’aide de X-Ray dans API Gateway Vous pouvez utiliser [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) pour suivre et analyser les demandes des utilisateurs lorsqu’ils passent par vos API REST Amazon API Gateway vers les services sous-jacents. API Gateway prend en charge le suivi X-Ray pour tous les types de point de terminaison API REST Gateway : régional, optimisé pour la périphérie et privé. Vous pouvez utiliser X-Ray avec Amazon API Gateway dans toutes les Régions AWS où X-Ray est disponible. Comme X-Ray vous offre une vue de bout en bout de la totalité d’un processus de demande, vous pouvez analyser les latences de vos API et de leurs services backend. Vous pouvez utiliser une carte des services X-Ray pour afficher la latence de l’ensemble d’une demande et celle des services en aval intégrés avec X-Ray. Vous pouvez également configurer des règles d’échantillonnage pour indiquer à X-Ray les demandes à enregistrer et les taux d’échantillonnage, selon les critères que vous spécifiez. Si vous appelez une API Gateway à partir d’un service déjà en cours de suivi, API Gateway transmet le suivi, même si le suivi X-Ray n’est pas activé sur l’API. Vous pouvez activer X-Ray pour une étape d’API à l’aide de la console API Gateway, ou à l’aide de l’API API Gateway ou de l’interface de ligne de commande. **Topics** + [Configuration AWS X-Ray avec API Gateway REST APIs](apigateway-enabling-xray.md) + [Utilisez des cartes AWS X-Ray de service et des vues de traçage avec API Gateway](apigateway-using-xray-maps.md) + [Configuration des règles AWS X-Ray d'échantillonnage pour API Gateway APIs](apigateway-configuring-xray-sampling-rules.md) + [AWS X-Ray traces pour Amazon API Gateway APIs](apigateway-understanding-xray-traces.md) # Configuration AWS X-Ray avec API Gateway REST APIs Dans cette section, vous trouverez des informations détaillées sur la configuration [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html)avec API Gateway REST APIs. **Topics** + [Modes de suivi X-Ray pour API Gateway](#apigateway-tracing-modes) + [Autorisations pour le suivi X-Ray](#set-up-xray-tracing-permissions) + [Activation du suivi X-Ray dans la console API Gateway](#apigateway-xray-console-setup) + [Activation du AWS X-Ray suivi à l'aide de l'API Gateway CLI](#apigateway-xray-cli-setup) ## Modes de suivi X-Ray pour API Gateway Le chemin d’une demande via votre application est suivie avec un ID de suivi. Une trace collecte tous les segments générés par une seule requête, généralement une requête HTTP `GET` ou `POST`. Il existe deux modes de suivi pour une API API Gateway : + **Suivi passif** : il s’agit du paramètre par défaut si vous n’avez pas activé le suivi X-Ray sur une étape de l’API. Avec cette approche, l’API API Gateway est suivie uniquement si X-Ray a été activé sur un service en amont. + **Suivi actif** : lorsque ce paramètre est appliqué à une étape d’API API Gateway, API Gateway crée automatiquement des exemples de demandes d’appels d’API, en fonction de l’algorithme d’échantillonnage spécifié par X-Ray. Lorsque le suivi actif est activé sur une étape, API Gateway crée un rôle lié à un service dans votre compte, si ce rôle n’existe pas déjà. Le rôle est nommé `AWSServiceRoleForAPIGateway` et la politique gérée `APIGatewayServiceRolePolicy` lui est attachée. Pour de plus amples informations sur les rôles liés à un service, veuillez consulter [Utilisation des rôles liés à un service](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). **Note** X-Ray applique un algorithme d’échantillonnage pour s’assurer que le suivi est efficace, tout en fournissant un échantillon représentatif des demandes reçues par votre API. L’algorithme d’échantillonnage par défaut est de 1 demande par seconde, avec 5 % des demandes échantillonnées au-delà de cette limite. Vous pouvez modifier le mode de suivi de votre API à l'aide de la console de gestion API Gateway, de la CLI API Gateway ou d'un AWS SDK. ## Autorisations pour le suivi X-Ray Lorsque vous activez le suivi X-Ray sur une étape, API Gateway crée un rôle lié à un service dans votre compte, si ce rôle n’existe pas déjà. Le rôle est nommé `AWSServiceRoleForAPIGateway` et la politique gérée `APIGatewayServiceRolePolicy` lui est attachée. Pour de plus amples informations sur les rôles liés à un service, veuillez consulter [Utilisation des rôles liés à un service](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html). ## Activation du suivi X-Ray dans la console API Gateway Vous pouvez utiliser la console Amazon API Gateway pour activer le suivi actif sur une étape d’API. Cette procédure suppose que vous ayez déjà déployé l’API dans une étape. 1. Connectez-vous à la console API Gateway à l'adresse [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Choisissez votre API, puis dans le volet de navigation principal, choisissez **Étapes**. 1. Dans le volet **Étapes**, choisissez une étape. 1. Dans la section **Journaux et suivi**, choisissez **Modifier**. 1. Pour activer le suivi X-Ray, sélectionnez **Suivi X-Ray** pour activer le suivi X-Ray. 1. Sélectionnez **Enregistrer les modifications**. Une fois que vous avez activé X-Ray pour l’étape d’API, vous pouvez utiliser la console de gestion X-Ray pour afficher les suivis et les cartes de service. ## Activation du AWS X-Ray suivi à l'aide de l'API Gateway CLI La commande [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) suivante crée une étape avec un suivi X-Ray actif : ``` aws apigateway create-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --deployment-id deployment-id \ --region region \ --tracing-enabled=true ``` Le résultat se présente comme suit : ``` { "tracingEnabled": true, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} } ``` La commande [create-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-stage.html) suivante crée une étape sans suivi X-Ray actif : ``` aws apigateway create-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --deployment-id deployment-id \ --region region \ --tracing-enabled=false ``` Le résultat se présente comme suit : ``` { "tracingEnabled": false, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533849811, "createdDate": 1533849811, "methodSettings": {} } ``` La commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) suivante active le suivi X-Ray pour une API déployée : ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --patch-operations op=replace,path=/tracingEnabled,value=true ``` La commande [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) suivante désactive le suivi X-Ray pour une API déployée : ``` aws apigateway update-stage \ --rest-api-id rest-api-id \ --stage-name stage-name \ --region region \ --patch-operations op=replace,path=/tracingEnabled,value=false ``` Le résultat se présente comme suit : ``` { "tracingEnabled": false, "stageName": stage-name, "cacheClusterEnabled": false, "cacheClusterStatus": "NOT_AVAILABLE", "deploymentId": deployment-id, "lastUpdatedDate": 1533850033, "createdDate": 1533849811, "methodSettings": {} } ``` Une fois que vous avez activé X-Ray pour l’étape d’API, utilisez l’interface de ligne de commande X-Ray pour récupérer les informations de suivi. Pour plus d'informations, consultez la section [Utilisation de l'API X-Ray avec la AWS CLI](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-tutorial). # Utilisez des cartes AWS X-Ray de service et des vues de traçage avec API Gateway Dans cette section, vous trouverez des informations détaillées sur l’utilisation des cartes de service et des vues de suivi [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-apigateway.html) avec API Gateway. **Topics** + [Exemple de carte de service X-Ray](#apigateway-using-xray-maps-active) + [Exemple de vue de suivi X-Ray](#apigateway-using-xray-trace-view-active) ## Exemple de carte de service X-Ray AWS X-Ray les cartes de service affichent des informations sur votre API et tous ses services en aval. Quand X-Ray est activé pour une étape d’API dans API Gateway, un nœud contenant des informations sur le temps total passé dans le service API Gateway s’affiche dans la carte de service. Vous pouvez obtenir des informations détaillées sur le statut de réponse et un histogramme du temps de réponse de l’API pour la période sélectionnée. Pour APIs l'intégration à AWS des services tels qu' AWS Lambda Amazon DynamoDB, vous verrez davantage de nœuds fournissant des indicateurs de performance liés à ces services. Une cartographie des services est disponible pour chaque étape de l’API. L’exemple suivant montre une cartographie des services pour l’étape `test` d’une API appelée `xray`. Cette API possède deux intégrations Lambda. Les nœuds représentent le service API Gateway et les deux fonctions Lambda. Pour une explication détaillée de la structure des cartes de service, consultez [Use the X-Ray trace map](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-servicemap). ![\[Exemple de carte de service d’une étape d’API API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-xray-servicemap-2.png) Depuis la cartographie des services, vous pouvez zoomer afin de consulter un suivi de votre étape d’API. Le suivi affiche des informations détaillées concernant votre API, sous la forme de segments et de sous-segments. Par exemple, le suivi de la carte de service présentée ci-dessus inclut des segments pour le service Lambda et la fonction Lambda. Pour plus d'informations, reportez-vous [AWS Lambda aux sections et AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html). Si vous sélectionnez un nœud ou un arc sur une carte de service X-Ray, la console X-Ray affiche un histogramme de distribution des latences. Vous pouvez utiliser un histogramme de latence pour voir de combien de temps a besoin un service pour traiter ses requêtes. Voici un histogramme de l’étape d’API Gateway nommée `xray/test` dans la précédente carte de service. Pour obtenir une explication détaillée des histogrammes de distribution des latences, consultez [Use Latency Histograms](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-histograms). ![\[Histogramme X-Ray d’une étape d’API API Gateway\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-xray-histogram-1.png) ## Exemple de vue de suivi X-Ray Le schéma suivant présente une vue du suivi générée pour l’exemple d’API décrit ci-dessus, avec une fonction de backend Lambda. Une demande de méthode d’API réussie s’affiche avec le code de réponse 200. Pour obtenir une explication détaillée des vues de suivi, consultez [View traces and trace details](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-traces). ![\[API Gateway avec suivi actif activé\]](http://docs.aws.amazon.com/fr_fr/apigateway/latest/developerguide/images/apigateway-xray-traceview-1.png) # Configuration des règles AWS X-Ray d'échantillonnage pour API Gateway APIs Vous pouvez utiliser AWS X-Ray la console ou le SDK pour configurer les règles d'échantillonnage pour votre API Amazon API Gateway. Une règle d’échantillonnage spécifie quelles demandes X-Ray doit enregistrer pour votre API. En personnalisant les règles d’échantillonnage, vous pouvez contrôler la quantité de données que vous enregistrez, et modifier le comportement d’échantillonnage à la volée, sans modifier ni redéployer votre code. Avant de spécifier vos règles d’échantillonnage X-Ray, consultez les rubriques suivantes dans le Guide du développeur X-Ray : + [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling) + [Utilisation de règles d’échantillonnage avec l’API X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-sampling) **Topics** + [Valeurs des options des règles d'échantillonnage X-Ray pour API Gateway APIs](#apigateway-xray-sampling-rule-options) + [Exemples de règles d’échantillonnage X-Ray](#apigateway-xray-sampling-rules-examples) ## Valeurs des options des règles d'échantillonnage X-Ray pour API Gateway APIs Les options d’échantillonnage X-Ray suivantes sont pertinentes pour API Gateway. Les valeurs de chaîne peuvent comporter des caractères génériques pour correspondre à un seul caractère (?) ou à zéro caractère ou plus (\$1). Pour obtenir de plus amples informations et une explication détaillée de l’utilisation des paramètres **Réservoir** et **Fréquence**, consultez [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). + **Rule name (Nom de la règle)** (chaîne) : nom unique de la règle. + **Priority (Priorité)** (nombre entier compris entre 1 et 9999) : priorité de la règle d’échantillonnage. Les services évaluent les règles dans l’ordre croissant de priorité, et prennent une décision d’échantillonnage avec la première règle correspondante. + **Reservoir (Réservoir)** (entier non négatif) : nombre fixe de demandes correspondantes à instrumenter par seconde, avant d’appliquer la fréquence fixe. Le réservoir n’est pas utilisé directement par les services, mais s’applique à tous les services qui utilisent la règle collectivement. + **Rate (Fréquence)** (nombre compris entre 0 et 100) : pourcentage de demandes correspondantes à instrumenter une fois que le réservoir est épuisé. + **Service name (Nom du service)** (chaîne) : nom de l’étape d’API, sous la forme ***\$1api-name\$1*/*\$1stage-name\$1***. Par exemple, si vous deviez déployer l'[PetStore](api-gateway-create-api-from-example.md)exemple d'API sur une étape nommée`test`, la valeur du **nom de service** à spécifier dans votre règle d'échantillonnage serait**pets/test**. + **Service type (Type de service)** (chaîne) : pour une API API Gateway, vous pouvez spécifier **AWS::ApiGateway::Stage** ou **AWS::ApiGateway::\$1**. + **Host (Hôte)** (chaîne) : nom d’hôte de l’en-tête d’hôte HTTP. Définissez cette valeur sur **\$1** pour l’associer à tous les noms d’hôte. Vous pouvez également spécifier tout ou partie d’un nom d’hôte pour le faire correspondre (par exemple, **api.example.com** ou **\$1.example.com**). + **Resource ARN (ARN de la ressource)** (chaîne) : ARN de l’étape de l’API, au format  ; par exemple, **arn:aws:apigateway:*region*::/restapis/*api-id*/stages/*stage-name***. Le nom de l’étape peut être obtenu à partir de la console ou de l’interface de ligne de commande ou de l’API API Gateway. Pour plus d’informations sur les formats ARN, consultez [Référence générale d'Amazon Web Services](https://docs.aws.amazon.com/general/latest/gr/). + **HTTP method (Méthode HTTP)** (chaîne) : la méthode à échantillonner (par exemple, **GET**). + **URL path** (Chemin URL) (chaîne) : chemin URL de la demande. + (facultatif) **Attributes (Attributs)** (clé et valeur) : en-têtes de la demande HTTP d’origine (par exemple, **Connection**, **Content-Length** ou **Content-Type**). Chaque attribut peut contenir jusqu’à 32 caractères. ## Exemples de règles d’échantillonnage X-Ray **Exemple de règle d’échantillonnage n°1** Cette règle échantillonne toutes les requêtes `GET` pour l’API `testxray` à l’étape `test`. + **Nom de la règle — ****test-sampling** + **Priorité — ****17** + **Taille du réservoir — ****10** + **Fréquence fixe — ****10** + **Nom du service — ****testxray/test** + **Type de service — ****AWS::ApiGateway::Stage** + **Méthode HTTP — ****GET** + **ARN de la ressource — ****\$1** + **Hôte — ****\$1** **Exemple de règle d’échantillonnage n°2** Cette règle échantillonne toutes les requêtes pour l’API `testxray` à l’étape `prod`. + **Nom de la règle — ****prod-sampling** + **Priorité — ****478** + **Taille du réservoir — ****1** + **Fréquence fixe — ****60** + **Nom du service — ****testxray/prod** + **Type de service — ****AWS::ApiGateway::Stage** + **Méthode HTTP — ****\$1** + **ARN de la ressource — ****\$1** + **Hôte — ****\$1** + **Attributs** — **\$1\$1** # AWS X-Ray traces pour Amazon API Gateway APIs Cette section décrit les segments de AWS X-Ray trace, les sous-segments et les autres champs de suivi pour Amazon API Gateway APIs. Avant de lire cette section, consultez les rubriques suivantes dans le Guide du développeur X-Ray : + [Utilisez un AWS Management Console](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html) + [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments) + [Concepts](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html#xray-concepts) **Topics** + [Exemples d’objets de suivi pour une API API Gateway](#apigateway-understanding-xray-traces-example-segments) + [Présentation des suivis](#apigateway-understanding-xray-traces-segments) ## Exemples d’objets de suivi pour une API API Gateway Cette section décrit quelques-uns des objets que vous pouvez voir dans le suivi d’une API API Gateway. **Annotations** Des annotations peuvent s’afficher dans les segments et les sous-segments. Elles sont utilisées comme expressions de filtrage dans les règles d’échantillonnage pour filtrer les suivis. Pour plus d’informations, consultez [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). Voici un exemple d’objet `annotations`, dans lequel une étape d’API est identifiée par l’ID d’API et le nom de l’étape d’API : ``` "annotations": { "aws:api_id": "a1b2c3d4e5", "aws:api_stage": "dev" } ``` Pour plus d’informations sur les annotations, consultez [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments), puis choisissez **Documents de segment X-Ray**, **Annotations**. **AWS données sur les ressources** L'objet `aws` s'affiche uniquement dans des segments. Voici un exemple d’objet qui `aws` correspondant à la règle d’échantillonnage par défaut. Pour une explication approfondie des règles d’échantillonnage, consultez [Configure sampling rules](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-sampling). ``` "aws": { "xray": { "sampling_rule_name": "Default" }, "api_gateway": { "account_id": "123412341234", "rest_api_id": "a1b2c3d4e5", "stage": "dev", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } } ``` Pour plus d’informations sur l’objet `aws`, consultez [X-Ray segment documents](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments), puis choisissez **Documents de segment X-Ray**, **Données de ressources AWS **. ## Présentation des suivis Voici un segment de suivi pour une étape d’API Gateway. Pour obtenir une explication détaillée des champs qui constituent le segment de suivi, consultez [Documents de segment X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-api.html#xray-api-segmentdocuments). ``` { "Document": { "id": "a1b2c3d4a1b2c3d4", "name": "testxray/dev", "start_time": 1533928226.229, "end_time": 1533928226.614, "metadata": { "default": { "extended_request_id": "abcde12345abcde=", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } }, "http": { "request": { "url": "https://example.com/dev?username=demo&message=hellofromdemo/", "method": "GET", "client_ip": "192.0.2.0", "x_forwarded_for": true }, "response": { "status": 200, "content_length": 0 } }, "aws": { "xray": { "sampling_rule_name": "Default" }, "api_gateway": { "account_id": "123412341234", "rest_api_id": "a1b2c3d4e5", "stage": "dev", "request_id": "a1b2c3d4-a1b2-a1b2-a1b2-a1b2c3d4e5f6" } }, "annotations": { "aws:api_id": "a1b2c3d4e5", "aws:api_stage": "dev" }, "trace_id": "1-a1b2c3d4-a1b2c3d4a1b2c3d4a1b2c3d4", "origin": "AWS::ApiGateway::Stage", "resource_arn": "arn:aws:apigateway:us-east-1::/restapis/a1b2c3d4e5/stages/dev", "subsegments": [ { "id": "abcdefgh12345678", "name": "Lambda", "start_time": 1533928226.233, "end_time": 1533928226.6130002, "http": { "request": { "url": "https://example.com/2015-03-31/functions/arn:aws:lambda:us-east-1:123412341234:function:xray123/invocations", "method": "GET" }, "response": { "status": 200, "content_length": 62 } }, "aws": { "function_name": "xray123", "region": "us-east-1", "operation": "Invoke", "resource_names": [ "xray123" ] }, "namespace": "aws" } ] }, "Id": "a1b2c3d4a1b2c3d4" } ```