Configuración del registro para una API de WebSocket - Amazon API Gateway

Configuración del registro para una API de WebSocket

Puede habilitar el registro para escribir registros en CloudWatch Logs. Existen dos tipos de registro de API en CloudWatch: los registros de ejecución y los registros de acceso. En el registro de ejecución, API Gateway administra los CloudWatch Logs. El proceso incluye la creación de grupos y flujos de registros y la notificación a los flujos de registro de las solicitudes y respuestas del intermediario.

En los registros de acceso, tanto usted como el desarrollador de la API pretenden registrar quién ha obtenido acceso a la API y cómo el intermediario ha obtenido acceso a la API. Puede crear su propio grupo de registros o elegir un grupo de registros existente, que podría administrarse a través de API Gateway. Para especificar los detalles de acceso, seleccione variables $context (expresadas en un formato que elija) y elija un grupo de registro como destino.

Para ver instrucciones sobre cómo configurar el registro de CloudWatch, consulte Configuración del registro de API de CloudWatch mediante la consola de API Gateway.

Al especificar el Log Format (Formato de registro), puede elegir las variables de contexto que deben registrarse. Se admiten las siguientes variables.

Parámetro Descripción
$context.apiId

El identificador que API Gateway asigna a su API.
$context.authorize.error El mensaje de error de autorización.
$context.authorize.latency La latencia de autorización en ms.
$context.authorize.status El código de estado devuelto por un intento de autorización.
$context.authorizer.error El mensaje de error devuelto por un autorizador.
$context.authorizer.integrationLatency La latencia del autorizador de Lambda en ms.
$context.authorizer.integrationStatus El código de estado que devuelve un autorizador de Lambda.
$context.authorizer.latency La latencia del autorizador en ms.
$context.authorizer.requestId El ID de solicitud del punto de enlace de AWS.
$context.authorizer.status El código de estado devuelto por un autorizador.
$context.authorizer.principalId

La identificación de usuario principal que está asociada con el token que envía el cliente y devuelve la función de Lambda del autorizador personalizado de Lambda de API Gateway. (El autorizador de Lambda se conocía anteriormente como “autorizador personalizado”).
$context.authorizer.property

El valor en forma de cadena del par clave-valor especificado de la asignación context que devuelve la función de Lambda del autorizador de Lambda de API Gateway. Por ejemplo, si el autorizador devuelve la siguiente asignación de context: 

"context" : {
                            "key": "value",
                            "numKey": 1,
                            "boolKey": true
                            }

la llamada a $context.authorizer.key devuelve la cadena "value", la llamada a $context.authorizer.numKey devuelve la cadena "1" y la llamada a $context.authorizer.boolKey devuelve la cadena "true".
$context.authenticate.error El mensaje de error devuelto por un intento de autorización.
$context.authenticate.latency La latencia de autenticación en ms.
$context.authenticate.status El código de estado devuelto por un intento de autenticación.
$context.connectedAt

Hora de la conexión en formato de tiempo Unix.
$context.connectionId

Identificador único para la conexión que se puede utilizar para realizar una devolución de llamada al cliente.
$context.domainName

Nombre de dominio para la API de WebSocket. Se puede utilizar para realizar una devolución de llamada al cliente (en lugar de un valor de código rígido).
$context.error.message

Una cadena que contiene un mensaje de error de API Gateway.
$context.error.messageString El valor entrecomillado de $context.error.message, es decir, "$context.error.message".
$context.error.responseType

El tipo de respuesta de error.
$context.error.validationErrorString

Una cadena que contiene un mensaje de error de validación detallado.
$context.eventType

El tipo de evento: CONNECT, MESSAGE o DISCONNECT.
$context.extendedRequestId Es igual que $context.requestId.
$context.identity.accountId

El ID de cuenta de AWS asociado con la solicitud.
$context.identity.apiKey

Clave del propietario de API asociada a la solicitud de API habilitada para claves.
$context.identity.apiKeyId ID de clave de API asociado a la solicitud de API habilitada para claves
$context.identity.caller

El identificador principal del intermediario que firmó la solicitud. Compatible con rutas que utilizan la autorización de IAM.
$context.identity.cognitoAuthenticationProvider

