Referência de variáveis de registro em log de acesso e modelo de mapeamento do API Gateway - Amazon API Gateway
$contextVariáveis para modelos de dados, autorizadores, modelos de mapeamento e registro de CloudWatch acessoExemplo de modelo de variáveis $contextVariáveis $context somente para registro de acesso em logsVariáveis $inputExemplos de modelos de variáveis $input$stageVariablesVariáveis $util

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Referência de variáveis de registro em log de acesso e modelo de mapeamento do API Gateway

Esta seção fornece informações de referência para as variáveis e funções que o Amazon API Gateway define para uso com modelos de dados, autorizadores, modelos de mapeamento e registro de CloudWatch acesso. Para obter informações detalhadas sobre como usar essas variáveis e funções, consulte Noções básicas de modelos de mapeamento. Para obter mais informações sobre a Velocity Template Language (VTL), consulte VTL Reference.

nota

Para obter as variáveis $method e $integration, consulte Referência de mapeamento de dados de resposta e de solicitação de API do Amazon API Gateway.

$contextVariáveis para modelos de dados, autorizadores, modelos de mapeamento e registro de CloudWatch acesso

$contextAs variáveis a seguir podem ser usadas em modelos de dados, autorizadores, modelos de mapeamento e registro de CloudWatch acesso.

Para $context variáveis que podem ser usadas somente no registro de CloudWatch acesso, consulteVariáveis $context somente para registro de acesso em logs.

Parâmetro Descrição
$context.accountId

O ID da AWS conta do proprietário da API.
$context.apiId

O identificador que o API Gateway atribui à sua API.
$context.authorizer.claims.property

Uma propriedade das declarações retornadas do grupo de usuários do Amazon Cognito depois que o autor da chamada do método é autenticado com êxito. Para ter mais informações, consulte Controlar o acesso a uma API REST usando um grupo de usuários do Amazon Cognito como autorizador.

nota

Chamar $context.authorizer.claims retorna um valor nulo.
$context.authorizer.principalId

A identificação do usuário principal associada ao token enviado pelo cliente e retornada a partir de um autorizador do Lambda do API Gateway (anteriormente conhecido como autorizador personalizado). Para ter mais informações, consulte Usar os autorizadores do API Gateway Lambda.
$context.authorizer.property

O valor transformado em string do par de chave/valor especificado do mapa context retornado de 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 retornará a string "value", chamar $context.authorizer.numKey retornará a string "1" e chamar $context.authorizer.boolKey retornará a string "true".

Para ter mais informações, consulte Usar os autorizadores do API Gateway Lambda.
$context.awsEndpointRequestId

O ID da solicitação do AWS endpoint.
$context.domainName

O nome de domínio completo usado para invocar a API. Ele deve ser o mesmo que o cabeçalho Host de entrada.
$context.domainPrefix

O primeiro rótulo do $context.domainName.
$context.error.message

Uma string que contém uma mensagem de erro do API Gateway. Essa variável só pode ser usada para substituição simples de variáveis em um modelo de GatewayResponsemapeamento corporal, que não é processado pelo mecanismo Velocity Template Language, e no registro de acesso. Para ter mais informações, consulte Monitorar a execução de APIs WebSocket com métricas do CloudWatch e Configurar respostas do gateway para personalizar respostas de erro.
$context.error.messageString O valor citado de $context.error.message, ou seja, "$context.error.message".
$context.error.responseType

Um tipo de GatewayResponse. Essa variável só pode ser usada para substituição simples de variáveis em um modelo de GatewayResponsemapeamento corporal, que não é processado pelo mecanismo Velocity Template Language, e no registro de acesso. Para ter mais informações, consulte Monitorar a execução de APIs WebSocket com métricas do CloudWatch e Configurar respostas do gateway para personalizar respostas de erro.
$context.error.validationErrorString

Uma string que contém uma mensagem de erro de validação detalhada.
$context.extendedRequestId O ID estendido que o API Gateway gera e atribui à solicitação de API. O ID de solicitação estendido contém informações úteis para a depuração e solução de problemas.
$context.httpMethod

O método HTTP utilizado. Os valores válidos incluem: DELETE, GET, HEAD, OPTIONS, PATCH, POST e PUT.
$context.identity.accountId

O ID da AWS conta associado à solicitação.
$context.identity.apiKey

Para os métodos de API que exigem uma chave de API, essa variável é a chave de API associada à solicitação do método. Para métodos que não exigem uma chave de API, essa variável é um valor nulo. Para ter mais informações, consulte Criar e usar planos de uso com chaves de API.
$context.identity.apiKeyId O ID da chave de API associada a uma solicitação de API que exige uma chave de API.
$context.identity.caller

