Referência de variáveis de registro em log de acesso e modelo de mapeamento do API Gateway - Amazon API Gateway
Variáveis $context para modelos de dados, autorizadores, modelos de mapeamento e registro de acesso em logs do CloudWatchExemplo 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

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 acesso em logs do CloudWatch. Para obter informações detalhadas sobre como usar essas variáveis e funções, consulte Modelos de mapeamento para APIs REST. 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.

Variáveis $context para modelos de dados, autorizadores, modelos de mapeamento e registro de acesso em logs do CloudWatch

As seguintes variáveis $context podem ser usadas em modelos de dados, autorizadores, modelos de mapeamento e registro de acesso em logs do CloudWatch. O API Gateway pode adicionar outras variáveis de contexto.

Para obter as variáveis $context que podem ser usadas somete no registro de acesso em logs do CloudWatch, consulte Variáveis $context somente para registro de acesso em logs.

Parâmetro Descrição
$context.accountId

O ID da conta da AWS 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 APIs REST usando grupos 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".

Com relação à propriedade, o único caractere especial aceito é o sublinhado (_).

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

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

O ID da implantação de API.
$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 pode ser usada apenas para substituição de variável simples em um modelo de mapeamento de corpo GatewayResponse, que não é processado pelo mecanismo Velocity Template Language, bem como no registro de acesso. Para ter mais informações, consulte Monitorar a execução de APIs de 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 pode ser usada apenas para substituição de variável simples em um modelo de mapeamento de corpo GatewayResponse, que não é processado pelo mecanismo Velocity Template Language, bem como no registro de acesso. Para ter mais informações, consulte Monitorar a execução de APIs de 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 conta da AWS 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 Usar planos e chaves de API para APIs REST no APIs Gateway .
$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 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 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 ao 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.vpcId

O ID da VPC que está fazendo a solicitação ao endpoint do API Gateway.
$context.identity.vpceId

O ID do endpoint da VPC que está fazendo a solicitação ao endpoint do API Gateway. Presente somente quando você tem uma API privada.
$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.isCanaryRequest

Retorna true se a solicitação foi direcionada ao canário e false se a solicitação não foi direcionada ao canário. Presente somente quando você tem um canário habilitado.
$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: Crie uma API REST com uma integração de não proxy de 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 REST no API Gateway.
$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 REST no API Gateway.

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

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

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

A saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

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 APIs REST no API Gateway. (Para APIs WebSocket, consulte Monitorar a execução de APIs de 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 integração do 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 endpoint da AWS.
$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 Associar estágios de API a um nome de domínio personalizado para APIs REST.
$context.endpointType

O tipo do endpoint da API.
$context.integration.error A mensagem de erro retornada de uma integração.
$context.integration.integrationStatus Para a integração de proxy do Lambda, o código de status retornado do AWS Lambda, não do código de função do 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 endpoint da AWS. 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 de proxy do Lambda, esse parâmetro representa o código de status retornado do AWS Lambda, não do código da função do 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 retornada pelo AWS WAF.
$context.waf.latency A latência do AWS WAF em ms.
$context.waf.status O código de status retornado pelo 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 as seguintes funções:

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

Retorna a carga de solicitação bruta como uma string. É possível usar $input.body para preservar números inteiros de ponto flutuante, como 10.00.
$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').size() retornaria "3".

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

Exemplos de modelos de variáveis $input

Os exemplos a seguir mostram como usar as variáveis $input em modelos de mapeamento. Você pode usar uma integração simulada ou uma integração sem proxy do Lambda que retorna o evento de entrada ao API Gateway para testar esses exemplos.

Exemplo de modelo de mapeamento de parâmetros

O exemplo a seguir transmite todos os parâmetros de solicitação, incluindo path, querystring e header, ao endpoint de integração por meio de uma carga útil 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
  }
}

Para uma solicitação que inclui os seguintes parâmetros de entrada:

  • Um parâmetro de caminho chamado myparam

  • Parâmetros de string de consulta querystring1=value1,value2&querystring2=value3

  • Cabeçalhos "header1" : "value1", "header2" : "value2", "header3" : "value3".

A saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

Exemplo de modelo de mapeamento JSON

É 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 obter o parâmetro e a carga útil, ou uma subseção da carga útil. Os três exemplos a seguir mostram como fazer isso.

O exemplo a seguir usa um modelo de mapeamento para obter uma subseção da carga útil. Este exemplo obtém o parâmetro de entrada name e todo o corpo POST:

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

Para uma solicitação que inclua os parâmetros de string de consulta name=Bella&type=dog e o seguinte corpo:

{
    "Price" : "249.99",
    "Age": "6"
}

A saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

Se a entrada JSON contiver caracteres sem escape que não podem ser analisados pelo JavaScript, o API Gateway pode retornar uma resposta 400. Aplique $util.escapeJavaScript($input.json('$')) para garantir que a entrada JSON possa ser analisada corretamente.

O exemplo anterior com $util.escapeJavaScript($input.json('$')) aplicado é o seguinte:

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

Neste caso, a saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

Exemplo de Expressão JSONPath

O exemplo a seguir mostra como transmitir uma expressão JSONPath ao método json(). Você também pode ler uma subseção do seu objeto do corpo da solicitação usando um ponto, ., para especificar uma propriedade:

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

Para uma solicitação que inclua os parâmetros de string de consulta name=Bella&type=dog e o seguinte corpo:

{
    "Price" : "249.99",
    "Age": "6"
}

A saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{
    "name" : "Bella",
    "body" : "6"
}

Se uma carga útil de solicitação de método contiver caracteres sem escape que não podem ser analisados por JavaScript, o API Gateway pode retornar uma resposta 400. Aplique $util.escapeJavaScript() para garantir que a entrada JSON possa ser analisada corretamente.

O exemplo anterior com $util.escapeJavaScript($input.json('$.Age')) aplicado é o seguinte:

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

Neste caso, a saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{
    "name" : "Bella",
    "body": "\"6\""
}

Exemplo de solicitação e resposta

O exemplo a seguir usa $input.params(), $input.path() e $input.json() para um recurso com o caminho /things/{id}:

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

Para uma solicitação que inclui o parâmetro de caminho 123 e o seguinte corpo:

{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

A saída deste modelo de mapeamento deve ser semelhante ao seguinte:

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

Se uma carga útil de solicitação de método contiver caracteres sem escape que não podem ser analisados por JavaScript, o API Gateway pode retornar uma resposta 400. Aplique $util.escapeJavaScript() para garantir que a entrada JSON possa ser analisada corretamente.

O exemplo anterior com $util.escapeJavaScript($input.json('$.things')) aplicado é o seguinte:

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

A saída deste modelo de mapeamento deve ser semelhante ao seguinte:

{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

Para ver mais exemplos de mapeamento, consulte Modelos de mapeamento para APIs REST.

$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 Usar variáveis de estágio para uma API REST no API Gateway.

Sintaxe Descrição
$stageVariables.<variable_name>, $stageVariables['<variable_name>'] ou ${stageVariables['<variable_name>']}

<variable_name> representa um 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 os caracteres em uma string usando regras de string JavaScript.

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.