Menu
Amazon API Gateway
Guia do desenvolvedor

Referência 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

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 uma função Lambda do autorizador do Lambda do API Gateway (anteriormente conhecido como autorizador personalizado).

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

$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. 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.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 de variável simples em um modelo de mapeamento de corpo GatewayResponse, que não é processado pelo mecanismo VTL (Velocity Template Language).

$context.extendedRequestId Um ID gerado automaticamente para a chamada de API, que contém mais informações úteis para depuração/solução de problemas.
$context.identity.accountId

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

$context.identity.apiKey

A chave do proprietário da API associada à solicitação de API habilitada por chave.

$context.identity.apiKeyId O ID da chave da API associada à solicitação de API habilitada por chave
$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.integrationLatency A latência de integração em ms, disponível somente para registro de log de acesso.
$context.path O caminho da solicitação. 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.path é /{stage}/root/child.
$context.protocol O protocolo de solicitação, por exemplo, é HTTP/1.1.
$context.requestId

Um ID gerado automaticamente para a chamada de API.

$context.requestTime O horário da solicitação CLF formatado (dd/MMM/yyyy:HH:mm:ss +-hhmm.
$context.requestTimeEpoch O horário da solicitação Epoch formatado.
$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 obter mais informações, consulte Criar uma API com integração personalizada HTTP.

$context.responseLength O tamanho da carga de resposta, disponível para registro de acesso em logs apenas.
$context.responseLatency A latência de resposta em ms, disponível somente para registro de log de acesso.
$context.status O status de resposta, disponível para registro de acesso em logs apenas.
$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 um modelo de mapeamento para mapear variáveis de contexto para uma carga de solicitação de integração:

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

No exemplo acima, pressupõe-se que o método tenha uma chave de API habilitada. Se a chave de API não for exigida na solicitação do método, api_key será nulo.

Para solicitações do tipo de autorização AWS_IAM, você pode passar as informações do usuário autorizado para o endpoint de integração com propriedades de $context.identity.*. Para solicitações do tipo de autorização COGNITO_USER_POOLS, as informações do usuário autorizado também incluem propriedades $context.identity.cognito* e $context.authorizer.claims.*. Para solicitações que usam um autorizador do Lambda, você pode passar $context.authorizer.principalId e outras propriedades $context.authorizer.* aplicáveis como contexto de usuário autorizado adicional para o endpoint de integração.

Com uma integração de proxy, o API Gateway passa as informações de identidade autorizadas para o back-end no objeto requestContext.identity. Você não configura um modelo de mapeamento, mas analisa explicitamente a entrada para o back-end de integração. A tabela a seguir mostra um exemplo de requestContext passado para um endpoint de integração de proxy Lambda quando o tipo de autorização é definido como AWS_IAM.

{ ..., "requestContext": { "requestTime": "20/Feb/2018:22:48:57 +0000", "path": "/test/", "accountId": "123456789012", "protocol": "HTTP/1.1", "resourceId": "yx5mhem7ye", "stage": "test", "requestTimeEpoch": 1519166937665, "requestId": "3c3ecbaa-1690-11e8-ae31-8f39f1d24afd", "identity": { "cognitoIdentityPoolId": null, "accountId": "123456789012", "cognitoIdentityId": null, "caller": "AIDAJ........4HCKVJZG", "sourceIp": "51.240.196.104", "accessKey": "IAM_user_access_key", "cognitoAuthenticationType": null, "cognitoAuthenticationProvider": null, "userArn": "arn:aws:iam::123456789012:user/alice", "userAgent": "PostmanRuntime/7.1.1", "user": "AIDAJ........4HCKVJZG" }, "resourcePath": "/", "httpMethod": "GET", "apiId": "qr2gd9cfmf" }, ... }

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:

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

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

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

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

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

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 Criar modelos e modelos de mapeamento para mapeamentos 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:

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