O identificador principal da entidade do autor da chamada que assinou a solicitação. Compatível com recursos que usam a autorização do IAM.
$context.identity.cognitoAuthenticationProvider

Uma lista separada por vírgulas dos 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

Para obter informações, consulte Usar identidades federadas no Guia do desenvolvedor do Amazon Cognito.
$context.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.
$context.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.
$context.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.
$context.identity.principalOrgId

O ID da organização da AWS.
$context.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.
$context.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. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua.
$context.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. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua.
$context.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. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua.
$context.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. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua.
$context.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. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua.
$context.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. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua.
$context.identity.user

O identificador principal da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com recursos que usam a autorização do IAM.
$context.identity.userAgent

O cabeçalho User-Agent do autor da chamada da API.
$context.identity.userArn

O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação. Para ter mais informações, consulte https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
$context.path O caminho da solicitação. Por exemplo, para um URL de solicitação sem proxy de https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, o valor $context.path é /{stage}/root/child.
$context.protocol O protocolo de solicitação, por exemplo, , HTTP/1.1.
nota

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.
$context.requestId

Um ID para a solicitação. Os clientes podem substituir esse ID de solicitação. Usar $context.extendedRequestId para um ID de solicitação exclusivo gerado pelo API Gateway.
$context.requestOverride.header.header_name

Substituição do cabeçalho da solicitação. Esse parâmetro, quando definido, contém os cabeçalhos a serem usados em lugar dos HTTP Headers (Cabeçalhos HTTP) que são definidos no painel Integration Request (Solicitação de integração). Para ter mais informações, consulte Usar um modelo de mapeamento para substituir parâmetros de solicitação e resposta e códigos de status de uma API.
$context.requestOverride.path.path_name

Substituição do caminho da solicitação. Esse parâmetro, quando definido, contém o caminho da solicitação a ser usado em lugar dos URL Path Parameters (Parâmetros de caminho de URL) que são definidos no painel Integration Request (Solicitação de integração). Para ter mais informações, consulte Usar um modelo de mapeamento para substituir parâmetros de solicitação e resposta e códigos de status de uma API.
$context.requestOverride.querystring.querystring_name

