# Transformar solicitações e respostas de API para APIs HTTP no API Gateway
<a name="http-api-parameter-mapping"></a>

Você pode modificar solicitações de API dos clientes antes que eles atinjam suas integrações de backend. Você também pode alterar a resposta das integrações antes que o API Gateway retorne a resposta aos clientes. Use o *mapeamento de parâmetros* para modificar solicitações e respostas de API para APIs HTTP. Para usar o mapeamento de parâmetros, especifique os parâmetros de solicitação de API ou resposta a serem modificados e especifique como modificar esses parâmetros.



## Transformação de solicitações de API
<a name="http-api-mapping-request-parameters"></a>

Você usa parâmetros de solicitação para alterar solicitações antes que elas atinjam suas integrações de backend. Você pode modificar cabeçalhos, strings de consulta ou o caminho da solicitação.

Os parâmetros de solicitação são um mapa de chave-valor. A chave identifica a localização do parâmetro da solicitação a ser alterado e como alterá-lo. O valor especifica os novos dados para o parâmetro.

A tabela a seguir mostra as chaves suportadas.


| Tipo | Sintaxe | 
| --- | --- | 
| Cabeçalho | append\$1overwrite\$1remove:header.headername | 
| String de consulta | append\$1overwrite\$1remove:querystring.querystring-name | 
| Caminho | overwrite:path | 

A tabela a seguir mostra os valores suportados que você pode mapear para parâmetros.


