# Configuración del registro de API HTTP en API Gateway
<a name="http-api-logging"></a>

Puede activar el registro para escribir registros en CloudWatch Logs. Puede utilizar [variables de registro](http-api-logging-variables.md) para personalizar el contenido de los registros.

Para aumentar la seguridad, le recomendamos que escriba los registros en Registros de CloudWatch para todas las etapas de la API HTTP. Es probable que deba hacerlo para asegurar el cumplimiento de diversos marcos normativos. Para obtener más información, consulte [Controles de Amazon API Gateway](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) en la *Guía del usuario de AWS Security Hub*.

Para activar el registro para una API HTTP, tendrá que hacer lo siguiente.

1. Asegúrese de que el usuario tenga los permisos necesarios para activar el registro.

1. Cree un grupo de registros de Registros de CloudWatch.

1. Proporcione el ARN del grupo de registros de Registros de CloudWatch para una etapa de la API.

## Permisos para activar el registro
<a name="http-api-logging.permissions"></a>

Para activar el registro para una API, el usuario debe tener los siguientes permisos.

**Example**    
****  

```
{
    "Version":"2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "logs:DescribeLogGroups",
                "logs:DescribeLogStreams",
                "logs:GetLogEvents",
                "logs:FilterLogEvents"
            ],
            "Resource": "arn:aws:logs:us-east-2:123456789012:log-group:*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "logs:CreateLogDelivery",
                "logs:PutResourcePolicy",
                "logs:UpdateLogDelivery",
                "logs:DeleteLogDelivery",
                "logs:CreateLogGroup",
                "logs:DescribeResourcePolicies",
                "logs:GetLogDelivery",
                "logs:ListLogDeliveries"
            ],
            "Resource": "*"
        }
    ]
}
```

## Crear un grupo de registro y activar el registro para las API HTTP
<a name="http-api-enable-logging"></a>

Puede crear un grupo de registro y activar el registro de acceso mediante Consola de administración de AWS o AWS CLI.

------
#### [ Consola de administración de AWS ]

1.  Cree un grupo de registros. 

   Para obtener información acerca de cómo crear un grupo de registro mediante la consola, consulte [Crear un grupo de registro en la Guía del usuario de Registros de Amazon CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html).

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

1. Elija una API HTTP.

1. En la pestaña **Monitor** (Monitorear), en el panel de navegación principal, elija **Logging** (Registro).

1. Seleccione una etapa para activar el registro y elija **Select** (Seleccionar). 

1. Elija **Edit** (Editar) para activar el registro de acceso. 

1. Active el **Access logging** (Registro de acceso), ingrese un registro de CloudWatch y seleccione un formato de registro.

1. Seleccione **Save**.

------
#### [ AWS CLI ]

El siguiente comando [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) permite crear un grupo de registro:

```
aws logs create-log-group --log-group-name my-log-group
```

Necesita el nombre de recurso de Amazon (ARN) del grupo de registro para activar el registro. El formato del ARN es arn:aws:logs:*región*:*id de cuenta*:grupo de registro:*nombre del grupo de registro*.

El siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) activa el registro para la etapa `$default` de una API HTTP.

```
aws apigatewayv2 update-stage --api-id abcdef \
    --stage-name '$default' \
    --access-log-settings '{"DestinationArn": "arn:aws:logs:region:account-id:log-group:log-group-name", "Format": "$context.identity.sourceIp - - [$context.requestTime] \"$context.httpMethod $context.routeKey $context.protocol\" $context.status $context.responseLength $context.requestId"}'
```

------

## Ejemplo de formatos de registro
<a name="http-api-enable-logging.examples"></a>

