Menu
Amazon API Gateway
Guia do desenvolvedor

Funções e variáveis internas de modelos de mapeamento do API Gateway

O Amazon API Gateway define um conjunto de variáveis e funções para trabalhar com modelos e modelos de mapeamento. Este documento descreve essas funções e fornece exemplos para trabalhar com cargas de entrada.

Acessando a variável $context

A variável $context contém todas as informações contextuais da sua chamada de API.

Referência da variável $context

Parâmetro Descrição
$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 agente de chamada do método é autenticado com êxito.

nota

$context.authorizer.claims
$context.authorizer.principalId

A identificação de usuário principal associada ao token enviado pelo cliente e retornado de uma função Lambda de autorizador personalizado do API Gateway.

$context.authorizer.property

O valor transformado em string do par de chave/valor especificado do mapa context retornado de uma função Lambda de autorizador personalizado do API Gateway. Por exemplo, se o autorizador retornar o seguinte mapa context:

Copy
"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".

$context.httpMethod

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

$context.error.message

Uma string de uma mensagem de erro do API Gateway personalizável. Essa variável só pode ser usada para substituição de variável simples em um modelo de mapeamento de corpo GatewayResponse, que não é processado pelo mecanismo VTL (Velocity Template Language).

$context.error.responseType

Um tipo de GatewayResponse. Essa variável só pode ser usada para substituição de variável simples em um modelo de mapeamento de corpo GatewayResponse, que não é processado pelo mecanismo VTL (Velocity Template Language).

$context.identity.accountId

O ID da conta da AWS associado à solicitação.

$context.identity.apiKey

A chave do proprietário da API associada à sua API.

$context.identity.caller

O identificador principal do agente de chamada que está fazendo a solicitação.

$context.identity.cognitoAuthenticationProvider

O provedor de autenticação do Amazon Cognito usado pelo agente de chamada que está fazendo a solicitação. Disponível apenas se a solicitação tiver sido assinada com as credenciais do Amazon Cognito.

Para obter informações relacionadas a esta e as outras variáveis $context do Amazon Cognito, consulte o tópico sobre como usar identidades federadas no Amazon Cognito Developer Guide.

$context.identity.cognitoAuthenticationType

O tipo de autenticação do Amazon Cognito usado pelo agente de chamada que está fazendo a solicitação. Disponível apenas se a solicitação tiver sido assinada com as credenciais do Amazon Cognito.

$context.identity.cognitoIdentityId

O ID de identidade do Amazon Cognito usado pelo agente de chamada que está fazendo a solicitação. Disponível apenas se a solicitação tiver sido assinada com as credenciais do Amazon Cognito.

$context.identity.cognitoIdentityPoolId

O ID do grupo de identidades do Amazon Cognito usado pelo agente de chamada que está fazendo a solicitação. Disponível apenas se a solicitação tiver sido assinada com as credenciais do Amazon Cognito.

$context.identity.sourceIp

O endereço IP de origem da conexão TCP que está fazendo a solicitação para ao API Gateway.

$context.identity.user

O identificador principal do usuário que está fazendo a solicitação.

$context.identity.userAgent

O Agente de usuário do agente de chamada da API.

$context.identity.userArn

O Nome do Recurso Amazon (ARN) do usuário efetivo identificado após a autenticação.

$context.requestId

Um ID gerado automaticamente para a chamada de API.

$context.resourceId

O identificador que o API Gateway atribui ao seu recurso.

$context.resourcePath

O caminho para o seu recurso. Para obter mais informações, consulte Construir uma API do API Gateway para expor um endpoint HTTP.

$context.stage

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

Exemplo

Você pode querer usar a variável $context quando está usando o AWS Lambda como o back-end de destino que é chamado pelo método de API. Por exemplo, talvez você queira realizar duas ações diferentes, dependendo de o estágio estar em Beta ou Prod.

Exemplo de modelo de variáveis de contexto

O exemplo a seguir mostra como obter variáveis de contexto:

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

Acessando a variável $input