Una lista separada por comas de los proveedores de autenticación de Amazon Cognito utilizados por el intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito.

Por ejemplo, para una identidad de un grupo de usuarios de Amazon Cognito, cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim

Consulte Uso de las identidades federadas en la guía para desarrolladores de Amazon Cognito para obtener más información.
$context.identity.cognitoAuthenticationType

El tipo de autenticación de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito. Los valores posibles incluyen authenticated para identidades autenticadas y unauthenticated para identidades no autenticadas.
$context.identity.cognitoIdentityId

El ID de identidad de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito.
$context.identity.cognitoIdentityPoolId

El ID del grupo de identidades de Amazon Cognito del intermediario que realiza la solicitud. Solo está disponible si la solicitud se firmó con las credenciales de Amazon Cognito.
$context.identity.principalOrgId

El ID de organización de AWS. Compatible con rutas que utilizan la autorización de IAM.
$context.identity.sourceIp

La dirección IP de origen de la conexión TCP que realiza la solicitud de API Gateway.
$context.identity.user

El identificador principal del usuario que se autorizará a acceder al recurso. Compatible con rutas que utilizan la autorización de IAM.
$context.identity.userAgent

El agente de usuario del intermediario de la API.
$context.identity.userArn

El Nombre de recurso de Amazon (ARN) del usuario identificado después de la autenticación.
$context.integration.error El mensaje de error devuelto por una integración.
$context.integration.integrationStatus Para la integración de proxy de Lambda, el código de estado que devuelve AWS Lambda, en lugar del código de función de Lambda del backend.
$context.integration.latency La latencia de integración en ms. Es igual que $context.integrationLatency.
$context.integration.requestId El ID de solicitud del punto de enlace de AWS. Es igual que $context.awsEndpointRequestId.
$context.integration.status El código de estado devuelto por una integración. Para integraciones de proxy de Lambda, este es el código de estado que devuelve su código de la función de Lambda. Es igual que $context.integrationStatus.
$context.integrationLatency La latencia de integración en ms, disponible únicamente para el registro de acceso.
$context.messageId

Un ID único del lado del servidor para un mensaje. Solo está disponible si $context.eventType es MESSAGE.
$context.requestId

Igual que $context.extendedRequestId.
$context.requestTime Hora de la solicitud en formato CLF-(dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch Hora de la solicitud en formato Epoch en milisegundos.
$context.routeKey

La clave de ruta seleccionada.
$context.stage

La etapa de implementación de la llamada a la API (por ejemplo, beta o prod).
$context.status

Estado de la respuesta.
$context.waf.error El mensaje de error devuelto por AWS WAF.
$context.waf.latency La latencia de AWS WAF en ms.
$context.waf.status El código de estado devuelto por AWS WAF.

Algunos ejemplos de los formatos de registro de acceso que se utilizan habitualmente se muestran en la consola de API Gateway y se detallan a continuación.

  • CLF (Common Log Format):

    $context.identity.sourceIp $context.identity.caller \
$context.identity.user [$context.requestTime] "$context.eventType $context.routeKey $context.connectionId" \
$context.status $context.requestId

    Los caracteres de continuación (\) deben entenderse como una ayuda visual. El formato de registro debe ser una sola línea. Puede agregar un carácter de nueva línea (\n) al final del formato de registro para incluir una nueva línea al final de cada entrada de registro.

  • 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"
}

    Los caracteres de continuación (\) deben entenderse como una ayuda visual. El formato de registro debe ser una sola línea. Puede agregar un carácter de nueva línea (\n) al final del formato de registro para incluir una nueva línea al final de cada entrada de registro.

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

    Los caracteres de continuación (\) deben entenderse como una ayuda visual. El formato de registro debe ser una sola línea. Puede agregar un carácter de nueva línea (\n) al final del formato de registro para incluir una nueva línea al final de cada entrada de registro.

  • CSV (valores separados por comas):

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

    Los caracteres de continuación (\) deben entenderse como una ayuda visual. El formato de registro debe ser una sola línea. Puede agregar un carácter de nueva línea (\n) al final del formato de registro para incluir una nueva línea al final de cada entrada de registro.