Configuration de la journalisation pour WebSocket les API dans API Gateway

Vous pouvez activer la journalisation pour écrire des CloudWatch journaux dans Logs. 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.

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 CloudWatch journalisation, consultezConfiguration de la journalisation des CloudWatch API à 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 d'état 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 d'état renvoyé par un mécanisme d'autorisation Lambda.
$context.authorizer.latency	Latence du mécanisme d'autorisation en millisecondes (ms).
$context.authorizer.requestId	ID de demande du AWS point de terminaison.
$context.authorizer.status	Code d'état 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 d'état 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 pour l' WebSocket API. 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	L'ID de AWS compte 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 la section Utilisation des identités fédérées dans le manuel Amazon Cognito Developer Guide.
$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 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.
$context.integration.latency	Latence d'intégration en millisecondes (ms). Équivalent à $context.integrationLatency.
$context.integration.requestId	ID de demande du AWS point de terminaison. Équivalent à $context.awsEndpointRequestId.
$context.integration.status	Code d'état renvoyé à partir d'une intégration. Pour les intégrations de proxy Lambda, code d'état 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 AWS WAF latence en ms.
$context.waf.status	Le code d'état 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.