View a markdown version of this page

Registros de acceso para las API de REST - Amazon API Gateway
Formatos de los registro de accesoConfiguración del registro de acceso mediante la consola de API GatewayConfiguración del registro de acceso mediante CloudFormation

Registros de acceso para las API de REST

En los registros de acceso, se registra quién ha accedido a la API y cómo el intermediario ha accedido a la API. Puede crear su propio grupo de registro o elegir un grupo de registro existente. Para especificar los detalles de acceso, se seleccionan variables $context, un formato de registro y un destino de grupo de registro.

Formatos de los registro de acceso

El formato del registro de acceso debe incluir al menos $context.requestId o $context.extendedRequestId. Como práctica recomendada, incluya ambos en el formato de registro.

$context.requestId

Esto registra el valor en el encabezado x-amzn-RequestId. Los clientes pueden invalidar el valor del encabezado x-amzn-RequestId con un valor en formato de identificador único universal (UUID). API Gateway devuelve este ID de solicitud en el encabezado de respuesta x-amzn-RequestId. API Gateway sustituye los ID de solicitud invalidados que no tienen el formato de un UUID por UUID_REPLACED_INVALID_REQUEST_ID en los registros de acceso.

$context.extendedRequestId

ExtendedRequestID es un ID único que API Gateway genera. API Gateway devuelve este ID de solicitud en el encabezado de respuesta x-amz-apigw-id. Una persona que llama a la API no puede proporcionar ni anular este ID de solicitud. Es posible que tenga que proporcionar este valor a AWS Support para que le ayude a solucionar los problemas de la API. Para obtener más información, consulte Variables para el registro de acceso para API Gateway.

Elija un formato de registro que también se utilice en el backend de análisis; por ejemplo, Common Log Format (CLF), JSON, XML o CSV. Después, puede incluir datos en los registros de acceso para que tengan las métricas calculadas y procesadas. Para definir el formato del registro, establezca el ARN del grupo de registros en la propiedad accessLogSettings/destinationArn de stage. Puede obtener el ARN de un grupo de registro en la consola de CloudWatch. Para definir el formato del registro de acceso, establezca el formato elegido en la propiedad accessLogSetting/format de stage.

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.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 (valores separados por comas):

    $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

Configuración del registro de acceso mediante la consola de API Gateway

Antes de configurar el registro de acceso, implemente la API en una etapa y configure un ARN de rol de Registros de CloudWatch adecuado para la cuenta.

  1. Inicie sesión en la consola de API Gateway, en https://console.aws.amazon.com/apigateway.

  2. En el panel de navegación principal, elija API y, a continuación, realice una de las siguientes acciones:

    1. Elija una API existente y después una etapa.

    2. Cree una API e impleméntela como etapa.

  3. En el panel de navegación principal, elija Etapas.

  4. En la sección Registros y rastreo, elija Editar.

  5. Active Registros de acceso personalizado.

  6. En ARN del destino de registro de acceso, ingrese el ARN de un grupo de registro. El formato del ARN es arn:aws:logs:{region}:{account-id}:log-group:log-group-name.

  7. En Formato de registro, ingrese un formato de registro. Puede elegir CLF, JSON, XML o CSV. Para obtener más información sobre ejemplos de formatos de registro, consulte Formatos de los registro de acceso.

  8. Seleccione Save changes (Guardar cambios).

API Gateway ya está listo para registrar solicitudes en la API. Si actualiza la configuración de la etapa, los registros o las variables de la etapa, no necesita volver a implementar la API.

Configuración del registro de acceso mediante CloudFormation

Utilice la siguiente plantilla de CloudFormation de ejemplo para crear un grupo de registro de Registros de Amazon CloudWatch y configurar el registro de acceso para una etapa. Para habilitar CloudWatch Logs, debe conceder permiso a API Gateway para leer y escribir registros en CloudWatch para su cuenta. Para obtener más información, consulte Asociar una cuenta a un rol de IAM en la Guía del usuario de 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