Substituição da string de consulta da solicitação. Esse parâmetro, quando definido, contém as strings de consulta da solicitação a serem usadas em lugar dos URL Query String Parameters (Parâmetros de string de consulta de URL) que são definidos no painel Integration Request (Solicitação de integração). Para ter mais informações, consulte Usar um modelo de mapeamento para substituir parâmetros de solicitação e resposta e códigos de status de uma API.
$context.responseOverride.header.header_name Substituição do cabeçalho da resposta. Esse parâmetro, quando definido, contém o cabeçalho a ser retornado em lugar do Response header (Cabeçalho de resposta) que é definido como o Default mapping (Mapeamento padrão) no painel Integration Response (Resposta de integração). Para ter mais informações, consulte Usar um modelo de mapeamento para substituir parâmetros de solicitação e resposta e códigos de status de uma API.
$context.responseOverride.status Substituição do código de status da resposta. Esse parâmetro, quando definido, contém o código de status a ser retornado em lugar do Method response status (Status de resposta de método) que é definido como o Default mapping (Mapeamento padrão) no painel Integration Response (Resposta de integração). Para ter mais informações, consulte Usar um modelo de mapeamento para substituir parâmetros de solicitação e resposta e códigos de status de uma API.
$context.requestTime O horário da solicitação CLF formatado (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch O tempo de solicitação formatado em Epoch, em milissegundos.
$context.resourceId

O identificador que o API Gateway atribui ao seu recurso.
$context.resourcePath

O caminho para o seu recurso. Por exemplo, para a URI de solicitação sem proxy de https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, o valor $context.resourcePath é /root/child. Para ter mais informações, consulte Tutorial: Criar uma API REST com integração não proxy HTTP.

$context.stage

O estágio de implantação da solicitação de API (por exemplo, Beta ou Prod).
$context.wafResponseCode

A resposta recebida do AWS WAF: WAF_ALLOW ou WAF_BLOCK. Não será definido se o estágio não estiver associado a uma ACL da web. Para ter mais informações, consulte Usar o AWS WAF para proteger as APIs.
$context.webaclArn

O ARN completo da ACL da web que é utilizada para decidir se deseja permitir ou bloquear a solicitação. Não será definido se o estágio não estiver associado a uma ACL da web. Para ter mais informações, consulte Usar o AWS WAF para proteger as APIs.

Exemplo de modelo de variáveis $context

É aconselhável usar variáveis $context em um modelo de mapeamento se o método de API transmitir dados estruturados a um back-end que exija que os dados estejam em um formato específico.

O exemplo a seguir mostra um modelo de mapeamento que mapeia variáveis $context de entrada para variáveis de back-end com nomes um pouco diferentes em uma carga de solicitação de integração:

nota

Observe que uma das variáveis é uma chave de API. Este exemplo pressupõe que o método tem "exige a chave de API" habilitado.

{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

Variáveis $context somente para registro de acesso em logs

As variáveis $context a seguir estão disponíveis somente para registro de acesso em logs. Para ter mais informações, consulte Configurar o registro em log do CloudWatch para uma API REST no API Gateway. (Para WebSocket APIs, consulteMonitorar a execução de APIs WebSocket com métricas do CloudWatch.)

Parâmetro Descrição
$context.authorize.error A mensagem de erro de autorização.
$context.authorize.latency A latência de autorização em ms.
$context.authorize.status O código de status retornado de uma tentativa de autorização.
$context.authorizer.error A mensagem de erro retornada de um autorizador.
$context.authorizer.integrationLatency A latência de autorizador em ms.
$context.authorizer.integrationStatus O código de status retornado de um autorizador do Lambda.
$context.authorizer.latency A latência de autorizador em ms.
$context.authorizer.requestId O ID da solicitação do AWS endpoint.
$context.authorizer.status O código de status retornado de um autorizador.
$context.authenticate.error A mensagem de erro retornada de uma tentativa de autenticação.
$context.authenticate.latency A latência de autenticação em ms.
$context.authenticate.status O código de status retornado de uma tentativa de autenticação.
$context.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 Como trabalhar com mapeamentos de API para APIs REST.
$context.integration.error A mensagem de erro retornada de uma integração.
$context.integration.integrationStatus Para a integração do proxy Lambda, o código de status retornou do código da função Lambda de back-end AWS Lambda, não do código da função Lambda de back-end.
$context.integration.latency A latência de integração em ms. Equivale a $context.integrationLatency.
$context.integration.requestId O ID da solicitação do AWS endpoint. Equivale a $context.awsEndpointRequestId.
$context.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.
$context.integrationLatency A latência de integração em ms.
$context.integrationStatus Para a integração do proxy Lambda, esse parâmetro representa o código de status retornado AWS Lambda, não do código da função Lambda de back-end.
$context.responseLatency A latência da resposta em ms.
$context.responseLength O tamanho da carga de resposta em bytes.
$context.status O status de resposta do método.
$context.waf.error A mensagem de erro retornou de AWS WAF.
$context.waf.latency A AWS WAF latência em ms.
$context.waf.status O código de status retornado de AWS WAF.
$context.xrayTraceId

O ID de rastreio do rastreio do X-Ray. Para ter mais informações, consulte Configurar o AWS X-Ray com APIs REST do API Gateway.

Variáveis $input

A variável $input representa os parâmetros e a carga de solicitação do método a serem processados por um modelo de mapeamento. Ela fornece quatro funções:

Variável e função Descrição
$input.body

Retorna a carga de solicitação bruta como uma string.
$input.json(x)

Essa função avalia uma expressão JSONPath e retorna os resultados como uma string JSON.

Por exemplo, $input.json('$.pets') retorna uma string JSON que representa a estrutura pets.

Para obter mais informações sobre o JSONPath, consulte JSONPath ou JSONPath para Java.
$input.params()

Retorna um mapa de todos os parâmetros de solicitação. Recomendamos que você use $util.escapeJavaScript para higienizar o resultado a fim de evitar um potencial ataque de injeção. Para o controle total da higienização de solicitações, use uma integração de proxy sem um modelo e realize a higienização de solicitações em sua integração.
$input.params(x)

Retorna o valor de um parâmetro de solicitação do método do caminho, da string de consulta ou do valor de cabeçalho (pesquisados nessa ordem), considerando uma string de nome do parâmetro x. Recomendamos que você use $util.escapeJavaScript para higienizar o parâmetro a fim de evitar um potencial ataque de injeção. Para o controle total da higienização de parâmetros, use uma integração de proxy sem um modelo e realize a higienização de solicitações em sua integração.
$input.path(x)

Usa uma string de expressão JSONPath (x) e retorna uma representação de objeto JSON do resultado. Isso permite que você acesse e manipule elementos da carga nativamente em Apache Velocity Template Language (VTL).

Por exemplo, se a expressão $input.path('$.pets') retorna um objeto da seguinte forma:

[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]

$input.path('$.pets').count() retornaria "3".

Para obter mais informações sobre o JSONPath, consulte JSONPath ou JSONPath para Java.

Exemplos de modelos de variáveis $input

Exemplo de modelo de mapeamento de parâmetros

O seguinte exemplo de mapeamento de parâmetros transmite todos os parâmetros, incluindo path, querystring e header, ao endpoint de integração por meio de uma carga JSON:

#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

Na verdade, esse modelo de mapeamento processa a saída de todos os parâmetros de solicitação na carga, conforme descrito da seguinte forma:

{
  "params" : {
     "path" : {    
       "path_name" : "path_value", 
       ...
     }
     "header" : {  
       "header_name" : "header_value",
       ...
     }
     "querystring" : {
       "querystring_name" : "querystring_value",
       ...
     }
   }
}

É aconselhável usar a variável $input para obter strings de consulta e o corpo da solicitação com ou sem o uso de modelos. Também convém inserir o parâmetro e a carga útil, ou uma subseção da carga útil, na função do Lambda. Os exemplos a seguir mostram como fazer isso.

Exemplo de modelo de mapeamento JSON usando $input

O exemplo a seguir mostra como usar um mapeamento para ler um nome da string de consulta e depois incluir todo o corpo POST em um elemento:

{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

Se a entrada JSON contiver caracteres sem escape que não possam ser analisados JavaScript, uma resposta de 400 poderá ser retornada. A aplicação de $util.escapeJavaScript($input.json('$')) acima assegurará que a entrada JSON possa ser analisada corretamente.

Exemplo de modelo de mapeamento usando $input

O exemplo a seguir mostra como transmitir uma expressão JSONPath ao método json(). Você também pode ler uma propriedade específica do seu objeto de corpo da solicitação usando um ponto (.), seguido pelo nome da sua propriedade:

{
    "name" : "$input.params('name')",
    "body" : $input.json('$.mykey')  
}

Se a carga de uma solicitação de método contiver caracteres sem escape que não possam ser analisados JavaScript, você poderá obter uma resposta. 400 Nesse caso, é necessário chamar a função $util.escapeJavaScript() no modelo de mapeamento, conforme mostrado a seguir: 

{
    "name" : "$input.params('name')",
    "body" : "$util.escapeJavaScript($input.json('$.mykey'))" 
}

Exemplo de solicitação e resposta usando $input

Veja a seguir um exemplo que usa todas as três funções:

Request template (Modelo de solicitação):

Resource: /things/{id}

With input template:
{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

POST /things/abc
{
    "things" : {
        "1" : {},
        "2" : {},
        "3" : {}
    }
}

Resposta:

{
  "id": "abc",
  "count": "3",
  "things": {
    "1": {},
    "2": {},
    "3": {}
  }
}

Para ver mais exemplos de mapeamento, consulte Noções básicas de modelos de mapeamento.

$stageVariables

Variáveis de estágio podem ser usadas no mapeamento de parâmetro e modelos de mapeamento e como espaços reservados em ARNs e URLs usados em integrações de método. Para ter mais informações, consulte Configurar variáveis de estágio para a implantação de uma API REST.

Sintaxe Descrição
$stageVariables.<variable_name>

<variable_name> representa um nome de variável de estágio.
$stageVariables['<variable_name>']

<variable_name> representa qualquer nome de variável de estágio.
${stageVariables['<variable_name>']}

<variable_name> representa qualquer nome de variável de estágio.

Variáveis $util

A variável $util contém funções de utilitário para uso em modelos de mapeamento.

nota

A menos que especificado de outra forma, o conjunto de caracteres padrão é UTF-8.

Função Descrição
$util.escapeJavaScript()

Escapa dos caracteres em uma string usando regras de JavaScript string.

nota

Essa função transformará quaisquer aspas simples comuns (') em aspas com escape (\'). No entanto, as aspas simples com escape não são válidas no JSON. Portanto, quando a saída dessa função for usada em uma propriedade JSON, você deverá transformar todas aspas simples (\') com escape de volta para aspas simples comuns ('). Isso é mostrado no exemplo a seguir: 

 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
$util.parseJson()

Usa um JSON "transformado em string" e retorna uma representação de objeto do resultado. Você pode usar o resultado dessa função para acessar e manipular elementos da carga nativamente em Apache VTL (Velocity Template Language). Por exemplo, se tiver a seguinte carga: 

{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}

e usar o seguinte modelo de mapeamento 

#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}

Você receberá a seguinte saída:

{
   "errorMessageObjKey2ArrVal" : 1
}
$util.urlEncode()

Converte uma string no formato “application/x-www-form-urlencoded”.
$util.urlDecode()

Decodifica uma string “application/x-www-form-urlencoded”.
$util.base64Encode()

Codifica os dados em uma string codificada em base64.
$util.base64Decode()

Decodifica os dados de uma string codificada em base64.