Noções básicas de modelos de mapeamento - Amazon API Gateway
Modelos de mapeamento complexos

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Noções básicas de modelos de mapeamento

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.

  • Associe parâmetros de caminho, parâmetros de sequência de caracteres de consulta ou parâmetros de cabeçalho na solicitação de método do proxy ou AWS service (Serviço da AWS) proxy HTTP.

  • Selecione quais dados enviar usando a integração Serviços da AWS, como funções do Amazon DynamoDB ou 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 .

O exemplo a seguir mostra dados de entrada, um modelo de mapeamento e dados de saída para uma transformação dos PetStore dados.

Dados de entrada 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
Modelo de mapeamento 
#set($inputRoot = $input.path('$'))
[
#foreach($elem in $inputRoot)
  {
    "description" : "Item $elem.id is a $elem.type.",
    "askingPrice" : $elem.price
  }#if($foreach.hasNext),#end

#end
]
Dados de saída 
[
  {
    "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.

exemplo de 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.

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 Noções básicas dos modelos de dados.

Modelos de mapeamento complexos

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.

Dados de entrada 
[
  {
    "id": 1,
    "type": "dog",
    "price": 249.99
  },
  {
    "id": 2,
    "type": "cat",
    "price": 124.99
  },
  {
    "id": 3,
    "type": "fish",
    "price": 0.99
  }
]
Modelo de mapeamento 
#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
]
Dados de saída 
[
  {
    "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
  }  
]

Veja o exemplo de álbum de fotos Exemplo de fotos para ver um modelo mais complicado.