Transformar solicitações e respostas de API para APIs HTTP no API Gateway - Amazon API Gateway
Transformação de solicitações de APITransformando respostas da APICabeçalhos reservadosExemplos

Transformar solicitações e respostas de API para APIs HTTP no API Gateway

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

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|overwrite|remove:header.headername
String de consulta append|overwrite|remove: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 $request.header.name ou ${request.header.name} 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.
Valor da string de consulta $request.querystring.name ou ${request.querystring.name} 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 $request.body.name ou ${request.body.name} Uma expressão de caminho JSON. Descida recursiva ($request.body..name) e expressões de filtro (?(expression)) não são suportadas.
nota

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. $request.path ou ${request.path} O caminho da solicitação, sem o nome do estágio.
Parâmetro de caminho $request.path.name ou ${request.path.name} O valor de um parâmetro de caminho na solicitação. Por exemplo, se a rota for /pets/{petId}, você poderá mapear o parâmetro petId da solicitação com $request.path.petId.
Variável de contexto $context.variableName ou ${context.variableName} O valor de uma variável de contexto.
nota

Somente os caracteres especiais . e _ são aceitos.
Variável de estágio $stageVariables.variableName ou ${stageVariables.variableName} O valor de uma variável de estágio.
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

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|overwrite|remove: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 $response.header.nome ou ${response.header.nome} 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.
Corpo da resposta $response.body.name ou ${response.body.name} Uma expressão de caminho JSON. Descidas recursivas ($response.body..name) e expressões de filtro (?(expression)) não são compatíveis.
nota

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 $context.variableName ou ${context.variableName} O valor de uma variável de contexto compatível.
Variável de estágio $stageVariables.variableName ou ${stageVariables.variableName} O valor de uma variável de estágio.
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

Os seguintes cabeçalhos são reservados. Não é possível configurar mapeamentos de solicitação ou resposta para esses cabeçalhos.

  • access-control-*

  • apigw-*

  • 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-*

  • x-amzn-*

  • X-Forwarded-For

  • X-Forwarded-Host

  • X-Forwarded-Proto

  • Via

Exemplos

Os exemplos da AWS CLI a seguir configuram mapeamentos de dados. Para ver modelos de exemplo do AWS CloudFormation, consulte o GitHub.

Adicionar um cabeçalho a uma solicitação de API

O exemplo a seguir adiciona um cabeçalho chamado header1 a uma solicitação de API antes que ele 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

O exemplo a seguir 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

O exemplo 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 header11 à 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

O comando de exemplo 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" : {}}'