A variável $input representa a carga de entrada e os parâmetros a serem processados pelo seu modelo. Ela fornece quatro funções:

Referência de funções

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

Retorna a carga 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') retornará uma string JSON que representa a estrutura de animais de estimação.

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 da sua chamada de API.

$input.params(x)

Retorna o valor de um parâmetro de solicitação de método do caminho, da string de consulta ou do valor de cabeçalho (nessa ordem), considerando uma string de nome de parâmetro x.

$input.path(x)

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

Por exemplo, $input.path('$.pets').size()

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

Exemplos

Você pode querer usar a variável $input para obter strings de consulta e o corpo da solicitação com ou sem o uso de modelos. Você também pode querer inserir o parâmetro e a carga, ou uma subseção da carga, na sua função AWS Lambda. Os exemplos abaixo mostram como fazer isso.

Exemplo de modelo de mapeamento JSON

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:

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

Se a entrada JSON contiver caracteres sem escape que não podem ser analisados pelo JavaScript, uma resposta 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 de entradas

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:

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

Se uma carga de solicitação de método contiver caracteres sem escape que não podem ser analisados pelo 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:

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

Exemplo de modelo de mapeamento de parâmetros

O seguinte exemplo de mapeamento de parâmetros transmite todos os parâmetros, incluindo o caminho, a string de consulta e o cabeçalho, ao endpoint de integração por meio de uma carga JSON

Copy
#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:

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

Exemplo de solicitação e resposta

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

Request Template:

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

Response:

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

Para ver mais exemplos de mapeamento, consulte Criar modelos e modelos de mapeamento para cargas de solicitação e resposta

Acessando a variável $stageVariables

A sintaxe para inserir uma variável de estágio é semelhante a esta: $stageVariables.

Referência da variável $stageVariables

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.

Acessando a variável $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.

Referência da variável $util

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:

Copy
$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:

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

e usar o seguinte modelo de mapeamento

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

Você receberá a seguinte saída:

Copy
{ "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.

Comportamentos de passagem direta de integração

Quando uma solicitação de método contém uma carga e o cabeçalho Content-Type não corresponde a nenhum modelo de mapeamento especificado, ou nenhum modelo de mapeamento está definido, você pode optar por transmitir a carga da solicitação fornecida pelo cliente na solicitação de integração para o back-end sem transformação. O processo é conhecido como passagem direta de integração. O comportamento de passagem direta real de uma solicitação de entrada é determinado pela opção que você escolhe para um modelo de mapeamento especificado, durante a configuração da solicitação de integração, e pelo cabeçalho Content-Type que um cliente define na solicitação de entrada. Os exemplos a seguir ilustram os possíveis comportamentos de passagem direta.

Exemplo 1: um modelo de mapeamento é definido na solicitação de integração para o tipo de conteúdo application/json.

Cabeçalho Content-Type\Opção de passagem direta selecionada WHEN_NO_MATCH WHEN_NO_TEMPLATE NEVER
Nenhum (padrão para application/json A carga da solicitação é transformada usando o modelo. A carga da solicitação é transformada usando o modelo. A carga da solicitação é transformada usando o modelo.
application/json A carga da solicitação é transformada usando o modelo. A carga da solicitação é transformada usando o modelo. A carga da solicitação é transformada usando o modelo.
application/xml A carga da solicitação não é transformada e é enviada ao back-end no estado em que se encontra. A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type.

Exemplo 2: um modelo de mapeamento é definido na solicitação de integração para o tipo de conteúdo application/xml.

Cabeçalho Content-Type\Opção de passagem direta selecionada WHEN_NO_MATCH WHEN_NO_TEMPLATE NEVER
Nenhum (padrão para application/json A carga da solicitação não é transformada e é enviada ao back-end no estado em que se encontra. A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type.
application/json A carga da solicitação não é transformada e é enviada ao back-end no estado em que se encontra. A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type.
application/xml A carga da solicitação é transformada usando o modelo. A carga da solicitação é transformada usando o modelo. A carga da solicitação é transformada usando o modelo.