Configuration de la journalisation pour les API WebSocket dans API Gateway - Amazon API Gateway

Configuration de la journalisation pour les API WebSocket dans API Gateway

Vous pouvez activer la journalisation pour écrire des journaux dans CloudWatch Logs. Il existe deux types de journalisation d’API dans Amazon CloudWatch : la journalisation des exécutions et celle des accès. Dans la journalisation des exécutions, API Gateway gère CloudWatch Logs. 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.

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 sélectionnez des variables $context (exprimées au format de votre choix) et vous choisissez un groupe de journaux comme destination.

Pour obtenir des instructions sur la configuration de la journalisation CloudWatch, consultez Configuration de la journalisation de l’API CloudWatch à l’aide de la console API Gateway.

Lorsque vous spécifiez Log Format (Format de journal), vous pouvez choisir les variables de contexte à journaliser. Les variables suivantes sont prises en charge.

Paramètre Description
$context.apiId

Identifiant qu’API Gateway attribue à votre API.
$context.authorize.error Message d’erreur d’autorisation.
$context.authorize.latency Latence d’autorisation en millisecondes.
$context.authorize.status Code de statut renvoyé à la suite d’une tentative d’autorisation.
$context.authorizer.error Message d’erreur renvoyé par un mécanisme d’autorisation.
$context.authorizer.integrationLatency Latence de l’autorisation Lambda en ms.
$context.authorizer.integrationStatus Code de statut renvoyé par un mécanisme d’autorisation Lambda.
$context.authorizer.latency Latence du mécanisme d’autorisation en millisecondes (ms).
$context.authorizer.requestId L’ID de demande du point de terminaison AWS.
$context.authorizer.status Code de statut renvoyé par un mécanisme d’autorisation.
$context.authorizer.principalId

L’identifiant utilisateur principal qui est associé au jeton envoyé par le client et retourné par une fonction Lambda du mécanisme d’autorisation API Gateway Lambda. (Un mécanisme d’autorisation Lambda était auparavant connu sous le nom de mécanisme d’autorisation personnalisé.)
$context.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".
$context.authenticate.error Message d’erreur renvoyé à la suite d’une tentative d’authentification.
$context.authenticate.latency Latence d’authentification en millisecondes.
$context.authenticate.status Code de statut renvoyé à la suite d’une tentative d’authentification.
$context.connectedAt

Temps de connexion au format Epoch.
$context.connectionId

ID unique pour la connexion qui peut être utilisé pour effectuer un rappel au client.
$context.domainName

Nom de domaine de l’API WebSocket. Ce nom peut être utilisé pour effectuer un rappel au client (au lieu d’une valeur codée en dur).
$context.error.message

Chaîne contenant un message d’erreur API Gateway.
$context.error.messageString La valeur entre guillemets de $context.error.message, à savoir "$context.error.message".
$context.error.responseType

Type de réponse d’erreur.
$context.error.validationErrorString

Chaîne contenant un message d’erreur de validation détaillé.
$context.eventType

Type d’événement : CONNECT, MESSAGE ou DISCONNECT.
$context.extendedRequestId Équivalent à $context.requestId.
$context.identity.accountId

ID de compte AWS associé à la demande.
$context.identity.apiKey

Clé du propriétaire d’API associée à la demande d’API activée par clé.
$context.identity.apiKeyId ID de clé du propriétaire d’API associée à la demande d’API activée par clé
$context.identity.caller

Identifiant principal de l’appelant qui a signé la demande. Pris en charge pour les routes qui utilisent l’autorisation IAM.
$context.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 pool 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 dans le Guide du développeur Amazon Cognito.
$context.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.
$context.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.
$context.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.
$context.identity.principalOrgId

ID d’organisation AWS. Pris en charge pour les routes qui utilisent l’autorisation IAM.
$context.identity.sourceIp

Adresse IP source de la connexion TCP envoyant la demande à API Gateway.
$context.identity.user

Identifiant principal de l’utilisateur qui sera autorisé à accéder aux ressources. Pris en charge pour les routes qui utilisent l’autorisation IAM.
$context.identity.userAgent

Agent utilisateur de l’appelant de l’API.
$context.identity.userArn

ARN (Amazon Resource Name) de l’utilisateur identifié après l’authentification.
$context.integration.error Message d’erreur renvoyé à partir d’une intégration.
$context.integration.integrationStatus Pour l’intégration de proxy Lambda, le code de statut est renvoyé par AWS Lambda et non par le code de fonction Lambda du backend.
$context.integration.latency Latence d’intégration en millisecondes (ms). Équivalent à $context.integrationLatency.
$context.integration.requestId L’ID de demande du point de terminaison AWS. Équivalent à $context.awsEndpointRequestId.
$context.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. Équivalent à $context.integrationStatus.
$context.integrationLatency Latence d’intégration en ms, disponible pour la journalisation des accès uniquement.
$context.messageId

ID côté serveur unique pour un message. Uniquement disponible lorsque $context.eventType est défini sur MESSAGE.
$context.requestId

Identique à $context.extendedRequestId.
$context.requestTime Durée des demandes au format CLF (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch Heure de la demande au format Epoch, en millisecondes.
$context.routeKey

Clé de routage sélectionnée.
$context.stage

Étape de déploiement de l’appel d’API (par exemple, bêta ou production).
$context.status

Statut de la réponse.
$context.waf.error Le message d’erreur renvoyé par AWS WAF.
$context.waf.latency La latence AWS WAF en millisecondes.
$context.waf.status Le code de statut renvoyé par AWS WAF.

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.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId

    Les caractères de continuation (\) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (\n) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.

  • JSON: 

    {
"requestId":"$context.requestId", \
"ip": "$context.identity.sourceIp", \
"caller":"$context.identity.caller", \
"user":"$context.identity.user", \
"requestTime":"$context.requestTime", \
"eventType":"$context.eventType", \
"routeKey":"$context.routeKey", \
"status":"$context.status", \
"connectionId":"$context.connectionId"
}

    Les caractères de continuation (\) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (\n) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.

  • XML: 

    <request id="$context.requestId"> \
 <ip>$context.identity.sourceIp</ip> \
 <caller>$context.identity.caller</caller> \
 <user>$context.identity.user</user> \
 <requestTime>$context.requestTime</requestTime> \
 <eventType>$context.eventType</eventType> \
 <routeKey>$context.routeKey</routeKey> \
 <status>$context.status</status> \
 <connectionId>$context.connectionId</connectionId> \
</request>

    Les caractères de continuation (\) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (\n) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.

  • CSV (valeurs séparées par des virgules) :

    $context.identity.sourceIp,$context.identity.caller, \
$context.identity.user,$context.requestTime,$context.eventType, \
$context.routeKey,$context.connectionId,$context.status, \
$context.requestId

    Les caractères de continuation (\) sont destinés à être une aide visuelle. Le format du journal doit être une seule ligne. Vous pouvez ajouter un caractère de nouvelle ligne (\n) à la fin du format du journal pour inclure une nouvelle ligne à la fin de chaque entrée du journal.