# 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\":{}}"}
```