Configurer la CloudWatch journalisation REST APIs dans API Gateway - APIPasserelle Amazon
CloudWatch formats de journal pour API GatewayAutorisations pour la CloudWatch journalisationConfiguration de la CloudWatch API journalisation à l'aide de la console API GatewayConfigurer la CloudWatch API journalisation à l'aide de AWS 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.

Configurer la CloudWatch journalisation REST APIs dans API Gateway

Pour résoudre les problèmes liés à l'exécution des demandes ou à l'accès client à votre compteAPI, vous pouvez activer Amazon CloudWatch Logs pour enregistrer les API appels. Pour plus d'informations sur CloudWatch, voirSurveillez REST API l'exécution avec CloudWatch les métriques Amazon.

CloudWatch formats de journal pour API Gateway

Il existe deux types de API connexion CloudWatch : la journalisation des exécutions 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 enregistrées incluent les erreurs ou les traces d'exécution (telles que les valeurs des paramètres de demande ou de réponse ou les charges utiles), les données utilisées par les autorisateurs Lambda (anciennement appelés autorisateurs personnalisés), API si les clés sont requises, si les plans d'utilisation sont activés, et d'autres informations. APIGateway expédie les en-têtes d'autorisation, les valeurs API clés et les paramètres de demande sensibles similaires à partir des données enregistrées.

Lorsque vous déployez unAPI, API Gateway crée un groupe de journaux et des flux de journaux sous le groupe 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 API développeur, souhaitez enregistrer qui a accédé à votre compte API et comment l'appelant a accédé auAPI. Vous pouvez créer votre propre groupe de journaux ou choisir un groupe de journaux existant qui pourrait être géré par API Gateway. Pour spécifier les détails d'accès, vous sélectionnez $contextdes variables, 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. La meilleure pratique consiste à inclure $context.requestId et $context.extendedRequestId dans le format de votre journal.

$context.requestId

Cela enregistre la valeur dans l'x-amzn-RequestIden-tête. Les clients peuvent remplacer la valeur de l'x-amzn-RequestIden-tête par une valeur au format d'identifiant unique universel (UUID). APIGateway renvoie cet ID de demande dans l'en-tête de x-amzn-RequestId réponse. APIGateway remplace les demandes remplacées IDs qui n'ont pas le format d'un UUID with UUID_REPLACED_INVALID_REQUEST_ID dans vos journaux d'accès.

$context.extendedRequestId

L'extendedRequestID est un identifiant unique généré par API Gateway. APIGateway renvoie cet ID de demande dans l'en-tête de x-amz-apigw-id réponse. Un API appelant ne peut pas fournir ou remplacer cet ID de demande. Vous devrez peut-être fournir cette valeur au AWS Support pour vous aider à résoudre votre API problème. Pour de plus amples informations, veuillez consulter $contextVariables pour les modèles de données, les autorisateurs, les modèles de mappage et la journalisation des CloudWatch accès.

Note

Seules $context les variables sont prises en charge.

Choisissez un format de journal également adopté par votre backend analytique, tel que Common Log Format (CLF), JSONXML, 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 le groupe de journaux ARN sur la destinationArn propriété accessLogSettings/sur la scène. Vous pouvez obtenir un groupe de journaux ARN 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 de la scène.

Des exemples de formats de journaux d'accès couramment utilisés sont présentés dans la console API Gateway et sont répertoriés comme suit.

  • 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

Autorisations pour la CloudWatch journalisation

Pour activer CloudWatch les journaux, vous devez autoriser API Gateway à lire et à écrire les journaux CloudWatch de votre compte. La politique AmazonAPIGatewayPushToCloudWatchLogs gérée (avec un ARN dearn:aws:iam::aws:policy/service-role/AmazonAPIGatewayPushToCloudWatchLogs) dispose de toutes les autorisations requises :

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:PutLogEvents",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "*"
        }
    ]
}
Note

APIGateway appelle AWS Security Token Service pour assumer le IAM rôle, alors assurez-vous qu'il AWS STS est activé pour la région. Pour plus d'informations, consultez la section Gestion AWS STS dans une AWS région.

Pour accorder ces autorisations à votre compte, créez un IAM rôle avec apigateway.amazonaws.com comme entité de confiance, associez la politique précédente au IAM rôle et définissez le IAM rôle ARN sur la propriété cloudWatchRoleArn de votre compte. Vous devez définir la cloudWatchRolepropriété Arn séparément pour chaque AWS région dans laquelle vous souhaitez activer CloudWatch les journaux.

Si un message d'erreur s'affiche lors de la définition du IAM rôleARN, 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 AWS STS dans une AWS région du Guide de IAM l'utilisateur.

Configuration de la CloudWatch API journalisation à l'aide de la console API Gateway

Pour configurer la CloudWatch API journalisation, vous devez avoir déployé le API sur une étape. Vous devez également avoir configuré un rôle CloudWatch Logs approprié ARN 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 Paramètres, puis sous Journalisation, choisissez Modifier.

  3. Pour le rôle ARN du CloudWatch journal ARN, entrez un IAM rôle doté des autorisations appropriées. Vous devez le faire une fois pour chaque création Compte AWS à APIs l'aide de API Gateway.

  4. Dans le volet de navigation principal, choisissez APIs, puis effectuez l'une des opérations suivantes :

    1. Choisissez une étape existanteAPI, puis choisissez une étape.

    2. Créez unAPI, puis déployez-le sur une scène.

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

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

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

    2. (Facultatif) Sélectionnez Suivi des données pour activer l'enregistrement du suivi des données pour votre scène. Cela peut être utile pour résoudre les problèmesAPIs, 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 productionAPIs.

    3. (Facultatif) Sélectionnez Mesures détaillées pour activer les CloudWatch mesures détaillées.

    Pour plus d'informations sur CloudWatch les métriques, consultezSurveillez REST API l'exécution avec CloudWatch les métriques Amazon.

  8. Pour activer la journalisation des accès :

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

    2. Pour la destination du journal d'accès ARN, entrez le nom ARN d'un groupe de journaux. Le ARN format estarn:aws:logs:{region}:{account-id}:log-group:log-group-name.

    3. Dans Format des journaux, entrez un format de journal. Vous pouvez choisir CLFJSON, XML, ou CSV. Pour en savoir plus sur les exemples de formats de journal, consultez CloudWatch formats de journal pour API Gateway.

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

APIGateway est maintenant prêt à enregistrer les demandes adressées à votreAPI. Vous n'avez pas besoin de le redéployer API lorsque vous mettez à jour les paramètres, les journaux ou les variables d'étape.

Configurer la CloudWatch API journalisation à l'aide de AWS CloudFormation

Utilisez l'exemple de AWS 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 la section Associer un compte à IAM un rôle dans le Guide de AWS CloudFormation l'utilisateur.

  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