La consola de API Gateway incluye algunos ejemplos de los formatos de registro de acceso habituales, los cuales se detallan a continuación.
+ `CLF` ([Common Log Format](https://httpd.apache.org/docs/current/logs.html#common)):

  ```
  $context.identity.sourceIp - - [$context.requestTime] "$context.httpMethod $context.routeKey $context.protocol" $context.status $context.responseLength $context.requestId $context.extendedRequestId
  ```
+  `JSON`: 

  ```
  { "requestId":"$context.requestId", "ip": "$context.identity.sourceIp", "requestTime":"$context.requestTime", "httpMethod":"$context.httpMethod","routeKey":"$context.routeKey", "status":"$context.status","protocol":"$context.protocol", "responseLength":"$context.responseLength", "extendedRequestId": "$context.extendedRequestId" }
  ```
+ `XML`: 

  ```
  <request id="$context.requestId"> <ip>$context.identity.sourceIp</ip> <requestTime>$context.requestTime</requestTime> <httpMethod>$context.httpMethod</httpMethod> <routeKey>$context.routeKey</routeKey> <status>$context.status</status> <protocol>$context.protocol</protocol> <responseLength>$context.responseLength</responseLength> <extendedRequestId>$context.extendedRequestId</extendedRequestId> </request>
  ```
+ `CSV` (valores separados por comas):

  ```
  $context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId
  ```

# Personalización de registros de acceso de las API de HTTP
<a name="http-api-logging-variables"></a>

Puede utilizar las siguientes variables para personalizar los registros de acceso de las API HTTP. Para obtener más información acerca de los registros de acceso para las API HTTP, consulte [Configuración del registro de API HTTP en API Gateway](http-api-logging.md).


| Parámetro | Descripción | 
| --- | --- | 
| \$1context.accountId |  El ID de cuenta de AWS del propietario de la API.  | 
| \$1context.apiId |  El identificador que API Gateway asigna a su API.  | 
| \$1context.authorizer.claims.property |  Una propiedad de las reclamaciones devueltas por el JSON Web Token (JWT) una vez que se ha autenticado correctamente al intermediario del método, como `$context.authorizer.claims.username`. Para obtener más información, consulte [Control del acceso a API HTTP con autorizadores de JWT en API Gateway](http-api-jwt-authorizer.md).  La llamada a `$context.authorizer.claims` devuelve null.   | 
| \$1context.authorizer.error | El mensaje de error devuelto por un autorizador. | 
| \$1context.authorizer.property |  El valor del par clave-valor especificado de la asignación `context` devuelto de una función de autorizador de Lambda para API Gateway. Por ejemplo, si el autorizador devuelve la siguiente asignación de `context`:  <pre>"context" : {<br />  "key": "value",<br />  "numKey": 1,<br />  "boolKey": true<br />}</pre> la llamada a `$context.authorizer.key` devuelve la cadena `"value"`, la llamada a `$context.authorizer.numKey` devuelve `1` y la llamada a `$context.authorizer.boolKey` devuelve `true`.  | 
| \$1context.awsEndpointRequestId |  El ID de la solicitud del punto de enlace de AWS desde el encabezado `x-amz-request-id` o `x-amzn-requestId`.  | 
| \$1context.awsEndpointRequestId2 |  El ID de la solicitud del punto de enlace de AWS desde el encabezado `x-amz-id-2`.  | 
| \$1context.customDomain.basePathMatched |  La ruta de un mapeo de la API con la que coincidió una solicitud entrante. Aplicable cuando un cliente utiliza un nombre de dominio personalizado para acceder a una API. Por ejemplo, si un cliente envía una solicitud a `https://api.example.com/v1/orders/1234` y la solicitud empareja el mapeo de la API con la ruta `v1/orders`, el valor es `v1/orders`. Para obtener más información, consulte [Asignación de etapas de API a un nombre de dominio personalizado para las API HTTP](http-api-mappings.md).  | 
| \$1context.dataProcessed | La cantidad de datos procesados en bytes. | 
| \$1context.domainName |  El nombre de dominio completo que se utiliza para invocar la API. Este debe ser el mismo que el encabezado `Host` entrante.  | 
| \$1context.domainPrefix |  La primera etiqueta del `$context.domainName`.  | 
| \$1context.error.message |  Una cadena que contiene un mensaje de error de API Gateway.  | 
| \$1context.error.messageString | El valor entrecomillado de \$1context.error.message, es decir, "\$1context.error.message". | 
| \$1context.error.responseType |  Un tipo de `GatewayResponse`. Para obtener más información, consulte [Supervisión de la ejecución de la API de WebSocket con métricas de CloudWatch](apigateway-websocket-api-logging.md) y [Configuración de respuestas de gateway para personalizar respuestas de errores](api-gateway-gatewayResponse-definition.md#customize-gateway-responses).  | 
| \$1context.extendedRequestId | Es igual que \$1context.requestId. | 
| \$1context.httpMethod |  El método HTTP utilizado. Los valores válidos son: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` y `PUT`.  | 
| \$1context.identity.accountId |  El ID de cuenta de AWS asociado con la solicitud. Compatible con rutas que utilizan la autorización de IAM.  | 
| \$1context.identity.caller |  El identificador principal del intermediario que firmó la solicitud. Compatible con rutas que utilizan la autorización de IAM.  | 
| \$1context.identity.cognitoAuthenticationProvider |  Una lista separada por comas de todos 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](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) en la *Guía para desarrolladores de Amazon Cognito* para obtener información sobre los proveedores de autenticación de Amazon Cognito disponibles. | 
| \$1context.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. | 
| \$1context.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.  | 
| \$1context.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.  | 
| \$1context.identity.principalOrgId |  El [ID de organización de AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Compatible con rutas que utilizan la autorización de IAM.  | 
| \$1context.identity.clientCert.clientCertPem |  El certificado de cliente codificado en PEM que el cliente presentó durante la autenticación TLS mutua. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada.  | 
| \$1context.identity.clientCert.subjectDN |  Nombre distintivo del asunto del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada.  | 
| \$1context.identity.clientCert.issuerDN |  Nombre distintivo del emisor del certificado que presenta un cliente. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada.  | 
| \$1context.identity.clientCert.serialNumber |  Número de serie del certificado. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada.  | 
| \$1context.identity.clientCert.validity.notBefore |  Fecha antes de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada.  | 
| \$1context.identity.clientCert.validity.notAfter |  Fecha después de la cual el certificado no es válido. Presente cuando un cliente accede a una API mediante un nombre de dominio personalizado que tiene una TLS mutua habilitada.  | 
| \$1context.identity.sourceIp |  La dirección IP de origen de la conexión TCP inmediata que realiza la solicitud al punto de enlace de API Gateway.  | 
| \$1context.identity.user |  El identificador principal del usuario que se autorizará a acceder al recurso. Compatible con rutas que utilizan la autorización de IAM.  | 
| \$1context.identity.userAgent |  El encabezado [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del intermediario de la API.  | 
| \$1context.identity.userArn |  El Nombre de recurso de Amazon (ARN) del usuario identificado después de la autenticación. Compatible con rutas que utilizan la autorización de IAM. Para obtener más información, consulte [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html).  | 
| \$1context.integration.error | El mensaje de error devuelto por una integración. Es igual que \$1context.integrationErrorMessage. | 
| \$1context.integration.integrationStatus | Para la integración de proxy de Lambda, el código de estado que se devuelve desde AWS Lambda, y no desde el código de función de Lambda del backend. | 
| \$1context.integration.latency | La latencia de integración en ms. Es igual que \$1context.integrationLatency. | 
| \$1context.integration.requestId | El ID de solicitud del punto de conexión de AWS. Es igual que \$1context.awsEndpointRequestId. | 
| \$1context.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. | 
| \$1context.integrationErrorMessage |  Una cadena que contiene un mensaje de error de integración.  | 
| \$1context.integrationLatency | La latencia de integración en ms. | 
| \$1context.integrationStatus | Para la integración de proxy de Lambda, este parámetro representa el código de estado que se devuelve desde AWS Lambda, y no desde la función de Lambda del backend. | 
| \$1context.path | Ruta de acceso de la solicitud. Por ejemplo, /\$1stage\$1/root/child.  | 
| \$1context.protocol | Protocolo de la solicitud; por ejemplo, HTTP/1.1.  Las API de API Gateway pueden aceptar solicitudes HTTP/2, pero API Gateway envía solicitudes a las integraciones de backend mediante HTTP/1.1. Como resultado, el protocolo de solicitud se registra como HTTP/1.1 incluso si un cliente envía una solicitud que usa HTTP/2.   | 
| \$1context.requestId |  El ID que API Gateway asigna a la solicitud de API.  | 
| \$1context.requestTime | Hora de la solicitud en formato [CLF](https://httpd.apache.org/docs/current/logs.html#common)-(dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | 
| \$1context.requestTimeEpoch | Hora de la solicitud en formato [Epoch](https://en.wikipedia.org/wiki/Unix_time). | 
| \$1context.responseLatency | La latencia de respuesta en ms. | 
| \$1context.responseLength | La duración de la carga de respuesta en bytes. | 
| \$1context.routeKey |  La clave de ruta de la solicitud de la API, por ejemplo, `/pets`.  | 
| \$1context.stage |  La etapa de implementación de la solicitud de la API (por ejemplo, `beta` o `prod`).  | 
| \$1context.status | El estado de respuesta de método. |