Modelos de mapeamento para APIs REST

No API Gateway, a solicitação ou a resposta de método de uma API pode receber uma carga útil em um formato diferente da solicitação ou da resposta de integração.

Você pode transformar seus dados para:

• Combinar a carga útil com um formato especificado pela API.

• Substituir parâmetros de solicitação e resposta e códigos de status de uma API.

• Retornar os cabeçalhos de resposta selecionados pelo cliente.

• Associar parâmetros de caminho, parâmetros de string de consulta ou parâmetros de cabeçalho na solicitação de método do proxy HTTP ou do proxy Serviço da AWS.

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

Você pode usar modelos de mapeamento para transformar seus dados. Um modelo de mapeamento é um script expresso em Velocity Template Language (VTL) e aplicado à carga útil usando expressões JSONPath .

Esta seção descreve informações conceituais relacionadas aos modelos de mapeamento. Para ter instruções sobre como criar um modelo de mapeamento para uma API REST do API Gateway, consulte Configurar transformações de dados no API Gateway.

Exemplo de modelo de mapeamento

O exemplo a seguir são dados de entrada para uma solicitação de integração.

[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

O exemplo a seguir é um modelo de mapeamento para transformar os dados da solicitação de integração.

#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]

O exemplo a seguir são os dados de saída da transformação.

[
  {
    "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
  }
]

O diagrama a seguir mostra detalhes desse modelo de mapeamento.

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 #.

2. Um loop foreach itera em cada objeto nos dados JSON originais.

3. A descrição é uma concatenação do id e do type do animal de estimação dos dados JSON originais.

4. askingPrice é o price é o preço dos dados JSON originais.

Modelo de mapeamento PetStore

1 #set($inputRoot = $input.path('$'))
2 [
3 #foreach($elem in $inputRoot)
4  {
5    "description" : "Item $elem.id is a $elem.type.",
6    "askingPrice" : $elem.price
7  }#if($foreach.hasNext),#end
8 #end
9 ]

Neste modelo de mapeamento:

1. Na linha 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 #.

2. Na linha 3, um loop foreach itera em cada objeto nos dados JSON originais.

3. Na linha 5, a description é uma concatenação do id e do type do animal de estimação dos dados JSON originais.

4. Na linha 6, askingPrice é o price, o preço dos dados JSON originais.

Para obter mais informações sobre o Velocity Template Language, consulte Apache Velocity - VTL Reference. Para obter mais informações sobre o JSONPath, consulte JSONPath - XPath para JSON.

O modelo de mapeamento pressupõe que os dados subjacentes sejam de um objeto JSON. Ele não exige que um modelo seja definido para os dados. No entanto, um modelo para os dados de saída possibilita que os dados anteriores sejam retornados como um objeto específico da linguagem. Para ter mais informações, consulte Modelos de dados para APIs REST.

Exemplos de modelo de mapeamento complexo

Também é possível criar modelos de mapeamento mais complicados. O exemplo a seguir mostra a concatenação de referências e um limite de cem para determinar se um animal de estimação é acessível.

O exemplo a seguir são dados de entrada para uma solicitação de integração.

[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]

O exemplo a seguir é um modelo de mapeamento para transformar os dados da solicitação de integração.

#set($inputRoot = $input.path('$'))
#set($cheap = 100)
[
#foreach($elem in $inputRoot)
  {
#set($name = "${elem.type}number$elem.id")
    "name" : $name,
    "description" : "Item $elem.id is a $elem.type.",
    #if($elem.price > $cheap )#set ($afford = 'too much!') #{else}#set ($afford = $elem.price)#end
"askingPrice" : $afford
  }#if($foreach.hasNext),#end
  
#end
]

O exemplo a seguir são os dados de saída da transformação.

[
  {
    "name" : dognumber1,
    "description" : "Item 1 is a dog.",
    "askingPrice" : too much!
  },  
  {
    "name" : catnumber2,
    "description" : "Item 2 is a cat.",
    "askingPrice" : too much!
  },  
  {
    "name" : fishnumber3,
    "description" : "Item 3 is a fish.",
    "askingPrice" : 0.99
  }  
]

Você também pode ver modelos de dados mais complicados. Consulte Exemplo de modelos de dados e modelos de mapeamento para o API Gateway.