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.

# Configuration de la CloudWatch journalisation pour REST APIs dans API Gateway
<a name="set-up-logging"></a>

 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
<a name="apigateway-cloudwatch-log-formats"></a>

 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`: 

  ```
  <request id="$context.requestId"> <extendedRequestId>$context.extendedRequestId</extendedRequestId> <ip>$context.identity.sourceIp</ip> <caller>$context.identity.caller</caller> <user>$context.identity.user</user> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <resourcePath>$context.resourcePath</resourcePath> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> </request>
  ```
+ `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
<a name="set-up-access-logging-permissions"></a>

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
<a name="set-up-access-logging-using-console"></a>

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
<a name="set-up-access-logging-using-cloudformation"></a>

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
```