View a markdown version of this page

Journalisation des accès pour les API REST - Amazon API Gateway
Formats de journal d'accèsConfigurer la journalisation des accès à l'aide de la console API GatewayConfigurez la journalisation des accès à l'aide CloudFormation

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.

Journalisation des accès pour les API REST

Dans la journalisation des accès, vous enregistrez qui a accédé à votre API et comment l'appelant a accédé à l'API. Vous pouvez créer votre propre groupe de journaux ou choisir un groupe de journaux existant. Pour spécifier les détails d’accès, vous devez sélectionner des variables $context, un format de journal et une destination de groupe de journaux.

Formats de journal d'accès

Le format du journal d’accès doit inclure au moins $context.requestId ou $context.extendedRequestId. Il est recommandé d'inclure les deux 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 ID de demande écrasés qui ne sont pas au format UUID par 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 vous aider à résoudre les problèmes liés à votre API. Pour plus d’informations, consultez Variables pour la journalisation des accès pour API Gateway.

Choisissez un format de journal également adopté par votre backend analytique, comme Common Log Format (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 accessLogSettings/destinationArn propriété de la scène. 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 un format choisi dans la accessLogSetting/format propriété de la scène.

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

    $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

Configurer la journalisation des accès à l'aide de la console API Gateway

Avant de configurer la journalisation des accès, déployez l'API sur une étape et configurez un ARN de rôle CloudWatch Logs approprié pour votre compte.

  1. Connectez-vous à la console API Gateway à l'adresse https://console.aws.amazon.com/apigateway.

  2. Dans le volet de navigation principal, choisissez API, puis effectuez l’une des opérations suivantes :

    1. Choisissez une API existante, puis une étape.

    2. Créez une API et déployez-la dans une étape.

  3. Dans le volet de navigation principal, choisissez Étapes.

  4. Dans la section Journaux et suivi, choisissez Modifier.

  5. Activez Journalisation des accès personnalisée.

  6. 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.

  7. 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 Formats de journal d'accès.

  8. Cliquez sur Enregistrer les modifications.

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.

Configurez la journalisation des accès à l'aide CloudFormation

Utilisez l'exemple de CloudFormation modèle suivant pour créer un groupe de CloudWatch journaux Amazon Logs et configurer la journalisation 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 dans le Guide de l’utilisateur AWS CloudFormation .

  TestStage:
    Type: AWS::ApiGateway::Stage
    Properties:
      StageName: test
      RestApiId: !Ref MyAPI
      DeploymentId: !Ref Deployment
      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