# Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway
É possível usar transformações de modelos de mapeamento para substituir qualquer tipo de parâmetro de solicitação, cabeçalho de resposta ou código de status da resposta. Use um modelo de mapeamento para fazer o seguinte:
+ Executar mapeamentos de parâmetros muitos para um.
+ Substituir os parâmetros após a aplicação dos mapeamentos padrão do API Gateway
+ Associar parâmetros condicionalmente com base no conteúdo do corpo ou outros valores de parâmetros.
+ Criar parâmetros de modo programático.
+ Substituir os códigos de status exibidos pelo seu endpoint de integração.
As substituições são feitas no final. Uma substituição só pode ser aplicada a um parâmetro por vez. Se você tentar substituir o mesmo parâmetro várias vezes, o API Gateway vai gerar uma resposta `5XX`. Se você tiver de substituir o mesmo parâmetro várias vezes em todo o modelo, é recomendável criar uma variável e aplicar a substituição no final do modelo. O modelo é aplicado somente depois que todo o modelo é analisado.
## Exemplo 1: substituir o código de status com base no corpo da integração
Veja a seguir como usar a [API de exemplo](api-gateway-create-api-from-example.md) para substituir o código de status com base no corpo da resposta de integração.
------
#### [ Console de gerenciamento da AWS ]
**Como substituir um código de status com base no corpo da resposta de integração**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione **Create API** (Criar API).
1. Em **API REST**, escolha **Criar**.
1. Em **Detalhes da API**, escolha **API de exemplo**.
1. Selecione **Criar API**.
O API Gateway cria uma API de exemplo da loja de animais de estimação. Para recuperar informações sobre um animal de estimação, você usa a solicitação de método de API de `GET /pets/{petId}`, em que `{petId}` é um parâmetro de caminho correspondente a um número de ID de um animal de estimação.
Nesse exemplo, você substitui o código de resposta do método `GET` por `400` quando uma condição de erro é detectada.
1. Na árvore **Recursos**, selecione o método `GET` em `/{petId}`.
1. Primeiro, você testa a implementação atual da API.
Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **petId**, insira **-1** e, depois, selecione **Testar**.
O **Corpo da resposta** indica um erro fora do intervalo:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Além disso, a última linha em **Logs** termina com: `Method completed with status: 200`.
A integração foi concluída com sucesso, mas houve um erro. Agora, você vai substituir o código de status com base na resposta de integração.
1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**.
1. Selecione **Modelos de mapeamento**.
1. Escolha **Add mapping template** (Adicionar modelo de mapeamento).
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Corpo do modelo**, insira o seguinte:
```
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
```
Esse modelo de mapeamento usa a variável `$context.responseOverride.status` para substituir o código de status por `400` se a resposta de integração contiver a string `error`.
1. Escolha **Salvar**.
1. Selecione a guia **Testar**.
1. Em **petId**, insira **-1**.
1. Nos resultados, **Response Body (Corpo da resposta)** indica um erro fora do intervalo:
```
{
"errors": [
{
"key": "GetPetRequest.petId",
"message": "The value is out of range."
}
]
}
```
Entretanto, a última linha em **Logs** agora termina com: `Method completed with status: 400`.
------
#### [ CloudFormation ]
Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 1
description: Example pet store API.
version: "2025-01-14T00:13:18Z"
paths:
/pets/{petId}:
get:
parameters:
- name: petId
in: path
required: true
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}
responses:
default:
statusCode: "200"
responseTemplates:
application/json: |-
#set($inputRoot = $input.path('$'))
$input.json("$")
#if($inputRoot.toString().contains("error"))
#set($context.responseOverride.status = 400)
#end
requestParameters:
integration.request.path.petId: method.request.path.petId
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
A definição de OpenAPI a seguir cria o recurso `GET pets/{petId}` e substitui o código de status com base no corpo da integração.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 1",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:13:18Z"
},
"paths" : {
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}",
"responses" : {
"default" : {
"statusCode" : "200",
"responseTemplates" : {
"application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end"
}
}
},
"requestParameters" : {
"integration.request.path.petId" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
},
"components" : {
"schemas" : {
"Pet" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "integer"
},
"type" : {
"type" : "string"
},
"price" : {
"type" : "number"
}
}
}
}
}
}
```
------
## Exemplo 2: substituir o cabeçalho da solicitação e criar outros cabeçalhos
O exemplo a seguir usa a [API de exemplo](api-gateway-create-api-from-example.md) para substituir o cabeçalho da solicitação e criar outros cabeçalhos.
------
#### [ Console de gerenciamento da AWS ]
**Como substituir o cabeçalho de solicitação de um método criando outro cabeçalho**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha a API de exemplo que você criou no tutorial anterior. O nome da API deve ser **PetStore**.
1. Na árvore **Recursos**, selecione o método `GET` em `/pet`.
1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, selecione **Editar**.
1. Selecione **Cabeçalhos de solicitação HTTP** e, depois, **Adicionar cabeçalho**.
1. Em **Nome**, digite **header1**.
1. Selecione **Adicionar cabeçalho** e, depois, crie um segundo cabeçalho chamado **header2**.
1. Escolha **Salvar**.
Agora, você combina esses cabeçalhos em um valor de cabeçalho usando um modelo de mapeamento.
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Em **Passagem do corpo da solicitação**, selecione **Quando não há modelos definidos (recomendado)**.
1. Selecione **Modelos de mapeamento** e, depois, faça o seguinte:
1. Escolha **Add mapping template** (Adicionar modelo de mapeamento).
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Corpo do modelo**, insira o seguinte:
```
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
```
Esse modelo de mapeamento substitui `header1` pela string `pets` e cria um cabeçalho de vários valores chamado `$header3Value` que combina `header1` e `header2`.
1. Escolha **Salvar**.
1. Selecione a guia **Testar**.
1. Em **Cabeçalhos**, copie o seguinte código:
```
header1:header1Val
header2:header2Val
```
1. Escolha **Test** (Testar).
Em **Logs**, você deve ver uma entrada que inclui este texto:
```
Endpoint request headers: {header3=header1Valheader2Val,
header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id,
Accept=application/json, multivalueheader=pets,header1Valheader2Val}
```
------
#### [ CloudFormation ]
Nesse exemplo, você usa a propriedade [corpo](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) para importar um arquivo de definição da OpenAPI para o API Gateway.
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: PetStore Example 2
description: Example pet store API.
version: "2025-01-14T00:36:18Z"
paths:
/pets:
get:
parameters:
- name: header2
in: header
schema:
type: string
- name: page
in: query
schema:
type: string
- name: type
in: query
schema:
type: string
- name: header1
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.header1: method.request.header.header1
integration.request.header.header2: method.request.header.header2
integration.request.querystring.page: method.request.querystring.page
integration.request.querystring.type: method.request.querystring.type
requestTemplates:
application/json: |-
#set($header1Override = "pets")
#set($header3Value = "$input.params('header1')$input.params('header2')")
$input.json("$")
#set($context.requestOverride.header.header3 = $header3Value)
#set($context.requestOverride.header.header1 = $header1Override)
#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])
passthroughBehavior: when_no_match
type: http
components:
schemas:
Pet:
type: object
properties:
id:
type: integer
type:
type: string
price:
type: number
ApiGatewayDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
ApiGatewayDeployment20250219:
Type: 'AWS::ApiGateway::Deployment'
DependsOn: Api
Properties:
RestApiId: !Ref Api
Stage:
Type: 'AWS::ApiGateway::Stage'
Properties:
DeploymentId: !Ref ApiGatewayDeployment20250219
RestApiId: !Ref Api
StageName: prod
```
------
#### [ OpenAPI ]
A definição de OpenAPI a seguir cria o recurso `GET pets`, substitui o cabeçalho da solicitação e cria outros cabeçalhos.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "PetStore Example 2",
"description" : "Example pet store API.",
"version" : "2025-01-14T00:36:18Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "header2",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "page",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "type",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "header1",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.header1" : "method.request.header.header1",
"integration.request.header.header2" : "method.request.header.header2",
"integration.request.querystring.page" : "method.request.querystring.page",
"integration.request.querystring.type" : "method.request.querystring.type"
},
"requestTemplates" : {
"application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
Para usar uma substituição de modelo de mapeamento, adicione uma ou mais das variáveis `$context` a seguir. Consulte uma lista de variáveis `$context` em [Variáveis de contexto para transformações de dados](api-gateway-mapping-template-reference.md#context-variable-reference).