| Tipo | Sintaxe | Observações | 
| --- | --- | --- | 
| Valor de cabeçalho | \$1request.header.name ou \$1\$1request.header.name\$1 | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". Alguns cabeçalhos são reservados. Para saber mais, consulte [Cabeçalhos reservados](#http-api-mapping-reserved-headers). | 
| Valor da string de consulta | \$1request.querystring.name ou \$1\$1request.querystring.name\$1 | Os nomes de strings de consulta diferenciam maiúsculas e minúsculas O API Gateway combina vários valores com vírgulas, por exemplo, "querystring1" "Value1,Value2". | 
| Corpo da solicitação | \$1request.body.name ou \$1\$1request.body.name\$1 | Uma expressão de caminho JSON. Descida recursiva (\$1request.body..name) e expressões de filtro (?(expression)) não são suportadas.  Quando você especifica um caminho JSON, o API Gateway trunca o corpo da solicitação em 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$request.body`.   | 
| O caminho da solicitação. | \$1request.path ou \$1\$1request.path\$1 | O caminho da solicitação, sem o nome do estágio. | 
| Parâmetro de caminho | \$1request.path.name ou \$1\$1request.path.name\$1 | O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/\$1petId\$1, você poderá mapear o parâmetro petId da solicitação com \$1request.path.petId. | 
| Variável de contexto | \$1context.variableName ou \$1\$1context.variableName\$1 | O valor de uma [variável de contexto](http-api-logging-variables.md). Somente os caracteres especiais `.` e `_` são aceitos. | 
| Variável de estágio | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | 
| Valor estático | string | Um valor constante. | 

**nota**  
Para usar mais de uma variável em uma expressão de seleção, inclua a variável entre colchetes. Por exemplo, `${request.path.name} ${request.path.id}`.

## Transformando respostas da API
<a name="http-api-mapping-response-parameters"></a>

Você usa parâmetros de resposta para transformar a resposta HTTP de uma integração de backend antes de retornar a resposta aos clientes. Você pode modificar cabeçalhos ou o código de status de uma resposta antes que o API Gateway retorne a resposta aos clientes.

Você configura os parâmetros de resposta para cada código de status que sua integração retorna. Os parâmetros de resposta são um mapa de chave-valor. A chave identifica a localização do parâmetro da solicitação a ser alterado e como alterá-lo. O valor especifica os novos dados para o parâmetro.

A tabela a seguir mostra as chaves suportadas.


| Tipo | Sintaxe | 
| --- | --- | 
| Cabeçalho | append\$1overwrite\$1remove:header.headername | 
| Código de status | overwrite:statuscode | 

A tabela a seguir mostra os valores suportados que você pode mapear para parâmetros.


| Tipo | Sintaxe | Observações | 
| --- | --- | --- | 
| Valor de cabeçalho | \$1response.header.nome ou \$1\$1response.header.nome\$1 | Nomes de cabeçalhos não diferenciam maiúsculas de minúsculas. O API Gateway combina vários valores de cabeçalho com vírgulas, por exemplo, "header1": "value1,value2". Alguns cabeçalhos são reservados. Para saber mais, consulte [Cabeçalhos reservados](#http-api-mapping-reserved-headers). | 
| Corpo da resposta | \$1response.body.name ou \$1\$1response.body.name\$1 | Uma expressão de caminho JSON. Descidas recursivas (\$1response.body..name) e expressões de filtro (?(expression)) não são compatíveis.  Quando você especifica um caminho JSON, o API Gateway trunca o corpo da resposta a 100 KB e, em seguida, aplica a expressão de seleção. Para enviar cargas maiores que 100 KB, especifique `$response.body`.   | 
| Variável de contexto | \$1context.variableName ou \$1\$1context.variableName\$1 | O valor de uma [variável de contexto](http-api-logging-variables.md) compatível. | 
| Variável de estágio | \$1stageVariables.variableName ou \$1\$1stageVariables.variableName\$1 | O valor de uma [variável de estágio](http-api-stages.stage-variables.md). | 
| Valor estático | string | Um valor constante. | 

**nota**  
Para usar mais de uma variável em uma expressão de seleção, inclua a variável entre colchetes. Por exemplo, `${request.path.name} ${request.path.id}`.

## Cabeçalhos reservados
<a name="http-api-mapping-reserved-headers"></a>

Os seguintes cabeçalhos são reservados. Não é possível configurar mapeamentos de solicitação ou resposta para esses cabeçalhos.
+ access-control-\$1
+ apigw-\$1
+ Autorização
+ Conexão
+ Content-Encoding
+ Content-Length
+ Content-Location
+ Encaminhado
+ Keep-alive
+ Origem
+ Proxy-Authenticate
+ Proxy-Authorization
+ TE
+ Trailers 
+ Transfer-Encoding
+ Upgrade
+ x-amz-\$1
+ x-amzn-\$1
+ X-Forwarded-For
+ X-Forwarded-Host
+ X-Forwarded-Proto
+ Via

## Exemplos
<a name="http-api-parameter-mapping-examples"></a>

Os exemplos da AWS CLI a seguir configuram mapeamentos de dados. Para ver modelos de exemplo do CloudFormation, consulte o [GitHub](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).

### Adicionar um cabeçalho a uma solicitação de API
<a name="http-api-parameter-mapping-examples-request-header"></a>

O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir cria um cabeçalho chamado `header1` para uma solicitação de API antes que ela atinja sua integração de backend. O API Gateway preenche o cabeçalho com o ID da solicitação.

```
aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header1": "$context.requestId" }'
```

### Renomear um cabeçalho de solicitação
<a name="http-api-parameter-mapping-examples-response"></a>

O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) indicado abaixo renomeia um cabeçalho de solicitação de `header1` para `header2`:

```
aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --request-parameters '{ "append:header.header2": "$request.header.header1",  "remove:header.header1": "''"}'
```

### Alterar a resposta de uma integração
<a name="http-api-parameter-mapping-examples-response"></a>

O comando [create-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir configura parâmetros de resposta para uma integração. Quando as integrações retornam um código de status 500, o API Gateway altera o código de status para 403 e adiciona `header1`1 à resposta. Quando a integração retorna um código de status 404, o API Gateway adiciona um `error` cabeçalho à resposta.

```
aws apigatewayv2 create-integration \
    --api-id abcdef123 \
    --integration-type HTTP_PROXY \
    --payload-format-version 1.0 \
    --integration-uri 'https://api.example.com' \
    --integration-method ANY \
    --response-parameters '{"500" : {"append:header.header1": "$context.requestId", "overwrite:statuscode" : "403"}, "404" : {"append:header.error" : "$stageVariables.environmentId"}  }'
```

### Remover mapeamentos de parâmetros configurados
<a name="http-api-parameter-mapping-examples-remove"></a>

O comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-integration.html) a seguir remove os parâmetros de solicitação configurados anteriormente para `append:header.header1`. Ele também remove parâmetros de resposta previamente configurados para um código de status 200.

```
aws apigatewayv2 update-integration \
    --api-id abcdef123 \
    --integration-id hijk456 \
    --request-parameters '{"append:header.header1" : ""}' \
    --response-parameters '{"200" : {}}'
```