# Transformações de dados para APIs REST no API Gateway
**nota**
Essa seção explica os recursos que você usa com uma integração sem proxy. No entanto, recomendamos que, quando possível, você use uma integração com proxy para a API REST. Uma integração com proxy HTTP tem uma configuração de integração simplificada e pode evoluir com o backend sem a necessidade de descartar a configuração existente. Para obter mais informações, consulte [Escolher um tipo de integração de API do API Gateway](api-gateway-api-integration-types.md).
Se usar uma integração sem proxy, você poderá utilizar dois recursos do API Gateway para transformar a solicitação de método e a resposta da integração. Você poderá transformar a solicitação do método se ela usar um formato de carga útil diferente da carga útil da solicitação de integração. Será possível transformar a resposta da integração se ela retornar um formato de carga útil diferente do formato que você precisa retornar na resposta do método. Consulte mais informações sobre o ciclo de vida da solicitação em [Exemplo de recurso para uma API REST](rest-api-develop.md#rest-api-develop-example).
O exemplo a seguir mostra uma transformação de dados em que, para o cabeçalho `"x-version:beta"`, o parâmetro de cabeçalho `x-version` é transformado no parâmetro de cabeçalho `app-version`. A transformação dos dados de `x-version` para `app-version` ocorre na solicitação de integração. Dessa forma, o endpoint de integração recebe o valor do parâmetro do cabeçalho transformado. Quando o endpoint de integração retorna um código de status, esse código é transformado de `200` para `204` antes da resposta do método.
![\[Diagrama de transformação de dados do API Gateway\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/develop-non-proxy.png)
Para criar uma transformação de dados, é possível usar os seguintes recursos:
**Mapeamento de parâmetros**
No mapeamento de parâmetros, você pode modificar os parâmetros do caminho do URL da solicitação de integração, os parâmetros da string de consulta do URL ou os valores do cabeçalho HTTP, mas não pode modificar a carga útil da solicitação de integração. Você também pode modificar os valores do cabeçalho de resposta HTTP. Use o mapeamento de parâmetros para criar valores de cabeçalho estáticos para compartilhamento de recursos de origem cruzada (CORS).
É possível usar o mapeamento de parâmetros em sua solicitação de integração para integrações de proxy e não proxy, mas para usar o mapeamento de parâmetros para uma resposta de integração, você precisa de uma integração não proxy. O mapeamento de parâmetros não requer nenhuma programação em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Para obter mais informações, consulte [Mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping.md).
**Transformações de modelo de mapeamento**
Nas transformações de modelo de mapeamento, você usa um modelo de mapeamento para mapear parâmetros de caminho de URL, parâmetros de string de consulta de URL, cabeçalhos HTTP e o corpo da solicitação de integração ou resposta de integração. *Modelo de mapeamento* é um script expresso em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) que usa [expressões JSONPath](https://goessner.net/articles/JsonPath/) e é aplicado à carga útil com base no cabeçalho `Content-type`.
Com um modelo de mapeamento, é possível fazer o seguinte:
+ Selecionar quais dados enviar usando a integração a Serviços da AWS, como funções do Amazon DynamoDB ou do Lambda ou endpoints HTTP. Para obter mais informações, consulte [Tutorial: modificar a solicitação e a resposta de integração para integrações a serviços da AWS](set-up-data-transformations-in-api-gateway.md).
+ Substituir condicionalmente os parâmetros de solicitação e resposta de integração de uma API, criar valores de cabeçalho e substituir códigos de status. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md).
Você também pode especificar o comportamento da API quando um corpo de solicitação de integração tem um cabeçalho `Content-type` sem modelos de mapeamento correspondentes. Isso é chamado de comportamento de passagem direta de integração. Para obter mais informações, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md).
## Escolher entre mapeamento de parâmetros e transformações de modelos de mapeamento
Recomendamos que você use o mapeamento de parâmetros para transformar dados quando possível. Se a API exigir que você altere o corpo ou execute substituições e modificações condicionais com base na solicitação de integração recebida ou na resposta de integração, e não for possível usar uma integração com proxy, use transformações de modelo de mapeamento.
# Mapeamento de parâmetros para APIs REST no API Gateway
**nota**
Se você estiver usando uma API HTTP, consulte [Transformar solicitações e respostas de API para APIs HTTP no API Gateway](http-api-parameter-mapping.md).
No mapeamento de parâmetros, você mapeia os parâmetros de solicitação ou resposta. É possível mapear parâmetros usando expressões de mapeamento de parâmetros ou valores estáticos. Consulte uma lista de expressões de mapeamento em [Referência da origem do mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping-sources.md). É possível usar o mapeamento de parâmetros em sua solicitação de integração para integrações de proxy e não proxy, mas para usar o mapeamento de parâmetros para uma resposta de integração, você precisa de uma integração não proxy.
Por exemplo, você pode mapear o parâmetro do cabeçalho da solicitação do método `puppies` para o parâmetro do cabeçalho da solicitação de integração `DogsAge0`. Então, se um cliente enviar o cabeçalho `puppies:true` para a API, a solicitação de integração enviará o cabeçalho da solicitação `DogsAge0:true` ao endpoint de integração. O diagrama a seguir mostra o ciclo de vida da solicitação nesse exemplo.
![\[Diagrama do exemplo de mapeamento de parâmetros do API Gateway para uma solicitação\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/parameter-mapping-example1.png)
Para criar esse exemplo usando o API Gateway, consulte [Exemplo 1: mapear um parâmetro de solicitação de método para um parâmetro de solicitação de integração](request-response-data-mappings.md#request-response-data-mappings-example-1).
Como outro exemplo, você também pode mapear o parâmetro do cabeçalho de resposta da integração `kittens` para o parâmetro do cabeçalho de resposta do método `CatsAge0`. Então, se o endpoint de integração retornar `kittens:false`, o cliente receberá o cabeçalho `CatsAge0:false`. O diagrama a seguir mostra o ciclo de vida da solicitação nesse exemplo.
![\[Diagrama de exemplo de mapeamento de parâmetros do API Gateway para uma resposta\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/parameter-mapping-example2.png)
**Topics**
+ [Exemplos de mapeamento de parâmetros para APIs REST no API Gateway](request-response-data-mappings.md)
+ [Referência da origem do mapeamento de parâmetros para APIs REST no API Gateway](rest-api-parameter-mapping-sources.md)
# Exemplos de mapeamento de parâmetros para APIs REST no API Gateway
Os exemplos a seguir mostram como criar expressões de mapeamento de parâmetros usando o console do API Gateway, a OpenAPI e modelos do CloudFormation. Consulte um exemplo de como usar o mapeamento de parâmetros para criar os cabeçalhos CORS necessários em [CORS para APIs REST no API Gateway](how-to-cors.md).
## Exemplo 1: mapear um parâmetro de solicitação de método para um parâmetro de solicitação de integração
O exemplo a seguir mapeia o parâmetro do cabeçalho da solicitação do método `puppies` para o parâmetro do cabeçalho da solicitação de integração `DogsAge0`.
------
#### [ Console de gerenciamento da AWS ]
**Como mapear o parâmetro de solicitação do método**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API REST.
1. Escolha um método.
O método deve ter uma integração sem proxy.
1. Em **Configurações de solicitação de método**, selecione **Editar**.
1. Escolha **Cabeçalhos de solicitação HTTP**.
1. Escolha **Add header** (Adicionar cabeçalho).
1. Em **Nome**, digite **puppies**.
1. Escolha **Salvar**.
1. Selecione a guia **Solicitação de integração** e, em **Configurações de solicitação de integração**, selecione **Editar**.
O Console de gerenciamento da AWS adiciona automaticamente um mapeamento de parâmetros de `method.request.header.puppies ` para `puppies` para você, mas é necessário alterar o **Nome** para corresponder ao parâmetro do cabeçalho da solicitação que é esperado pelo endpoint de integração.
1. Em **Nome**, digite **DogsAge0**.
1. Escolha **Salvar**.
1. Implante a API novamente para que as alterações entrem em vigor.
As etapas a seguir mostram como verificar se o mapeamento de parâmetros foi bem-sucedido.
**(Opcional) Testar o mapeamento de parâmetros**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Para os cabeçalhos, insira **puppies:true**.
1. Escolha **Testar**.
1. Em **Logs**, o resultado deve ser algo semelhante a:
```
Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true}
Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations:
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets
Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344}
```
O parâmetro do cabeçalho da solicitação foi alterado de `puppies` para `DogsAge0`.
------
#### [ 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: ParameterMappingExample
version: "2025-02-04T00:30:41Z"
paths:
/pets:
get:
parameters:
- name: puppies
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.DogsAge0: method.request.header.puppies
passthroughBehavior: when_no_match
type: http
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 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "ParameterMappingExample",
"version" : "2025-02-04T00:30:41Z"
},
"paths" : {
"/pets" : {
"get" : {
"parameters" : [ {
"name" : "puppies",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.DogsAge0" : "method.request.header.puppies"
},
"passthroughBehavior" : "when_no_match",
"type" : "http"
}
}
}
}
}
```
------
## Exemplo 2: mapear vários parâmetros de solicitação de método para diferentes parâmetros de solicitação de integração
O exemplo a seguir mapeia o parâmetro de string de consulta de vários valores da solicitação do método `methodRequestQueryParam` para o parâmetro de string de consulta da solicitação de integração `integrationQueryParam` e mapeia o parâmetro de cabeçalho da solicitação do método `methodRequestHeaderParam` para o parâmetro de caminho da solicitação de integração `integrationPathParam`.
------
#### [ Console de gerenciamento da AWS ]
**Como mapear os parâmetros da solicitação de método**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API REST.
1. Escolha um método.
O método deve ter uma integração sem proxy.
1. Em **Configurações de solicitação de método**, selecione **Editar**.
1. Selecione **Parâmetros de string de consulta de URL**.
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, digite **methodRequestQueryParam**.
1. Escolha **Cabeçalhos de solicitação HTTP**.
1. Escolha **Add header** (Adicionar cabeçalho).
1. Em **Nome**, digite **methodRequestHeaderParam**.
1. Escolha **Salvar**.
1. Selecione a guia **Solicitação de integração** e, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de caminho de URL**.
1. Selecione **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **integrationPathParam**.
1. Em **Mapeado de**, insira **method.request.header.methodRequestHeaderParam**.
Isso mapeia o cabeçalho da solicitação de método que você especificou na solicitação de método para um novo parâmetro de caminho de solicitação de integração.
1. Selecione **Parâmetros de string de consulta de URL**.
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, digite **integrationQueryParam**.
1. Em **Mapeado de**, insira **method.request.multivaluequerystring.methodRequestQueryParam**.
Isso mapeia o parâmetro da string de consulta de vários valores para um novo parâmetro de string de consulta de solicitação de integração de valor único.
1. Escolha **Salvar**.
1. Implante a API novamente para que as alterações entrem em vigor.
------
#### [ 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.
A definição da OpenAPI a seguir cria os seguintes mapeamentos de parâmetros para uma integração HTTP:
+ O cabeçalho da solicitação de método, chamado `methodRequestHeaderParam`, no parâmetro do caminho de solicitação de integração, chamado `integrationPathParam`
+ A string de consulta da solicitação de método de vários valores, chamada `methodRequestQueryParam`, na string de consulta da solicitação de integração, chamada `integrationQueryParam`
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Body:
openapi: 3.0.1
info:
title: Parameter mapping example 2
version: "2025-01-15T19:12:31Z"
paths:
/:
post:
parameters:
- name: methodRequestQueryParam
in: query
schema:
type: string
- name: methodRequestHeaderParam
in: header
schema:
type: string
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam
integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 da OpenAPI a seguir cria os seguintes mapeamentos de parâmetros para uma integração HTTP:
+ O cabeçalho da solicitação de método, chamado `methodRequestHeaderParam`, no parâmetro do caminho de solicitação de integração, chamado `integrationPathParam`
+ A string de consulta da solicitação de método de vários valores, chamada `methodRequestQueryParam`, na string de consulta da solicitação de integração, chamada `integrationQueryParam`
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 2",
"version" : "2025-01-15T19:12:31Z"
},
"paths" : {
"/" : {
"post" : {
"parameters" : [ {
"name" : "methodRequestQueryParam",
"in" : "query",
"schema" : {
"type" : "string"
}
}, {
"name" : "methodRequestHeaderParam",
"in" : "header",
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam",
"integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemplo 3: mapear campos do corpo da solicitação JSON para os parâmetros da solicitação de integração
Também é possível mapear parâmetros da solicitação de integração com base em campos no corpo da solicitação JSON usando uma [expressão JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). O exemplo a seguir mapeia o corpo da solicitação de método para um cabeçalho da solicitação de integração chamado `body-header` e mapeia parte do corpo da solicitação, conforme expresso por uma expressão JSON, para um cabeçalho da solicitação de integração chamado `pet-price`.
Para testar esse exemplo, forneça uma entrada que contenha uma categoria de preço, como a seguinte:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
}
]
```
------
#### [ Console de gerenciamento da AWS ]
**Como mapear os parâmetros da solicitação de método**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API REST.
1. Escolha um método `POST`, `PUT`, `PATCH` ou `ANY`.
O método deve ter uma integração sem proxy.
1. Em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de cabeçalhos de solicitações de URL**.
1. Selecione **Adicionar parâmetro de cabeçalho de solicitação**.
1. Em **Nome**, digite **body-header**.
1. Em **Mapeado de**, insira **method.request.body**.
Isso mapeia o corpo da solicitação de método para um novo parâmetro de cabeçalho de solicitação de integração.
1. Selecione **Adicionar parâmetro de cabeçalho de solicitação**.
1. Em **Nome**, digite **pet-price**.
1. Em **Mapeado de**, insira ** method.request.body[0].price**.
Isso mapeia uma parte do corpo da solicitação do método para um novo parâmetro de cabeçalho da solicitação de integração.
1. Escolha **Salvar**.
1. Implante a API novamente para que as alterações entrem em vigor.
------
#### [ 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: Parameter mapping example 3
version: "2025-01-15T19:19:14Z"
paths:
/:
post:
responses:
"200":
description: 200 response
x-amazon-apigateway-integration:
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
requestParameters:
integration.request.header.pet-price: method.request.body[0].price
integration.request.header.body-header: method.request.body
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
type: http
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 mapeia parâmetros de solicitação de integração com base nos campos no corpo da solicitação JSON.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example 3",
"version" : "2025-01-15T19:19:14Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response"
}
},
"x-amazon-apigateway-integration" : {
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.header.pet-price" : "method.request.body[0].price",
"integration.request.header.body-header" : "method.request.body"
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000,
"type" : "http"
}
}
}
}
}
```
------
## Exemplo 4: mapear a resposta de integração para a resposta do método
Também é possível mapear a resposta de integração para a resposta do método. O exemplo a seguir mapeia o corpo da resposta de integração para um cabeçalho de resposta de método chamado `location`, mapeia o cabeçalho de resposta de integração `x-app-id` para o cabeçalho de resposta de método `id` e mapeia o cabeçalho de resposta de integração de vários valores `item` para o cabeçalho de resposta do método `items`.
------
#### [ Console de gerenciamento da AWS ]
**Como mapear a 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. Escolha uma API REST.
1. Escolha um método.
O método deve ter uma integração sem proxy.
1. Escolha a guia **Resposta do método** e, em **Resposta 200**, selecione **Editar**.
1. Em **Nome do cabeçalho**, escolha **Adicionar cabeçalho**.
1. Crie três cabeçalhos chamados **id**, **item** e **location**.
1. Escolha **Salvar**.
1. Escolha a guia **Resposta de integração** e em **Padrão: resposta**, selecione **Editar**.
1. Em **Mapeamentos de cabeçalho**, insira o indicado a seguir.
1. Em **id**, insira **integration.response.header.x-app-id**.
1. Em **item**, insira **integration.response.multivalueheader.item**
1. Em **local**, insira **integration.response.body.redirect.url**.
1. Escolha **Salvar**.
1. Implante a API novamente para que as alterações entrem em vigor.
------
#### [ 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: Parameter mapping example
version: "2025-01-15T19:21:35Z"
paths:
/:
post:
responses:
"200":
description: 200 response
headers:
item:
schema:
type: string
location:
schema:
type: string
id:
schema:
type: string
x-amazon-apigateway-integration:
type: http
httpMethod: GET
uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets
responses:
default:
statusCode: "200"
responseParameters:
method.response.header.id: integration.response.header.x-app-id
method.response.header.location: integration.response.body.redirect.url
method.response.header.item: integration.response.multivalueheader.item
requestTemplates:
application/json: '{"statusCode": 200}'
passthroughBehavior: when_no_templates
timeoutInMillis: 29000
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 mapeia a resposta de integração para a resposta do método.
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Parameter mapping example",
"version" : "2025-01-15T19:21:35Z"
},
"paths" : {
"/" : {
"post" : {
"responses" : {
"200" : {
"description" : "200 response",
"headers" : {
"item" : {
"schema" : {
"type" : "string"
}
},
"location" : {
"schema" : {
"type" : "string"
}
},
"id" : {
"schema" : {
"type" : "string"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.id" : "integration.response.header.x-app-id",
"method.response.header.location" : "integration.response.body.redirect.url",
"method.response.header.item" : "integration.response.multivalueheader.item"
}
}
},
"requestTemplates" : {
"application/json" : "{\"statusCode\": 200}"
},
"passthroughBehavior" : "when_no_templates",
"timeoutInMillis" : 29000
}
}
}
}
}
```
------
# Referência da origem do mapeamento de parâmetros para APIs REST no API Gateway
Ao criar um mapeamento de parâmetros, especifique os parâmetros de solicitação de método ou resposta de integração a serem modificados e especifique como modificar esses parâmetros.
A tabela a seguir mostra os parâmetros de solicitação de método que você pode mapear e a expressão para criar o mapeamento. Nessas expressões, *nome* é o nome de um parâmetro de solicitação de método. Por exemplo, para mapear o parâmetro do cabeçalho da solicitação `puppies`, use a expressão `method.request.header.puppies`. A expressão deve corresponder à expressão regular `'^[a-zA-Z0-9._$-]+$]'`. É possível usar o mapeamento de parâmetros em sua solicitação de integração para integrações de proxy e não proxy.
| **Fonte de dados mapeada** | **Expressão de mapeamento** |
| --- | --- |
| Caminho de solicitação de método | method.request.path.name |
| String de consulta da solicitação de método | method.request.querystring.name |
| String de consulta de solicitação do método de vários valores | method.request.multivaluequerystring.name |
| Cabeçalho da solicitação de método | method.request.header.name |
| Cabeçalho de solicitação de método de vários valores | method.request.multivalueheader.name |
| Corpo de solicitação de método | method.request.body |
| Corpo de solicitação de método (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION* é uma expressão JSONPath para um campo JSON do corpo de uma solicitação. Consulte mais informações em [Expressão JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variáveis de estágio | stageVariables.name |
| Variáveis de contexto | `context.name` O nome deve ser uma das [variáveis de contexto compatíveis](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valor estático | `'static_value'`. *static\$1value* é um literal de string e deve estar entre aspas simples. Por exemplo, `'https://www.example.com'`. |
A tabela a seguir mostra os parâmetros da resposta de integração que você pode mapear e a expressão para criar o mapeamento. Nessas expressões, *nome* é o nome de um parâmetro de resposta de integração. É possível mapear cabeçalhos de resposta do método por meio de qualquer cabeçalho de resposta de integração ou corpo de resposta de integração, variáveis \$1context ou valores estáticos. Para usar o mapeamento de parâmetros para uma resposta de integração, você precisa de uma integração não proxy.
| Fonte de dados mapeada | Expressão de mapeamento |
| --- | --- |
| Cabeçalho da resposta de integração | integration.response.header.name |
| Cabeçalho da resposta de integração | integration.response.multivalueheader.name |
| Corpo da resposta de integração | integration.response.body |
| Corpo da resposta de integração (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION* é uma expressão JSONPath para um campo JSON do corpo de uma resposta. Consulte mais informações em [Expressão JSONPath](http://goessner.net/articles/JsonPath/index.html#e2). |
| Variável de estágio | stageVariables.name |
| Variável de contexto | `context.name` O nome deve ser uma das [variáveis de contexto compatíveis](api-gateway-mapping-template-reference.md#context-variable-reference). |
| Valor estático | ` 'static_value'` *static\$1value* é um literal de string e deve estar entre aspas simples. Por exemplo, `'https://www.example.com'`. |
# Transformações de modelo de mapeamento para APIs REST no API Gateway
Uma transformação de modelo de mapeamento usa um modelo de mapeamento para modificar a solicitação ou a resposta de integração. *Modelo de mapeamento* é um script expresso em [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e é aplicado a uma carga útil usando o [JSONPath](https://goessner.net/articles/JsonPath/) baseado no cabeçalho `Content-type`. Você utiliza modelos de mapeamento ao usar transformações de modelos de mapeamento. Esta seção descreve informações conceituais relacionadas aos modelos de mapeamento.
O diagrama a seguir mostra o ciclo de vida da solicitação para um recurso `POST /pets` que tem uma integração com um endpoint de integração da PetStore. Nessa API, um usuário envia dados sobre um animal de estimação e o endpoint de integração retorna a taxa de adoção associada a um animal de estimação. Nesse ciclo de vida da solicitação, as transformações do modelo de mapeamento filtram o corpo da solicitação para o endpoint de integração e filtram o corpo da resposta do endpoint de integração.
![\[Exemplo de ciclo de vida da solicitação\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/mapping-template-transforms.png)
As seções a seguir explicam o ciclo de vida da solicitação e da resposta.
## Solicitação de método e solicitação de integração
No exemplo anterior, se este for o corpo da solicitação enviado para a solicitação do método:
```
POST /pets
HTTP/1.1
Host:abcd1234.us-west-2.amazonaws.com
Content-type: application/json
{
"id": 1,
"type": "dog",
"Age": 11,
}
```
Esse corpo da solicitação não está no formato correto para ser usado pelo endpoint de integração, então o API Gateway executa uma transformação do modelo de mapeamento. O API Gateway só executa uma transformação do modelo de mapeamento porque há um modelo de mapeamento definido para `application/json` de Content-Type. Se você não definir um modelo de mapeamento para Content-Type, por padrão, o API Gateway passará o corpo por meio da solicitação de integração ao endpoint de integração. Para modificar esse comportamento, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md).
O modelo de mapeamento a seguir transforma os dados da solicitação de método na solicitação de integração antes de serem enviados ao endpoint de integração:
```
#set($inputRoot = $input.path('$'))
{
"dogId" : "dog_"$elem.id,
"Age": $inputRoot.Age
}
```
1. A variável `$inputRoot` representa o objeto raiz nos dados JSON originais da seção anterior. As diretivas começam com o símbolo `#`.
1. `dog` é uma concatenação do `id` do usuário e de um valor de string.
1. `Age` é do corpo da solicitação do método.
Então, a saída a seguir é encaminhada ao endpoint de integração:
```
{
"dogId" : "dog_1",
"Age": 11
}
```
## Resposta de integração e resposta do método
Após a solicitação bem-sucedida ao endpoint de integração, o endpoint envia uma resposta à resposta de integração do API Gateway. Veja a seguir exemplos de dados de saída do endpoint de integração:
```
{
"dogId" : "dog_1",
"adoptionFee": 19.95,
}
```
A resposta do método espera uma carga útil diferente da retornada pela resposta de integração. O API Gateway executa uma transformação do modelo de mapeamento. O API Gateway só executa uma transformação do modelo de mapeamento porque há um modelo de mapeamento definido para `application/json` de Content-Type. Se você não definir um modelo de mapeamento para Content-Type, por padrão, o API Gateway passará o corpo por meio da resposta de integração para a resposta do método. Para modificar esse comportamento, consulte [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md).
```
#set($inputRoot = $input.path('$'))
{
"adoptionFee" : $inputRoot.adoptionFee,
}
```
Veja a seguir a saída enviada à resposta do método:
```
{"adoptionFee": 19.95}
```
Isso conclui o exemplo de transformação do modelo de mapeamento. Recomendamos que, quando possível, em vez de usar transformações de modelo de mapeamento, você use uma integração com proxy para transformar dados. Para obter mais informações, consulte [Escolher um tipo de integração de API do API Gateway](api-gateway-api-integration-types.md).
# Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway
Se a solicitação de método tiver uma carga útil e você não tiver um modelo de mapeamento definido para o cabeçalho `Content-Type`, poderá optar por passar a carga útil da solicitação fornecida pelo cliente por meio da solicitação de integração ao backend sem transformação. O processo é conhecido como passagem direta de integração.
O comportamento real de passagem de uma solicitação recebida é determinado por essa configuração. Existem três opções:
**Quando nenhum modelo corresponder ao cabeçalho Content-Type da solicitação**
Escolha essa opção se desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando o tipo de conteúdo da solicitação de método não corresponder a nenhum dos tipos de conteúdo associados aos modelos de mapeamento.
Ao chamar a API do API Gateway, escolha essa opção definindo `WHEN_NO_MATCH` como o valor da propriedade `passthroughBehavior` na [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Quando não há modelos definidos (recomendado)**
Escolha essa opção se desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando nenhum modelo de mapeamento estiver definido na solicitação de integração. Se um modelo for definido quando essa opção for selecionada, a solicitação de método de um tipo de conteúdo e carga útil que não corresponda a nenhum modelo de mapeamento definido será rejeitada com uma resposta HTTP 415 Tipo de mídia incompatível.
Ao chamar a API do API Gateway, escolha essa opção definindo `WHEN_NO_TEMPLATES` como o valor da propriedade `passthroughBehavior` na [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
**Nunca**
Escolha essa opção se não desejar que o corpo da solicitação de método passe a solicitação de integração para o back-end sem transformação quando nenhum modelo de mapeamento estiver definido na solicitação de integração. Se um modelo for definido quando essa opção for selecionada, a solicitação de método de um tipo de conteúdo não mapeado será rejeitada com uma resposta HTTP 415 Tipo de mídia sem suporte.
Ao chamar a API do API Gateway, escolha essa opção definindo `NEVER` como o valor da propriedade `passthroughBehavior` na [Integração](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html).
Os exemplos a seguir mostram os possíveis comportamentos de passagem.
Exemplo 1: um modelo de mapeamento é definido na solicitação de integração para o tipo de conteúdo `application/json`.
| Content-type | Opção de passagem | Comportamento |
| --- | --- | --- |
| Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1MATCH | A carga da solicitação é transformada usando o modelo. |
| Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1TEMPLATES | A carga da solicitação é transformada usando o modelo. |
| Nenhum O padrão do API Gateway é `application/json` | NEVER | A carga da solicitação é transformada usando o modelo. |
| application/json | WHEN\$1NO\$1MATCH | A carga da solicitação é transformada usando o modelo. |
| application/json | WHEN\$1NO\$1TEMPLATES | A carga da solicitação é transformada usando o modelo. |
| application/json | NEVER | A carga da solicitação é transformada usando o modelo. |
| application/xml | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| application/xml | WHEN\$1NO\$1TEMPLATES | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| application/xml | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
Exemplo 2: um modelo de mapeamento é definido na solicitação de integração para o tipo de conteúdo `application/xml`.
| Content-type | Opção de passagem | Comportamento |
| --- | --- | --- |
| Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1TEMPLATES | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| Nenhum O padrão do API Gateway é `application/json` | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| application/json | WHEN\$1NO\$1TEMPLATES | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| application/json | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | A carga da solicitação é transformada usando o modelo. |
| application/xml | WHEN\$1NO\$1TEMPLATES | A carga da solicitação é transformada usando o modelo. |
| application/xml | NEVER | A carga da solicitação é transformada usando o modelo. |
Exemplo 3: nenhum modelo de mapeamento está definido na solicitação de integração.
| Content-type | Opção de passagem | Comportamento |
| --- | --- | --- |
| Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| Nenhum O padrão do API Gateway é `application/json` | WHEN\$1NO\$1TEMPLATES | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| Nenhum O padrão do API Gateway é `application/json` | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| application/json | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| application/json | WHEN\$1NO\$1TEMPLATES | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| application/json | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
| application/xml | WHEN\$1NO\$1MATCH | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| application/xml | WHEN\$1NO\$1TEMPLATES | A carga da solicitação não é transformada e é enviada ao backend no estado em que se encontra. |
| application/xml | NEVER | A solicitação é rejeitada com uma resposta HTTP 415 Unsupported Media Type. |
# Exemplo adicional de modelo de mapeamento para APIs REST no API Gateway
O exemplo a seguir mostra uma API de álbum de fotos no API Gateway que usa modelos de mapeamento para transformar dados de solicitação e de resposta de integração. Ele também usa modelos de dados para definir cargas úteis de solicitação de método e resposta de integração. Para saber mais sobre modelos de dados, consulte [Modelos de dados para APIs REST](models-mappings-models.md).
## Solicitação de método e solicitação de integração
Veja a seguir um modelo que define o corpo da solicitação do método. Esse modelo de entrada exige que o chamador faça upload de uma página de foto requer no mínimo 10 fotos por página. É possível usar esse modelo de entrada para gerar um SDK ou para usar uma validação de solicitação para a API. Ao usar a validação de solicitação, se o corpo da solicitação do método não aderir à estrutura de dados do modelo, o API Gateway falhará na solicitação.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosInputModel",
"type": "object",
"properties": {
"photos": {
"type": "object",
"required" : [
"photo"
],
"properties": {
"page": { "type": "integer" },
"pages": { "type": "string" },
"perpage": { "type": "integer", "minimum" : 10 },
"total": { "type": "string" },
"photo": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"owner": { "type": "string" },
"photographer_first_name" : {"type" : "string"},
"photographer_last_name" : {"type" : "string"},
"secret": { "type": "string" },
"server": { "type": "string" },
"farm": { "type": "integer" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
}
}
```
Veja a seguir um exemplo de corpo de solicitação de método que adere à estrutura de dados do modelo de dados anterior.
```
{
"photos": {
"page": 1,
"pages": "1234",
"perpage": 100,
"total": "123398",
"photo": [
{
"id": "12345678901",
"owner": "23456789@A12",
"photographer_first_name" : "Saanvi",
"photographer_last_name" : "Sarkar",
"secret": "abc123d456",
"server": "1234",
"farm": 1,
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"owner": "34567890@B23",
"photographer_first_name" : "Richard",
"photographer_last_name" : "Roe",
"secret": "bcd234e567",
"server": "2345",
"farm": 2,
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
}
```
Nesse exemplo, se o corpo da solicitação do método anterior foi enviado pelo cliente, esse modelo de mapeamento transforma a carga útil para corresponder ao formato exigido pelo endpoint de integração.
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.ispublic,
"isfriend": $elem.isfriend,
"isfamily": $elem.isfamily
}#if($foreach.hasNext),#end
#end
]
}
```
Veja no exemplo a seguir os dados de saída da transformação.
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Esses dados são enviados para a solicitação de integração e, depois, ao endpoint de integração.
## Resposta de integração e resposta do método
Veja a seguir um exemplo de modelo de saída para dados de fotos do endpoint de integração. Você pode usar esse modelo como um modelo de resposta de método, que é necessário quando você gera um SDK fortemente tipado para a API. Isso faz com que a saída seja convertida em uma classe adequada em Java ou Objective-C.
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PhotosOutputModel",
"type": "object",
"properties": {
"photos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"photographedBy": { "type": "string" },
"title": { "type": "string" },
"ispublic": { "type": "boolean" },
"isfriend": { "type": "boolean" },
"isfamily": { "type": "boolean" }
}
}
}
}
}
```
O endpoint de integração pode não responder com uma resposta que faça adesão da estrutura de dados desse modelo. A resposta de integração pode parecer com o seguinte:
```
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"description": "My sample photo 1",
"public": true,
"friend": false,
"family": false
}
]
}
```
O exemplo de modelo de mapeamento a seguir transforma os dados de resposta de integração no formato esperado pela resposta do método:
```
#set($inputRoot = $input.path('$'))
{
"photos": [
#foreach($elem in $inputRoot.photos.photo)
{
"id": "$elem.id",
"photographedBy": "$elem.photographer_first_name $elem.photographer_last_name",
"title": "$elem.title",
"ispublic": $elem.public,
"isfriend": $elem.friend,
"isfamily": $elem.family
}#if($foreach.hasNext),#end
#end
]
}
```
Veja no exemplo a seguir os dados de saída da transformação.
```
{
"photos": [
{
"id": "12345678901",
"photographedBy": "Saanvi Sarkar",
"title": "Sample photo 1",
"ispublic": true,
"isfriend": false,
"isfamily": false
},
{
"id": "23456789012",
"photographedBy": "Richard Roe",
"title": "Sample photo 2",
"ispublic": true,
"isfriend": false,
"isfamily": false
}
]
}
```
Esses dados são enviados para a resposta do método e, depois, de volta ao cliente.
# 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).
# Tutorial: modificar a solicitação e a resposta de integração para integrações a serviços da AWS
O tutorial a seguir mostra como usar transformações de modelos de mapeamento para configurar modelos de mapeamento a fim de transformar solicitações e respostas de integração usando o console e a AWS CLI.
**Topics**
+ [Configurar transformações de dados no console do API Gateway](#mapping-example-console)
+ [Configurar a transformação de dados usando a CLI da AWS](#mapping-example-cli)
+ [Modelo CloudFormation de transformação de dados concluído](#api-gateway-data-transformations-full-cfn-stack)
## Configurar transformações de dados no console do API Gateway
Neste tutorial, você criará uma API incompleta e uma tabela do DynamoDB usando o seguinte arquivo .zip [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-console.zip). Essa API incompleta tem um recurso `/pets` com os métodos `GET` e `POST`.
+ O método `GET` obterá dados do endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Os dados de saída serão transformados de acordo com o modelo de mapeamento em [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md).
+ O método `POST` possibilitará que o usuário `POST` informações sobre animais de estimação em uma tabela do Amazon DynamoDB usando um modelo de mapeamento.
Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/data-transformation-tutorial-console.zip). Você usará esse modelo para criar uma tabela do DynamoDB para publicar informações sobre animais de estimação e uma API incompleta. Você concluirá o restante das etapas no console do API Gateway.
**Como criar uma pilha do CloudFormation**
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Selecione **Create stack (Criar pilha)** e **With new resources (standard) (Com novos recursos (padrão))**.
1. Em **Specify template (Especificar modelo)**, escolha **Upload a template file (Fazer upload de um arquivo de modelo)**.
1. Selecione o modelo que você baixou.
1. Escolha **Next (Próximo)**.
1. Em **Nome da pilha**, insira **data-transformation-tutorial-console** e escolha **Avançar**.
1. Para **Configurar opções de pilha**, escolha **Avançar**.
1. Para **Capabilities** (Recursos), reconheça que CloudFormation pode criar recursos do IAM em sua conta.
1. Escolha **Próximo** e, depois, **Enviar**.
CloudFormationO fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, você estará pronto para passar para a próxima etapa.
**Como testar a resposta de integração `GET`**
1. Na guia **Recursos** da pilha de CloudFormation para **data-transformation-tutorial-console**, selecione o ID físico de sua API.
1. No painel de navegação, selecione **Recursos** e, depois, selecione o método **GET**.
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
A saída do teste mostrará o seguinte:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Você transformará esse resultado de acordo com o modelo de mapeamento em [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md).
**Como transformar a resposta de integração `GET`**
1. Selecione a guia **Resposta de integração**.
Atualmente, não há modelos de mapeamento definidos, portanto, a resposta de integração não será transformada.
1. Em **Padrão - Resposta**, selecione **Editar**.
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($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
{
"description" : "Item $elem.id is a $elem.type.",
"askingPrice" : $elem.price
}#if($foreach.hasNext),#end
#end
]
```
Escolha **Salvar**.
**Como testar a resposta de integração `GET`**
+ Selecione a guia **Testar** e, depois, **Testar**.
A saída do teste mostrará a resposta transformada.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Como transformar dados de entrada do método `POST`**
1. Selecione o método **POST**.
1. Selecione a guia **Solicitação de integração** e, em **Configurações de solicitação de integração**, selecione **Editar**.
O modelo CloudFormation preencheu alguns dos campos da solicitação de integração.
+ O tipo de integração é AWS service (Serviço da AWS).
+ O AWS service (Serviço da AWS) é o DynamoDB.
+ O método HTTP é o `POST`.
+ A ação é `PutItem`.
+ O perfil de execução que possibilita que o API Gateway coloque um item na tabela do DynamoDB é `data-transformation-tutorial-console-APIGatewayRole`. O CloudFormation criou esse perfil para possibilitar que o API Gateway tenha as permissões mínimas para interagir com o DynamoDB.
O nome da tabela do DynamoDB não foi especificado. Você especificará o nome nas etapas a seguir.
1. Em **Passagem do corpo da solicitação**, selecione **Nunca**.
Isso significa que a API rejeitará dados com tipos de conteúdo que não tenham um modelo de mapeamento.
1. Selecione **Modelos de mapeamento**.
1. O **Tipo de conteúdo** é definido como `application/json`. Isso significa que tipos de conteúdo que não sejam application/json serão rejeitados pela API. Para obter mais informações sobre os comportamentos de passagem direta de integração, consulte . [Comportamento de solicitação de método para cargas úteis sem modelos de mapeamento para APIs REST no API Gateway](integration-passthrough-behaviors.md)
1. Insira o código a seguir no editor de texto.
```
{
"TableName":"data-transformation-tutorial-console-ddb",
"Item": {
"id": {
"N": $input.json("$.id")
},
"type": {
"S": $input.json("$.type")
},
"price": {
"N": $input.json("$.price")
}
}
}
```
Esse modelo especifica a tabela como `data-transformation-tutorial-console-ddb` e define os itens como `id`, `type` e `price`. Os itens virão do corpo do método `POST`. Você também pode usar um modelo de dados para ajudar a criar um modelo de mapeamento. Para obter mais informações, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md).
1. Escolha **Salvar** para salvar seu modelo de mapeamento.
**Como adicionar um método e uma resposta de integração do método `POST`**
O CloudFormation criou um método em branco e uma resposta de integração. Você editará essa resposta para fornecer mais informações. Para ter mais informações sobre como editar respostas, consulte [Exemplos de mapeamento de parâmetros para APIs REST no API Gateway](request-response-data-mappings.md).
1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**.
1. Selecione **Modelos de mapeamento** e, depois, **Adicionar modelo de mapeamento**.
1. Em **Tipo de conteúdo**, insira **application/json**.
1. No editor de código, insira o seguinte modelo de mapeamento de saída para enviar uma mensagem de saída:
```
{ "message" : "Your response was recorded at $context.requestTime" }
```
Para ter mais informações sobre variáveis de contexto, consulte [Variáveis de contexto para transformações de dados](api-gateway-mapping-template-reference.md#context-variable-reference).
1. Escolha **Salvar** para salvar seu modelo de mapeamento.
**Testar o método `POST`**
Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. No corpo da solicitação, insira o exemplo a seguir.
```
{
"id": "4",
"type" : "dog",
"price": "321"
}
```
1. Escolha **Testar**.
A saída deve mostrar sua mensagem de êxito.
Você pode abrir o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/) para verificar se o item de exemplo está na sua tabela.
**Para excluir uma pilha do CloudFormation**
1. Abra o console do CloudFormation em [https://console.aws.amazon.com/cloudformation](https://console.aws.amazon.com/cloudformation/).
1. Selecione sua pilha do CloudFormation.
1. Escolha **Excluir** e, em seguida, confirme sua escolha.
## Configurar a transformação de dados usando a CLI da AWS
Neste tutorial, você criará uma API incompleta e uma tabela do DynamoDB usando o arquivo .zip [data-transformation-tutorial-console.zip](samples/data-transformation-tutorial-cli.zip) a seguir. Essa API incompleta tem um recurso `/pets` com um método `GET` integrado ao endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Você criará um método `POST` para se conectar a uma tabela do DynamoDB e usará modelos de mapeamento para inserir dados em uma tabela do DynamoDB.
+ Você transformará os dados de saída de acordo com o modelo de mapeamento em [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md).
+ Você criará um método `POST` para possibilitar que o usuário `POST` informações sobre animais de estimação em uma tabela do Amazon DynamoDB usando um modelo de mapeamento.
**Como criar uma pilha do CloudFormation**
Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/data-transformation-tutorial-cli.zip).
Para concluir o tutorial a seguir, é necessária a [AWS Command Line Interface (AWS CLI) versão 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
Para comandos longos, um caractere de escape (`\`) é usado para dividir um comando em várias linhas.
**nota**
No Windows, alguns comandos da CLI do Bash que você costuma usar (como `zip`) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, [instale o Subsistema do Windows para Linux](https://learn.microsoft.com/en-us/windows/wsl/install). Os exemplos de comandos da CLI neste guia usam a formatação Linux. Os comandos que incluem documentos JSON em linha deverão ser reformatados se você estiver usando a CLI do Windows.
1. Use o comando a seguir para criar a pilha de CloudFormation.
```
aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
```
1. CloudFormationO fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Use o comando a seguir para ver o status de sua pilha de CloudFormation.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli
```
1. Quando o status da sua pilha de CloudFormation for `StackStatus: "CREATE_COMPLETE"`, use o comando a seguir para recuperar valores de saída relevantes para etapas futuras.
```
aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"
```
Os valores de saída são os seguintes:
+ ApiRole, que é o nome do perfil que possibilita que o API Gateway coloque itens na tabela do DynamoDB. Para este tutorial, o nome do perfil é `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`.
+ DDBTableName, que é o nome da tabela do DynamoDB. Para este tutorial, o nome da tabela é `data-transformation-tutorial-cli-ddb`.
+ ResourceId, que é o ID do recurso de animais de estimação em que os métodos `GET` e `POST` são expostos. Para este tutorial, o ID do recurso é `efg456`.
+ ApiId, que é o ID da API. Para este tutorial, o ID da API é `abc123`.
**Como testar o método `GET` antes da transformação de dados**
+ Use o comando a seguir para testar o método `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET
```
A saída do teste mostrará o seguinte:
```
[
{
"id": 1,
"type": "dog",
"price": 249.99
},
{
"id": 2,
"type": "cat",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Você transformará esse resultado de acordo com o modelo de mapeamento em [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md).
**Como transformar a resposta de integração `GET`**
+ Use o comando a seguir para atualizar a resposta de integração do método `GET`. Substitua o *rest-api-id* e o *resource-id* pelos seus valores.
Use o comando a seguir para criar uma resposta de integração.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}'
```
**Como testar o método `GET`**
+ Use o comando a seguir para testar o método `GET`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method GET \
```
A saída do teste mostrará a resposta transformada.
```
[
{
"description" : "Item 1 is a dog.",
"askingPrice" : 249.99
},
{
"description" : "Item 2 is a cat.",
"askingPrice" : 124.99
},
{
"description" : "Item 3 is a fish.",
"askingPrice" : 0.99
}
]
```
**Como criar um método `POST`**
1. Use o comando a seguir para criar um novo método no recurso `/pets`.
```
aws apigateway put-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--authorization-type "NONE" \
```
Esse método possibilitará que você envie informações sobre animais de estimação para a tabela do DynamoDB que você criou na pilha de CloudFormation.
1. Use o comando a seguir para criar uma integração do AWS service (Serviço da AWS) no método `POST`.
```
aws apigateway put-integration --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--type AWS \
--integration-http-method POST \
--uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \
--credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \
--request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}'
```
1. Use o comando a seguir para criar uma resposta de método para uma chamada bem-sucedida do método `POST`.
```
aws apigateway put-method-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200
```
1. Use o comando a seguir para criar uma resposta de integração para uma chamada bem-sucedida do método `POST`.
```
aws apigateway put-integration-response --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--status-code 200 \
--selection-pattern "" \
--response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}'
```
**Como testar o método `POST`**
+ Use o comando a seguir para testar o método `POST`.
```
aws apigateway test-invoke-method --rest-api-id abc123 \
--resource-id efg456 \
--http-method POST \
--body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}'
```
A saída mostrará a mensagem de êxito.
**Para excluir uma pilha do CloudFormation**
+ Use o comando a seguir para excluir seus recursos de CloudFormation.
```
aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli
```
## Modelo CloudFormation de transformação de dados concluído
O exemplo a seguir é um modelo de CloudFormation completo, que cria uma API e uma tabela do DynamoDB com um recurso `/pets` com os métodos `GET` e `POST`.
+ O método `GET` obterá dados do endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Os dados de saída serão transformados de acordo com o modelo de mapeamento em [Transformações de modelo de mapeamento para APIs REST no API Gateway](models-mappings.md).
+ O método `POST` possibilitará que o usuário `POST` informações sobre animais de estimação em uma tabela do DynamoDB usando um modelo de mapeamento.
### Exemplo de modelo CloudFormation
```
AWSTemplateFormatVersion: 2010-09-09
Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data.
Parameters:
StageName:
Type: String
Default: v1
Description: Name of API stage.
Resources:
DynamoDBTable:
Type: 'AWS::DynamoDB::Table'
Properties:
TableName: !Sub data-transformation-tutorial-complete
AttributeDefinitions:
- AttributeName: id
AttributeType: N
KeySchema:
- AttributeName: id
KeyType: HASH
ProvisionedThroughput:
ReadCapacityUnits: 5
WriteCapacityUnits: 5
APIGatewayRole:
Type: 'AWS::IAM::Role'
Properties:
AssumeRolePolicyDocument:
Version: 2012-10-17
Statement:
- Action:
- 'sts:AssumeRole'
Effect: Allow
Principal:
Service:
- apigateway.amazonaws.com
Policies:
- PolicyName: APIGatewayDynamoDBPolicy
PolicyDocument:
Version: 2012-10-17
Statement:
- Effect: Allow
Action:
- 'dynamodb:PutItem'
Resource: !GetAtt DynamoDBTable.Arn
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: data-transformation-complete-api
ApiKeySourceType: HEADER
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: HTTP
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
PassthroughBehavior: WHEN_NO_TEMPLATES
IntegrationResponses:
- StatusCode: '200'
ResponseTemplates:
application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"
MethodResponses:
- StatusCode: '200'
PetsMethodPost:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: POST
ApiKeyRequired: false
AuthorizationType: NONE
Integration:
Type: AWS
Credentials: !GetAtt APIGatewayRole.Arn
IntegrationHttpMethod: POST
Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem
PassthroughBehavior: NEVER
RequestTemplates:
application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"
IntegrationResponses:
- StatusCode: 200
ResponseTemplates:
application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}"
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: !Sub '${StageName}'
Outputs:
ApiId:
Description: API ID for CLI commands
Value: !Ref Api
ResourceId:
Description: /pets resource ID for CLI commands
Value: !Ref PetsResource
ApiRole:
Description: Role ID to allow API Gateway to put and scan items in DynamoDB table
Value: !Ref APIGatewayRole
DDBTableName:
Description: DynamoDB table name
Value: !Ref DynamoDBTable
```
# Exemplos de uso de variáveis para mapear transformações de modelos para o API Gateway
Os exemplos a seguir mostram como usar as variáveis `$context`, `input` e `util` em modelos de mapeamento. Você pode usar uma integração simulada ou uma integração sem proxy do Lambda que retorna o evento de entrada ao API Gateway. Consulte uma lista de variáveis compatíveis com transformadores de dados em [Variáveis para transformações de dados para o API Gateway](api-gateway-mapping-template-reference.md).
## Exemplo 1: passar várias variáveis `$context` ao endpoint de integração
O exemplo a seguir mostra um modelo de mapeamento que mapeia variáveis `$context` de entrada para variáveis de backend com nomes um pouco diferentes em 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"
}
```
A saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{
stage: 'prod',
request_id: 'abcdefg-000-000-0000-abcdefg',
api_id: 'abcd1234',
resource_path: '/',
resource_id: 'efg567',
http_method: 'GET',
source_ip: '192.0.2.1',
user-agent: 'curl/7.84.0',
account_id: '111122223333',
api_key: 'MyTestKey',
caller: 'ABCD-0000-12345',
user: 'ABCD-0000-12345',
user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}
```
Uma das variáveis é uma chave de API. Este exemplo pressupõe que o método exige a chave de API.
## Exemplo 2: passar todos os parâmetros de solicitação ao endpoint de integração por meio de uma carga útil JSON:
O exemplo a seguir passa todos os parâmetros de solicitação, incluindo os parâmetros `path`, `querystring` e `header`, ao endpoint de integração por meio de uma carga útil 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
}
}
```
Se uma solicitação tiver estes parâmetros de entrada:
+ Um parâmetro de caminho chamado `myparam`
+ Parâmetros de string de consulta `querystring1=value1,value2`
+ Cabeçalhos `"header1" : "value1"`.
A saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}}
```
## Exemplo 3: passar uma subseção de uma solicitação de método para o endpoint de integração
O exemplo a seguir usa o parâmetro de entrada `name` para recuperar somente o parâmetro `name` e o parâmetro de entrada `input.json('$')` para recuperar todo o corpo da solicitação do método:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$')
}
```
Para uma solicitação que inclua os parâmetros de string de consulta `name=Bella&type=dog` e o seguinte corpo:
```
{
"Price" : "249.99",
"Age": "6"
}
```
A saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{
"name" : "Bella",
"body" : {"Price":"249.99","Age":"6"}
}
```
Esse modelo de mapeamento remove o parâmetro da string de consulta `type=dog`.
Se a entrada JSON contiver caracteres sem escape que não podem ser analisados pelo JavaScript, o API Gateway pode retornar uma resposta 400. Aplique `$util.escapeJavaScript($input.json('$'))` para garantir que a entrada JSON possa ser analisada corretamente.
O exemplo anterior com `$util.escapeJavaScript($input.json('$'))` aplicado é o seguinte:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$'))"
}
```
Neste caso, a saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{
"name" : "Bella",
"body": {"Price":"249.99","Age":"6"}
}
```
## Exemplo 4: usar a expressão JSONPath para passar uma subseção de uma solicitação de método ao endpoint de integração
O exemplo a seguir usa expressões JSONPath para recuperar somente o parâmetro de entrada `name` e o `Age` do corpo da solicitação:
```
{
"name" : "$input.params('name')",
"body" : $input.json('$.Age')
}
```
Para uma solicitação que inclua os parâmetros de string de consulta `name=Bella&type=dog` e o seguinte corpo:
```
{
"Price" : "249.99",
"Age": "6"
}
```
A saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{
"name" : "Bella",
"body" : "6"
}
```
Esse modelo de mapeamento remove o parâmetro da string de consulta `type=dog` e o campo `Price` do corpo.
Se uma carga útil de solicitação de método contiver caracteres sem escape que não podem ser analisados por JavaScript, o API Gateway pode retornar uma resposta `400`. Aplique `$util.escapeJavaScript()` para garantir que a entrada JSON possa ser analisada corretamente.
O exemplo anterior com `$util.escapeJavaScript($input.json('$.Age'))` aplicado é o seguinte:
```
{
"name" : "$input.params('name')",
"body" : "$util.escapeJavaScript($input.json('$.Age'))"
}
```
Neste caso, a saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{
"name" : "Bella",
"body": "\"6\""
}
```
## Exemplo 5: usar uma expressão JSONPath para passar informações sobre uma solicitação de método ao endpoint de integração
O exemplo a seguir usa `$input.params()`, `$input.path()` e `$input.json()` para enviar informações sobre uma solicitação de método ao endpoint de integração. Esse modelo de mapeamento usa o método `size()` para fornecer o número de elementos em uma lista.
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : $input.json('$.things')
}
```
Para uma solicitação que inclui o parâmetro de caminho `123` e o seguinte corpo:
```
{
"things": {
"1": {},
"2": {},
"3": {}
}
}
```
A saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}
```
Se uma carga útil de solicitação de método contiver caracteres sem escape que não podem ser analisados por JavaScript, o API Gateway pode retornar uma resposta `400`. Aplique `$util.escapeJavaScript()` para garantir que a entrada JSON possa ser analisada corretamente.
O exemplo anterior com `$util.escapeJavaScript($input.json('$.things'))` aplicado é o seguinte:
```
{
"id" : "$input.params('id')",
"count" : "$input.path('$.things').size()",
"things" : "$util.escapeJavaScript($input.json('$.things'))"
}
```
A saída deste modelo de mapeamento deve ser semelhante ao seguinte:
```
{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}
```
# Variáveis para transformações de dados para o API Gateway
Ao criar um mapeamento de parâmetros, é possível usar variáveis de contexto como a fonte de dados. Ao criar transformações de modelos de mapeamento, é possível usar variáveis de utilidade, entrada e contexto em scripts que você escreve na [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Consulte exemplos de modelos de mapeamento que usam essas variáveis de referência em [Exemplos de uso de variáveis para mapear transformações de modelos para o API Gateway](api-gateway-mapping-variable-examples.md).
Consulte uma lista de variáveis de referência para registro em log de acesso em [Variáveis para registro em log de acesso no API Gateway](api-gateway-variables-for-access-logging.md).
## Variáveis de contexto para transformações de dados
É possível usar as variáveis `$context` a seguir para transformações de dados.
| Parameter | Descrição |
| --- | --- |
| \$1context.accountId | O ID da conta da AWS do proprietário da API |
| \$1context.apiId | O identificador que o API Gateway atribui à sua API. |
| \$1context.authorizer.claims.property | Uma propriedade das declarações retornadas do grupo de usuários do Amazon Cognito depois que o autor da chamada do método é autenticado com êxito. Para obter mais informações, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md). Chamar `$context.authorizer.claims` retorna um valor nulo. |
| \$1context.authorizer.principalId | A identificação do usuário principal associada ao token enviado pelo cliente e retornada a partir de um autorizador do Lambda do API Gateway (anteriormente conhecido como autorizador personalizado). Para obter mais informações, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). |
| \$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"`. Com relação à *propriedade*, o único caractere especial aceito é o sublinhado `(_)`. Para obter mais informações, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md). |
| \$1context.awsEndpointRequestId | O ID da solicitação do endpoint da AWS. |
| \$1context.deploymentId | O ID da implantação de API. |
| \$1context.domainName | O nome de domínio completo usado para invocar a API. Ele deve ser o mesmo que o cabeçalho `Host` de entrada. |
| \$1context.domainPrefix | O primeiro rótulo do `$context.domainName`. |
| \$1context.error.message | Uma string que contém uma mensagem de erro do API Gateway. Essa variável pode ser usada apenas para substituição de variável simples em um modelo de mapeamento de corpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que não é processado pelo mecanismo Velocity Template Language, bem como no registro de acesso. Para obter mais informações, consulte [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md) e [Configurar respostas do gateway para personalizar respostas de erro](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.messageString | O valor citado de \$1context.error.message, ou seja, "\$1context.error.message". |
| \$1context.error.responseType | Um [tipo](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) de [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). Essa variável pode ser usada apenas para substituição de variável simples em um modelo de mapeamento de corpo [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html), que não é processado pelo mecanismo Velocity Template Language, bem como no registro de acesso. Para obter mais informações, consulte [Monitorar a execução de APIs de WebSocket com métricas do CloudWatch](apigateway-websocket-api-logging.md) e [Configurar respostas do gateway para personalizar respostas de erro](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). |
| \$1context.error.validationErrorString | Uma string que contém uma mensagem de erro de validação detalhada. |
| \$1context.extendedRequestId | O ID estendido que o API Gateway gera e atribui à solicitação de API. O ID de solicitação estendido contém informações úteis para a depuração e solução de problemas. |
| \$1context.httpMethod | O método HTTP utilizado. Os valores válidos incluem: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. |
| \$1context.identity.accountId | O ID da conta da AWS associado à solicitação. |
| \$1context.identity.apiKey | Para os métodos de API que exigem uma chave de API, essa variável é a chave de API associada à solicitação do método. Para métodos que não exigem uma chave de API, essa variável é um valor nulo. Para obter mais informações, consulte [Usar planos e chaves de API para APIs REST no APIs Gateway](api-gateway-api-usage-plans.md). |
| \$1context.identity.apiKeyId | O ID da chave de API associada a uma solicitação de API que exige uma chave de API. |
| \$1context.identity.caller | O identificador principal da entidade do autor da chamada que assinou a solicitação. Compatível com recursos que usam a autorização do IAM. |
| \$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.principalOrgId | O [ID da organização da AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). |
| \$1context.identity.sourceIp | O endereço IP de origem da conexão TCP mais próxima que está fazendo a solicitação ao endpoint do API Gateway. |
| \$1context.identity.clientCert.clientCertPem | O certificado de cliente codificado por PEM que o cliente apresentou durante a autenticação TLS mútua. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. |
| \$1context.identity.clientCert.subjectDN | O nome distinto do assunto do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. |
| \$1context.identity.clientCert.issuerDN | O nome distinto do emissor do certificado apresentado por um cliente. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. |
| \$1context.identity.clientCert.serialNumber | O número de série do certificado. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. |
| \$1context.identity.clientCert.validity.notBefore | A data antes da qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. |
| \$1context.identity.clientCert.validity.notAfter | A data após a qual o certificado é inválido. Presente quando um cliente acessa uma API usando um nome de domínio personalizado que tenha TLS mútuo habilitado. Presente somente nos logs de acesso, se ocorrer falha na autenticação TLS mútua. |
| \$1context.identity.vpcId | O ID da VPC que está fazendo a solicitação ao endpoint do API Gateway. |
| \$1context.identity.vpceId | O ID do endpoint da VPC que está fazendo a solicitação ao endpoint do API Gateway. Presente somente quando você tem uma API privada. |
| \$1context.identity.user | O identificador principal da entidade do usuário que será autorizado contra o acesso a recursos. Compatível com recursos que usam a autorização do IAM. |
| \$1context.identity.userAgent | O cabeçalho [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) 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. Para obter mais informações, consulte [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). |
| \$1context.isCanaryRequest | Retorna `true` se a solicitação foi direcionada ao canário e `false` se a solicitação não foi direcionada ao canário. Presente somente quando você tem um canário habilitado. |
| \$1context.path | O caminho da solicitação. Por exemplo, para um URL de solicitação sem proxy de https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, o valor \$1context.path é /\$1stage\$1/root/child. |
| \$1context.protocol | O protocolo de solicitação, por exemplo, , HTTP/1.1. As APIs do API Gateway podem aceitar solicitações HTTP/2, mas o API Gateway envia solicitações para integrações de back-end usando HTTP/1.1. Como resultado, o protocolo de solicitação é registrado como HTTP/1.1 mesmo se um cliente enviar uma solicitação que usa HTTP/2. |
| \$1context.requestId | Um ID para a solicitação. Os clientes podem substituir esse ID de solicitação. Usar `$context.extendedRequestId` para um ID de solicitação exclusivo gerado pelo API Gateway. |
| \$1context.requestOverride.header.header\$1name | Substituição do cabeçalho da solicitação. Esse parâmetro, quando definido, contém os cabeçalhos a serem usados em lugar dos **HTTP Headers (Cabeçalhos HTTP)** que são definidos no painel **Integration Request (Solicitação de integração)**. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.path.path\$1name | Substituição do caminho da solicitação. Esse parâmetro, quando definido, contém o caminho da solicitação a ser usado em lugar dos **URL Path Parameters (Parâmetros de caminho de URL)** que são definidos no painel **Integration Request (Solicitação de integração)**. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.requestOverride.querystring.querystring\$1name | Substituição da string de consulta da solicitação. Esse parâmetro, quando definido, contém as strings de consulta da solicitação a serem usadas em lugar dos **URL Query String Parameters (Parâmetros de string de consulta de URL)** que são definidos no painel **Integration Request (Solicitação de integração)**. Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.header.header\$1name | Substituição do cabeçalho da resposta. Esse parâmetro, quando definido, contém o cabeçalho a ser retornado em lugar do Response header (Cabeçalho de resposta) que é definido como o Default mapping (Mapeamento padrão) no painel Integration Response (Resposta de integração). Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). |
| \$1context.responseOverride.status | Substituição do código de status da resposta. Esse parâmetro, quando definido, contém o código de status a ser retornado em lugar do Method response status (Status de resposta de método) que é definido como o Default mapping (Mapeamento padrão) no painel Integration Response (Resposta de integração). Para obter mais informações, consulte [Substituir parâmetros de solicitação e resposta da API e códigos de status por APIs REST no API Gateway](apigateway-override-request-response-parameters.md). |
| \$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.resourceId | O identificador que o API Gateway atribui ao seu recurso. |
| \$1context.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 [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md). |
| \$1context.stage | O estágio de implantação da solicitação de API (por exemplo, `Beta` ou `Prod`). |
| \$1context.wafResponseCode | A resposta recebida do [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` ou `WAF_BLOCK`. Não será definido se o estágio não estiver associado a uma ACL da web. Para obter mais informações, consulte [Usar o AWS WAF para proteger as APIs REST no API Gateway](apigateway-control-access-aws-waf.md). |
| \$1context.webaclArn | O ARN completo da ACL da web que é utilizada para decidir se deseja permitir ou bloquear a solicitação. Não será definido se o estágio não estiver associado a uma ACL da web. Para obter mais informações, consulte [Usar o AWS WAF para proteger as APIs REST no API Gateway](apigateway-control-access-aws-waf.md). |
## Variáveis de entrada
É possível usar as variáveis `$input` com distinção de maiúsculas e minúsculas a seguir para se referir à carga útil e aos parâmetros de solicitação de método. As seguintes funções estão disponíveis:
| Variável e função | Descrição |
| --- | --- |
| \$1input.body | Retorna a carga de solicitação bruta como uma string. É possível usar `$input.body` para preservar números inteiros de ponto flutuante, como `10.00`. |
| \$1input.json(x) | Essa função avalia uma expressão JSONPath e retorna os resultados como uma string JSON. Por exemplo, `$input.json('$.pets')` retorna uma string JSON que representa a estrutura `pets`. 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.params() | Retorna um mapa de todos os parâmetros de solicitação. Recomendamos que você use `$util.escapeJavaScript` para higienizar o resultado a fim de evitar um potencial ataque de injeção. Para o controle total da higienização de solicitações, use uma integração de proxy sem um modelo e realize a higienização de solicitações em sua integração. |
| \$1input.params(x) | Retorna o valor de um parâmetro de solicitação do método do caminho, da string de consulta ou do valor de cabeçalho (pesquisados nessa ordem), considerando uma string de nome do parâmetro `x`. Recomendamos que você use `$util.escapeJavaScript` para higienizar o parâmetro a fim de evitar um potencial ataque de injeção. Para o controle total da higienização de parâmetros, use uma integração de proxy sem um modelo e realize a higienização de solicitações em sua integração. |
| \$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').size()` retornaria `"3"`. 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). |
## Variáveis de estágio
É possível usar as seguintes variáveis de estágio como espaços reservados para ARNs e URLs em integrações de método. Para obter mais informações, consulte [Usar variáveis de estágio para uma API REST no API Gateway](stage-variables.md).
| Sintaxe | Descrição |
| --- | --- |
| \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'], ou \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name* representa um nome de variável de estágio. |
## Variáveis de utilidade
É possível usar as variáveis `$util` com distinção de maiúsculas e minúsculas a seguir para utilizar funções utilitárias para associar modelos. A menos que especificado de outra forma, o conjunto de caracteres padrão é UTF-8.
| Função | Descrição |
| --- | --- |
| \$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: "input" : "$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. |