# Configurar registro em log para APIs HTTP no API Gateway É possível ativar o registro em log para gravar logs no CloudWatch Logs. Você pode usar [variáveis de registro em log](http-api-logging-variables.md) para personalizar o conteúdo de seus logs. Para melhorar seu procedimento de segurança, recomendamos que você grave logs no CloudWatch Logs referentes a todos os estágios da sua API HTTP. Você pode precisar fazer isso para cumprir vários requisitos de conformidade. Para ter mais informações, consulte [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) no *Guia do usuário do AWS Security Hub*. Para ativar o registro em log para uma API HTTP, é necessário fazer o seguinte. 1. Seu usuário deve ter as permissões necessárias para ativar o registro em log. 1. Crie um grupo de logs do CloudWatch Logs. 1. Forneça o ARN do grupo de logs do CloudWatch Logs para um estágio de sua API. ## Permissões para ativar o registro em log Para ativar o registro em log para uma API, seu usuário deve ter as permissões a seguir. **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": "*" } ] } ``` ## Criar um grupo de logs e ativar o registro em log para APIs HTTP É possível criar um grupo de logs e ativar o registro em log de acesso usando o Console de gerenciamento da AWS ou a AWS CLI. ------ #### [ Console de gerenciamento da AWS ] 1. Crie um grupo de logs. Para saber como criar um grupo de logs usando o console, consulte [Criar um grupo de logs no Guia do usuário do Amazon CloudWatch Logs](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html). 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Selecione uma API HTTP. 1. Na guia **Monitor** no painel de navegação principal, selecione **Logging** (Registro em log). 1. Selecione um estágio para ativar o registro em log e **Select** (Selecionar). 1. Selecione **Edit** (Editar) para ativar o registro em log de acesso. 1. Ative **Access logging** (Registro em log de acesso), insira um CloudWatch Logs e selecione um formato de log. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] O comando [create-log-group](https://docs.aws.amazon.com/cli/latest/reference/logs/create-log-group.html) indicado abaixo cria um grupo de logs: ``` aws logs create-log-group --log-group-name my-log-group ``` Você precisa do nome do recurso da Amazon (ARN) do seu grupo de logs para ativar o registro em log. O formato do ARN é arn:aws:logs:*region*:*account-id*:log-group:*log-group-name*. O comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-stage.html) indicado abaixo ativa o registro em log para o estágio `$default` de uma 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"}' ``` ------ ## Formatos de log demonstrativos Alguns formatos demonstrativos de log de acesso usados com frequência estão disponíveis no console do API Gateway e são listados a seguir. + `CLF` ([Formato de log comum](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`: ``` $context.identity.sourceIp $context.requestTime $context.httpMethod $context.routeKey $context.status $context.protocol $context.responseLength $context.extendedRequestId ``` + `CSV` (valores separados por vírgula): ``` $context.identity.sourceIp,$context.requestTime,$context.httpMethod,$context.routeKey,$context.protocol,$context.status,$context.responseLength,$context.requestId,$context.extendedRequestId ``` # Personalizar logs de acesso à API HTTP É possível usar as variáveis a seguir para personalizar logs de acesso para APIs HTTP. Para saber mais sobre logs de acesso para APIs HTTP, consulte [Configurar registro em log para APIs HTTP no API Gateway](http-api-logging.md). | Parâmetro | Descrição | | --- | --- | | \$1context.accountId | O ID da conta da AWS do proprietário da API | | \$1context.apiId | O identificador que o API Gateway atribui à sua API. | | \$1context.authorizer.claims.property | Uma propriedade das declarações retornadas do JSON Web Token (JWT) depois que o chamador do método é autenticado com êxito, como `$context.authorizer.claims.username`. Para obter mais informações, consulte [Controlar o acesso a APIs HTTP com autorizadores JWT no API Gateway](http-api-jwt-authorizer.md). Chamar `$context.authorizer.claims` retorna um valor nulo. | | \$1context.authorizer.error | A mensagem de erro retornada de um autorizador. | | \$1context.authorizer.property | O valor do par de chave/valor especificado do mapa `context` retornado por uma função de autorizador do Lambda do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa `context`: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
chamar `$context.authorizer.key` retorna a string `"value"`, chamar `$context.authorizer.numKey` retorna `1` e chamar `$context.authorizer.boolKey` retorna `true`. | | \$1context.awsEndpointRequestId | O ID da solicitação do endpoint da AWS do cabeçalho `x-amz-request-id` ou `x-amzn-requestId`. | | \$1context.awsEndpointRequestId2 | O ID da solicitação do endpoint da AWS do cabeçalho `x-amz-id-2`. | | \$1context.customDomain.basePathMatched | O caminho para um mapeamento da API correspondente a uma solicitação de entrada. Aplicável quando um cliente usa um nome de domínio personalizado para acessar uma API. Por exemplo, se um cliente enviar uma solicitação para `https://api.example.com/v1/orders/1234` e a solicitação corresponder ao mapeamento da API com o caminho `v1/orders`, o valor será `v1/orders`. Para saber mais, consulte [Mapear estágios de API para um nome de domínio personalizado para APIs HTTP](http-api-mappings.md). | | \$1context.dataProcessed | A quantidade de dados processados em bytes. | | \$1context.domainName | O nome de domínio completo usado para invocar a API. Ele deve ser o mesmo que o cabeçalho `Host` de entrada. | | \$1context.domainPrefix | O primeiro rótulo do `$context.domainName`. | | \$1context.error.message | Uma string que contém uma mensagem de erro do API Gateway. | | \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". | | \$1context.error.responseType | Um tipo de `GatewayResponse`. Para obter mais informações, consulte [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md) e [Configurar respostas do gateway para personalizar respostas de erro](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.extendedRequestId | Equivale a \$1context.requestId. | | \$1context.httpMethod | O método HTTP utilizado. Os valores válidos incluem: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. | | \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. Compatível com rotas que usam a autorização do IAM. | | \$1context.identity.caller | O identificador da entidade do autor da chamada que assinou a solicitação. Compatível com rotas que usam a autorização do IAM. | | \$1context.identity.cognitoAuthenticationProvider | Uma lista separada por vírgulas de todos os provedores de autenticação do Amazon Cognito usados pelo autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Por exemplo, para uma identidade de um grupo de usuários do Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Consulte informações sobre os provedores de autenticação do Amazon Cognito disponível em [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) no *Guia do desenvolvedor do Amazon Cognito*. | | \$1context.identity.cognitoAuthenticationType | O tipo de autenticação do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. Os valores possíveis incluem `authenticated` para identidades autenticadas e `unauthenticated` para identidades não autenticadas. | | \$1context.identity.cognitoIdentityId | O ID de identidade do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | O ID do grupo de identidades do Amazon Cognito do autor da chamada que faz a solicitação. Disponível somente se a solicitação foi assinada com credenciais do Amazon Cognito. | | \$1context.identity.principalOrgId | O [ID da organização da AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). Compatível com rotas que usam a autorização do IAM. | | \$1context.identity.clientCert.clientCertPem | O certificado de cliente codificado por PEM que o cliente apresentou durante a autenticação TLS mútua. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. | | \$1context.identity.clientCert.subjectDN | O nome distinto do assunto do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. | | \$1context.identity.clientCert.issuerDN | O nome distinto do emissor do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. | | \$1context.identity.clientCert.serialNumber | O número de série do certificado. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. | | \$1context.identity.clientCert.validity.notBefore | A data antes da qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. | | \$1context.identity.clientCert.validity.notAfter | A data após a qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. | | \$1context.identity.sourceIp | O endereço IP de origem da conexão TCP mais próxima que está fazendo a solicitação para o endpoint do API Gateway. | | \$1context.identity.user | O identificador da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com rotas que usam a autorização do IAM. | | \$1context.identity.userAgent | O cabeçalho [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) do autor da chamada da API. | | \$1context.identity.userArn | O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação. Compatível com rotas que usam a autorização do IAM. Para obter mais informações, 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 | A mensagem de erro retornada de uma integração. Equivale a \$1context.integrationErrorMessage. | | \$1context.integration.integrationStatus | Para a integração de proxy do Lambda, o código de status retornado pelo AWS Lambda, e não pelo código de função do Lambda de backend. | | \$1context.integration.latency | A latência de integração em ms. Equivale a \$1context.integrationLatency. | | \$1context.integration.requestId | O ID da solicitação do endpoint da AWS. Equivale a \$1context.awsEndpointRequestId. | | \$1context.integration.status | O código de status retornado de uma integração. Para integrações de proxy do Lambda, esse é o código de status que seu código de função do Lambda retorna. | | \$1context.integrationErrorMessage | Uma string que contém uma mensagem de erro de integração. | | \$1context.integrationLatency | A latência de integração em ms. | | \$1context.integrationStatus | Para a integração de proxy do Lambda, esse parâmetro representa o código de status retornado pelo AWS Lambda, e não pela função do Lambda de backend. | | \$1context.path | O caminho da solicitação. Por exemplo, /\$1stage\$1/root/child. | | \$1context.protocol | O protocolo de solicitação, por exemplo, , HTTP/1.1. As APIs do API Gateway podem aceitar solicitações HTTP/2, mas o API Gateway envia solicitações para integrações de back-end usando HTTP/1.1. Como resultado, o protocolo de solicitação é registrado como HTTP/1.1 mesmo se um cliente enviar uma solicitação que usa HTTP/2. | | \$1context.requestId | O ID que o API Gateway atribui à solicitação de API. | | \$1context.requestTime | O horário da solicitação [CLF](https://httpd.apache.org/docs/current/logs.html#common) formatado (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | O horário da solicitação [Epoch](https://en.wikipedia.org/wiki/Unix_time) formatado. | | \$1context.responseLatency | A latência da resposta em ms. | | \$1context.responseLength | O tamanho da carga de resposta em bytes. | | \$1context.routeKey | A chave de rota da solicitação da API, por exemplo, `/pets`. | | \$1context.stage | O estágio de implantação da solicitação de API (por exemplo, `beta` ou `prod`). | | \$1context.status | O status de resposta do método. |