# Transformações de dados para APIs de WebSocket no API Gateway No API Gateway, a solicitação de método de uma API WebSocket pode usar uma carga em um formato diferente da carga da solicitação de integração correspondente, conforme exigido no backend. De maneira semelhante, o backend pode retornar uma carga de resposta de integração diferente da carga da resposta do método, conforme esperado pelo front-end. O API Gateway permite usar transformações de modelos de mapeamento para mapear a carga útil de uma solicitação de método para a solicitação de integração correspondente ou de uma resposta de integração para a resposta de método correspondente. Você cria um modelo de mapeamento e especifica uma expressão de seleção de modelos para determinar qual deles usar para executar as transformações de dados necessárias. É possível usar mapeamentos de dados para mapear dados de uma [solicitação de rota](api-gateway-basic-concept.md#apigateway-definition-route-request) para uma integração de backend. Para saber mais, consulte [Configurar o mapeamento de dados para APIs de WebSocket no API Gateway](websocket-api-data-mapping.md). ## Modelos e modelos de mapeamento Um *modelo de mapeamento* é um script expresso em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e aplicado à carga usando [expressões JSONPath](https://goessner.net/articles/JsonPath/). Para obter mais informações sobre modelos de mapeamento do API Gateway, consulte [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md). A carga pode ter um *modelo de dados* de acordo com o [esquema JSON rascunho 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04). Não é necessário definir um modelo para criar um modelo de mapeamento. No entanto, um modelo pode ajudar você a criar um modelo, porque o API Gateway gera um esquema de modelo com base em um modelo fornecido. Para obter mais informações sobre modelos do API Gateway, consulte [Modelos de dados para APIs REST](models-mappings-models.md). ## Expressões de seleção de modelo Para transformar uma carga com um modelo de mapeamento, especifique uma expressão de seleção de modelo de API WebSocket em uma [solicitação de integração](apigateway-websocket-api-integration-requests.md) ou [resposta de integração](apigateway-websocket-api-integration-responses.md). Esta expressão é avaliada para determinar o modelo de entrada ou de saída (se houver) a ser utilizado para transformar o corpo da solicitação no corpo da solicitação de integração (por meio de um modelo de entrada) ou o corpo da resposta de integração para o corpo de resposta de rotas (por meio de um modelo de saída). `Integration.TemplateSelectionExpression` oferece suporte a `${request.body.jsonPath}` e valores estáticos. `IntegrationResponse.TemplateSelectionExpression` oferece suporte a `${request.body.jsonPath}`, `${integration.response.statuscode}`, `${integration.response.header.headerName}`, `${integration.response.multivalueheader.headerName}` e a valores estáticos. ## Expressões de seleção de resposta da integração Quando você [define uma resposta de integração](apigateway-websocket-api-integration-responses.md) para uma API WebSocket, é possível especificar opcionalmente uma expressão de seleção de resposta da integração. Esta expressão determina qual `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid-integrationresponses-integrationresponseid.html)` deve ser selecionada quando uma integração retorna. O valor dessa expressão é atualmente restrito pelo API Gateway, conforme definido abaixo. Observe que essa expressão só é relevante para *integrações não proxy*; uma integração de proxy simplesmente transmitirá a carga da resposta de volta para o autor da chamada sem modelagem ou modificação. Ao contrário de outras expressões de seleção anteriores, essa expressão é atualmente compatível com um formato de *padrão correspondente*. A expressão deve ser encapsulada com barras. Atualmente, o valor é corrigido dependendo do `[https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/apis-apiid-integrations-integrationid.html#apis-apiid-integrations-integrationid-prop-integration-integrationtype)`: + Para integrações baseadas em Lambda, é `$integration.response.body.errorMessage`. + Para integrações `HTTP` e `MOCK`, é `$integration.response.statuscode`. + Para `HTTP_PROXY` e `AWS_PROXY`, a expressão não é utilizada porque você está solicitando que a carga seja transmitida para o autor da chamada. # Configurar o mapeamento de dados para APIs de WebSocket no API Gateway O*mapeamento de dados* permite mapear dados de uma [solicitação de rota](api-gateway-basic-concept.md#apigateway-definition-route-request) para uma integração de backend. **nota** O mapeamento de dados para APIs do WebSocket não é suportado no Console de gerenciamento da AWS. É necessário usar a AWS CLI, o AWS CloudFormation, ou um SDK para configurar o mapeamento de dados. **Topics** + [Mapear dados de solicitação de rota para parâmetros de solicitação de integração](#websocket-mapping-request-parameters) + [Exemplos](#websocket-data-mapping-examples) ## Mapear dados de solicitação de rota para parâmetros de solicitação de integração Os parâmetros de solicitação de integração podem ser mapeados a partir de quaisquer parâmetros de solicitação de rota definidos, o corpo da solicitação, as variáveis [`context` ou ](api-gateway-mapping-template-reference.md#context-variable-reference) [`stage`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) e valores estáticos. A tabela a seguir mostra as expressões de mapeamento de dados da solicitação de integração. Na tabela, *`PARAM_NAME`* é o nome de um parâmetro de solicitação de rota do tipo de parâmetro especificado. Deve corresponder à expressão regular `'^[a-zA-Z0-9._$-]+$]'`. *JSONPath\$1Expression* é uma expressão JSONPath para um campo JSON do corpo da solicitação. | Fonte de dados mapeada | Expressão de mapeamento | | --- | --- | | String de consulta de solicitação (compatível apenas com a rota \$1connect) | route.request.querystring.PARAM\$1NAME | | Cabeçalho de solicitação (compatível apenas com a rota \$1connect) | route.request.header.PARAM\$1NAME | | String de consulta de solicitação de vários valores (compatível apenas com a rota \$1connect) | route.request.multivaluequerystring.PARAM\$1NAME | | Cabeçalho de solicitação de vários valores (compatível apenas com a rota \$1connect) | route.request.multivalueheader.PARAM\$1NAME | | Corpo da solicitação | route.request.body.JSONPath\$1EXPRESSION | | Variáveis de estágio | stageVariables.VARIABLE\$1NAME | | Variáveis de contexto | context.VARIABLE\$1NAME que deve ser uma das [variáveis de contexto com suporte](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valor estático | 'STATIC\$1VALUE'. STATIC\$1VALUE é um literal de string e deve estar entre aspas simples. | Ao criar um mapeamento de dados, usando a AWS CLI, siga o formato correto para usar literais com strings na AWS CLI. Para ter mais informações, consulte [Usar aspas e literais com strings na AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-quoting-strings.html) no *Guia do usuário da versão 1 da AWS Command Line Interface*. ## Exemplos Os exemplos da AWS CLI a seguir configuram mapeamentos de dados. Para obter um modelo demonstrativo do CloudFormation, consulte [samples/websocket-data-mapping.zip](samples/websocket-data-mapping.zip). ### Mapear o connectionId de um cliente para um cabeçalho em uma solicitação de integração O comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) indicado abaixo associa o `connectionId` de um cliente a um cabeçalho `connectionId` na solicitação para uma integração de backend: ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.connectionId'='context.connectionId' ``` ### Mapear um parâmetro de string de consulta para um cabeçalho em uma solicitação de integração O exemplo a seguir associa um parâmetro de string de consulta `authToken` a um cabeçalho `authToken` na solicitação de integração. 1. Use o comando [update-route](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-route.html) a seguir para adicionar o parâmetro de string de consulta `authToken` aos parâmetros de solicitação da rota. ``` aws apigatewayv2 update-route --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameters '{"route.request.querystring.authToken": {"Required": false}}' ``` 1. Use o comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-integration.html) a seguir para associar o parâmetro de string de consulta ao cabeçalho `authToken` na solicitação para a integração de backend. ``` aws apigatewayv2 update-integration \ --integration-id abc123 \ --api-id a1b2c3d4 \ --request-parameters 'integration.request.header.authToken'='route.request.querystring.authToken' ``` 1. (Opcional) Se necessário, use o comando [delete-route-request-parameter](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-route-request-parameter.html) a seguir para excluir o parâmetro de string de consulta `authToken` dos parâmetros de solicitação da rota. ``` aws apigatewayv2 delete-route-request-parameter \ --route-id 0abcdef \ --api-id a1b2c3d4 \ --request-parameter-key 'route.request.querystring.authToken' ``` # Referência de modelos de mapeamento da API de WebSocket do API Gateway Esta seção resume o conjunto de variáveis que são atualmente compatíveis com APIs WebSocket no API Gateway. | Parâmetro | Descrição | | --- | --- | | \$1context.connectionId | Um ID exclusivo para a conexão que pode ser utilizado para fazer uma chamada ao cliente. | | \$1context.connectedAt | O tempo de conexão formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time). | | \$1context.domainName | Um nome de domínio para a API WebSocket. É possível utilizá-lo para fazer uma chamada ao cliente (em vez de um valor codificado). | | \$1context.eventType | O tipo de evento: `CONNECT`, `MESSAGE` ou `DISCONNECT`. | | \$1context.messageId | Um ID exclusivo do servidor para uma mensagem. Disponível apenas quando o `$context.eventType` é `MESSAGE`. | | \$1context.routeKey | A chave de roteamento selecionada. | | \$1context.requestId | Igual a `$context.extendedRequestId`. | | \$1context.extendedRequestId | Um ID gerado automaticamente para a chamada de API, que contém mais informações úteis para depuração/solução de problemas. | | \$1context.apiId | O identificador que o API Gateway atribui à sua API. | | \$1context.authorizer.principalId | A identificação do usuário principal associada ao token enviado pelo cliente e retornada por uma função do Lambda do autorizador do Lambda do API Gateway (anteriormente conhecido como autorizador personalizado). | | \$1context.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"`. | | \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". | | \$1context.error.validationErrorString | Uma string que contém uma mensagem de erro de validação detalhada. | | \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. | | \$1context.identity.apiKey | A chave do proprietário da API associada à solicitação de API habilitada por chave. | | \$1context.identity.apiKeyId | O ID da chave da API associada à solicitação de API habilitada por chave | | \$1context.identity.caller | O identificador principal do agente de chamada que está fazendo a solicitação. | | \$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.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 principal do usuário que está fazendo a solicitação. | | \$1context.identity.userAgent | O agente de usuário 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. | | \$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 tempo de solicitação formatado em [Epoch](https://en.wikipedia.org/wiki/Unix_time), em milissegundos. | | \$1context.stage | O estágio de implantação da chamada de API (por exemplo, Beta ou Prod). | | \$1context.status | O status da resposta. | | \$1input.body | Retorna a carga bruta como uma string. | | \$1input.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](https://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/json-path/JsonPath). | | \$1input.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)](https://velocity.apache.org/engine/devel/vtl-reference.html). 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](http://goessner.net/articles/JsonPath/) ou [JSONPath para Java](https://github.com/jayway/JsonPath). | | \$1stageVariables. | ** representa um nome de variável de estágio. | | \$1stageVariables[''] | ** representa qualquer nome de variável de estágio. | | \$1\$1stageVariables['']\$1 | ** representa qualquer nome de variável de estágio. | | \$1util.escapeJavaScript() | Escapa os caracteres em uma string usando regras de string JavaScript. 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("\\'","'")
| | \$1util.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
}
| | \$1util.urlEncode() | Converte uma string no formato "application/x-www-form-urlencoded". | | \$1util.urlDecode() | Decodifica uma string "application/x-www-form-urlencoded". | | \$1util.base64Encode() | Codifica os dados em uma string codificada em base64. | | \$1util.base64Decode() | Decodifica os dados de uma string codificada em base64. |