Tutorial: Criar uma API REST com integração não proxy HTTP - Amazon API Gateway

Tutorial: Criar uma API REST com integração não proxy HTTP

nota

Reformulamos o console do API Gateway. A experiência no console antigo não estará mais disponível a partir do final de novembro de 2023. Para saber como usar o console para criar uma API REST, consulte Conceitos básicos do console da API REST.

Neste tutorial, você criará uma API do zero usando o console do Amazon API Gateway. Você pode pensar no console como um estúdio de design de API e usá-lo para definir o escopo dos recursos da API, testar seus comportamentos, criar a API e implantá-la em estágios.

Criar uma API com integração personalizada HTTP

Esta seção orienta você pelas etapas necessárias para criar recursos, expor métodos em um recurso, configurar um método para alcançar os comportamentos de API desejados e testar e implantar a API.

  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Se esta for a primeira vez que você usa o API Gateway, você verá uma página com os recursos do serviço. Em REST API, escolha Build (Criar). Quando o pop-up Create Example API (Criar API de exemplo) for exibido, escolha OK.

    Se essa não for a primeira vez que você usa o API Gateway, escolha Create API (Criar API). Em REST API, escolha Build (Criar).

    1. Selecione New API (Nova API).

    2. Digite um nome em API Name (Nome da API).

    3. Se preferir, adicione uma breve descrição em Description (Descrição).

    4. Selecione Create API (Criar API).

    Como resultado, uma API vazia é criada. A árvore Resources (Recursos) mostra o recurso raiz (/) sem métodos. Neste exercício, criaremos a API com a integração HTTP personalizada do site da PetStore (http://petstore-demo-endpoint.execute-api.com/petstore/pets.) Para fins de ilustração, vamos criar um recurso /pets como um filho da raiz e expor um método GET nesse recurso para um cliente recuperar uma lista de itens de animais de estimação disponíveis no site PetStore.

  3. Para criar o recurso /pets, selecione a raiz, escolha Actions (Ações) e depois escolha Create Resource (Criar recurso).

    Digite Pets no campo Resource Name (Nome do recurso), deixe o valor Resource Path (Caminho do recurso) como determinado e escolha Enable API Gateway CORS (Habilitar CORS do API Gateway) e depois clique em Create Resource (Criar recurso).

    
                        Criar um recurso Parte B
  4. Para expor um método GET no recurso /pets, escolha Actions (Ações) e Create Method (Criar método).

    
                        Criar um método em um recurso

    Escolha GET na lista abaixo do nó de recurso /pets e escolha o ícone de marca de seleção para concluir a criação do método.

    
                        Criar um método em um recurso
    nota

    Outras opções para um método de API incluem:

    • POST, usado principalmente para criar recursos filho.

    • PUT, usado principalmente para atualizar recursos existentes (e, embora não seja recomendado, pode ser usado para criar recursos filho).

    • DELETE, usado para excluir recursos.

    • PATCH, usado para atualizar recursos.

    • HEAD, usado, principalmente em cenários de teste. É o mesmo que GET, mas não retorna a representação do recurso.

    • OPTIONS, que pode ser usado por autores de chamadas para obter informações sobre opções de comunicação disponíveis para o serviço de destino.

    O método criado ainda não está integrado ao backend. A próxima etapa configurará isso.

  5. No painel Setup (Configuração) do método, selecione HTTP para Integration type (Tipo de integração), selecione GET na lista suspensa HTTP method (Método HTTP), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets como o valor Endpoint URL (URL do endpoint), deixe todas as outras configurações como padrão e escolha Save (Salvar).

    nota

    Para o HTTP method (Método HTTP) da solicitação de integração, você deve escolher um que seja compatível com o backend. Para HTTP ou Mock integration, faz sentido que a solicitação de método e a solicitação de integração usem o mesmo verbo HTTP. Para outros tipos de integração, a solicitação de método provavelmente usará um verbo HTTP diferente da solicitação de integração. Por exemplo, para chamar uma função do Lambda, a solicitação de integração deve usar POST para invocar a função, enquanto a solicitação de método pode usar qualquer verbo HTTP, dependendo da lógica da função do Lambda.

    
                        Integrar o método GET on pets ao site PetStore

    Quando a configuração do método terminar, será exibido o painel Method Execution (Execução de método), no qual é possível configurar ainda mais a solicitação de método para adicionar uma string de consulta ou parâmetros de cabeçalho personalizados. Você também pode atualizar a solicitação de integração para mapear dados de entrada da solicitação de método para o formato exigido pelo backend.

    O site PetStore permite que você recupere uma lista de itens Pet por tipo de animal de estimação (por exemplo, "Cão" ou "Gato") em uma determinada página. Ele usa os parâmetros de string de consulta type e page para aceitar essa entrada. Sendo assim, precisamos adicionar os parâmetros de string de consulta à solicitação de método e mapeá-los para as strings de consulta correspondentes da solicitação de integração.

  6. No painel Method Execution (Execução de método) do método GET, escolha Method Request (Solicitação de método), selecione AWS_IAM para Authorization (Autorização), expanda a seção URL Query String Parameters (Parâmetros de string de consulta da URL) e escolha Add query string (Adicionar string de consulta) para criar dois parâmetros de string de consulta denominados type e page. Escolha o ícone de marca de seleção para salvar todos os parâmetros de string de consulta conforme você os adiciona.

    
                        Adicionar strings de consulta à solicitação de método GET on pets

    O cliente agora pode fornecer um tipo de animal de estimação e um número de página como parâmetros de string de consulta ao enviar uma solicitação. Esses parâmetros de entrada devem ser mapeados para parâmetros da sequência de consulta da integração para encaminhar os valores de entrada para nosso site PetStore no backend. Como o método usa AWS_IAM, você deve assinar a solicitação para invocá-lo.

  7. Na página Integration Request (Solicitação de integração) do método, expanda a seção URL Query String Parameters (Parâmetros de string de consulta da URL). Por padrão, os parâmetros da string de consulta da solicitação de método são mapeados para os parâmetros da string de consulta da solicitação de integração que possuem nomes semelhantes. Esse mapeamento padrão funciona para a nossa API de demonstração. Vamos deixá-los sem alterações. Para mapear um parâmetro de solicitação de método diferente para o parâmetro de solicitação de integração correspondente, escolha o ícone de lápis do parâmetro para editar a expressão de mapeamento, mostrada na coluna Mapped from (Mapeado de). Para mapear um parâmetro de solicitação de método para um parâmetro de solicitação de integração diferente, primeiro escolha o ícone de exclusão para remover o parâmetro de solicitação de integração existente e depois escolha Add query string (Adicionar string de consulta) para especificar um novo nome e a expressão desejada para o mapeamento de parâmetro de solicitação de método.

    
                        Mapear strings de consulta para o método GET on pets da solicitação de método para a solicitação de integração

    Isso conclui a construção da API de demonstração simples. É hora de testar essa API.

  8. Para testar a API usando o console do API Gateway, escolha Test (Testar) no painel Method Execution (Execução de método) para o método GET /pets. No painel Method Test (Teste de método), digite Dog e 2 para as strings de consulta type (tipo) e page (página), respectivamente, e escolha Test (Testar).

    O resultado é mostrado da seguinte forma. (Talvez você precise rolar para baixo para ver o resultado do teste.)

    
                        Testar/invocar o resultado do método GET on pets

    Agora que o teste foi bem-sucedido, podemos implantar a API para torná-la disponível publicamente.

  9. Para implantar a API, selecione-a e depois escolha Deploy API (Implantar API) no menu suspenso Actions (Ações).

    
                        Implantar a API

    Na caixa de diálogo Deploy API (Implantar API), escolha um estágio (ou [New Stage] para a primeira implantação da API), insira um nome (por exemplo, "test", "prod", "dev" etc.) no campo de entrada Stage name (Nome do estágio), forneça opcionalmente uma descrição em Stage description (Descrição do estágio) e/ou Deployment description (Descrição da implantação) e, em seguida, escolha Deploy (Implantar).

    
                        Implantar a API, parte 2

    Uma vez implantada, você pode obter as URLs de invocação (Invoke URL (Invocar URL)) dos endpoints da API.

    Se o método GET oferecesse suporte para acesso aberto (se o tipo de autorização do método estivesse definido como NONE), você poderia clicar duas vezes no link Invoke URL (Invocar URL) para invocar esse método em seu navegador padrão. Se necessário, você também poderia anexar parâmetros de string de consulta necessários à URL de invocação. Com o tipo de autorização AWS_IAM descrito aqui, é necessário assinar a solicitação com credenciais da AWS. Para fazer isso, você deve usar um cliente compatível com os protocolos Signature Version 4 (SigV4). Um exemplo desse cliente é um aplicativo que usa um dos SDKs da AWS ou o aplicativo Postman ou comandos cURL.

    Se você usar um SDK para criar um cliente, poderá chamar os métodos expostos pelo SDK para assinar a solicitação. Para obter detalhes da implementação, consulte o SDK da AWS de sua escolha.

    nota

    Quando alterações são feitas na sua API, você deve reimplantá-la para disponibilizar os recursos novos ou atualizados antes de invocar novamente a URL da solicitação.

Mapear parâmetros de solicitação para uma API do API Gateway

Nesta demonstração, descrevemos como mapear parâmetros de solicitação de método para os parâmetros de solicitação de integração correspondentes de uma API do API Gateway. Criamos uma API demonstrativa com integração HTTP personalizada e a utilizamos para demonstrar como usar o API Gateway para mapear um parâmetro de solicitação de método ao parâmetro de solicitação de integração correspondente. Em seguida, acessamos o seguinte endpoint HTTP de acesso público:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

Se você copiar o URL acima, colá-lo na barra de endereços de um navegador da web e pressionar Enter ou Return, obterá o seguinte corpo de resposta formatado em JSON:

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

O endpoint anterior pode usar dois parâmetros de consulta: type e page. Por exemplo, altere o URL para o seguinte:

http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=cat&page=2

Você receberá a seguinte carga de resposta em formato JSON, exibindo a página 2 apenas dos gatos:

[ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]

Esse endpoint também oferece suporte ao uso de um ID de item, expresso por um parâmetro de caminho de URL. Por exemplo, navegue até o seguinte:

http://petstore-demo-endpoint.execute-api.com/petstore/pets/1

As seguintes informações em formato JSON sobre o item com um ID de 1 são exibidas:

{ "id": 1, "type": "dog", "price": 249.99 }

Além de oferecer suporte a operações GET, esse endpoint usa solicitações POST com uma carga. Por exemplo, use o Postman para enviar uma solicitação de método POST para o seguinte:

http://petstore-demo-endpoint.execute-api.com/petstore/pets

inclua o cabeçalho Content-type: application/json e o seguinte corpo de solicitação:

{ "type": "dog", "price": 249.99 }

Você receberá o seguinte objeto JSON no corpo da resposta:

{ "pet": { "type": "dog", "price": 249.99 }, "message": "success" }

Agora, expomos estes e outros recursos com a criação de uma API do API Gateway com a integração HTTP personalizada desse site PetStore. As tarefas incluem o seguinte:

  • Criar uma API com um recurso de https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets atuando como um proxy para o endpoint HTTP de http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • Permitir que a API aceite dois parâmetros de consulta de solicitação de método de petType e petsPage, mapeá-los para os parâmetros de consulta type e page da solicitação de integração, respectivamente, e transmitir a solicitação ao endpoint HTTP.

  • Oferecer suporte a um parâmetro de caminho de {petId} na URL da solicitação de método da API para especificar um ID de item, mapeá-lo para o parâmetro de caminho {id} na URL da solicitação de integração e enviar a solicitação ao endpoint HTTP.

  • Permitir que a solicitação de método aceite a carga JSON do formato definido pelo site de backend e passe a carga sem modificações por meio da solicitação de integração para o endpoint HTTP de backend.

nota

Preste atenção à formatação de maiúsculas e minúsculas usada nas etapas deste passo-a-passo. Digitar uma letra minúscula em vez de uma maiúscula (ou vice-versa) pode causar erros mais adiante no processo.

Pré-requisitos

Antes de iniciar este passo-a-passo, você deve fazer o seguinte:

  1. Siga as etapas em Pré-requisitos para começar a usar o API Gateway.

  2. Siga pelo menos as etapas em Tutorial: Criar uma API REST com integração não proxy HTTP para criar uma nova API denominada MyDemoAPI no console do API Gateway.

Etapa 1: Criar recursos

Nesta etapa, você cria três recursos que permitem que a API interaja com o endpoint HTTP.

Para criar o primeiro recurso
  1. No painel Resources (Recursos), selecione a raiz do recurso, representada por uma única barra (/) e, em seguida, escolha Create Resource (Criar recurso) no menu suspenso Actions (Ações).

  2. Em Resource Name (Nome do recurso), digite petstorewalkthrough.

  3. Em Resource Path (Caminho do recurso), aceite o padrão /petstorewalkthrough e, depois, escolha Create Resource (Criar recurso).

Para criar o segundo recurso
  1. No painel Resources (Recursos), escolha /petstorewalkthrough e, em seguida, Create Resource (Criar recurso).

  2. Em Resource Name (Nome do recurso), digite pets.

  3. Em Resource Path (Caminho do recurso), aceite o padrão /petstorewalkthrough/pets e, depois, escolha Create Resource (Criar recurso).

Para criar o terceiro recurso
  1. No painel Resources (Recursos), escolha /petstorewalkthrough/pets e, depois, escolha Create Resource (Criar recurso).

  2. Em Resource Name (Nome do recurso), digite petId. Isso é mapeado para o ID do item no endpoint HTTP.

  3. Em Resource Path (Caminho do recurso), substitua petid por {petId}. Use chaves ({ }) petId para que /petstorewalkthrough/pets/ {petId} seja exibido e, depois, escolha Create Resource (Criar recurso).

    Isso é mapeado para /petstore/pets/my-item-id no endpoint HTTP.

Etapa 2: Criar e testar métodos

Nesta etapa, você integra os métodos aos endpoints HTTP de backend, mapeia os parâmetros de solicitação do método GET para os parâmetros de solicitação de integração correspondentes e testa os métodos.

Para configurar e testar o primeiro método GET

Este procedimento demonstra o seguinte:

  • Crie e integre a solicitação de método de GET /petstorewalkthrough/pets com a solicitação de integração de GET http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • Mapeie os parâmetros de consulta da solicitação de método de petType e petsPage para os parâmetros de string de consulta da solicitação de integração de type e page, respectivamente.

  1. No painel Resources (Recursos), escolha /petstorewalkthrough/pets, e Create Method (Criar método) no menu Actions (Ações) e, em seguida, escolha GET em /pets na lista suspensa de nomes de métodos.

  2. No painel /petstorewalkthrough/pets - GET - Setup, escolha HTTP para Integration type (Tipo de integração) e escolha GET para HTTP method (Método HTTP).

  3. Em Endpoint URL (URL do endpoint), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  4. Escolha Save (Salvar).

  5. No painel Method Execution (Execução de método), escolha Method Request (Solicitação de método) e escolha a seta ao lado de URL Query String Parameters (Parâmetros de string de consulta de URL).

  6. Escolha Add query string (Adicionar string de consulta).

  7. Para Name (Nome), digite petType.

    Isso especifica o parâmetro de consulta petType na solicitação de método da API.

  8. Escolha o ícone de marca de seleção para terminar de criar o parâmetro de string de consulta da URL da solicitação de método.

  9. Escolha Add query string (Adicionar string de consulta) novamente.

  10. Para Name (Nome), digite petsPage.

    Isso especifica o parâmetro de consulta petsPage na solicitação de método da API.

  11. Escolha o ícone de marca de seleção para terminar de criar o parâmetro de string de consulta da URL da solicitação de método.

  12. Escolha Method Execution (Execução de método), escolha Integration Request (Solicitação de integração) e escolha a seta ao lado de URL Query String Parameters (Parâmetros de string de consulta de URL).

  13. Exclua a entrada petType mapeada de method.request.querystring.petType e a entrada petsPage mapeada de method.request.querystring.petsPage. Realize esta etapa pois o endpoint exige parâmetros de string de consulta com os nomes type e page para o URL da solicitação, em vez dos valores padrão.

  14. Escolha Add query string (Adicionar string de consulta).

  15. Para Name (Nome), digite type. Isso cria o parâmetro de string de consulta necessário para a URL da solicitação de integração.

  16. Em Mapped from (Mapeado de), digite method.request.querystring.petType.

    Isso mapeia o parâmetro de consulta petType da solicitação de método para o parâmetro de consulta type da solicitação de integração.

  17. Escolha o ícone de marca de seleção para terminar de criar o parâmetro de string de consulta da URL da solicitação de integração.

  18. Escolha Add query string (Adicionar string de consulta) novamente.

  19. Para Name (Nome), digite page. Isso cria o parâmetro de string de consulta necessário para a URL da solicitação de integração.

  20. Em Mapped from (Mapeado de), digite method.request.querystring.petsPage.

    Isso mapeia o parâmetro de consulta petsPage da solicitação de método para o parâmetro de consulta page da solicitação de integração.

  21. Escolha o ícone de marca de seleção para terminar de criar o parâmetro de string de consulta da URL da solicitação de integração.

  22. Escolha Method Execution (Execução de método). Na caixa Client (Cliente), escolha TEST. Na área Query Strings (Strings de consulta), para petType, digite cat. Para petsPage, digite 2.

  23. Escolha Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    [ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]
Para configurar e testar o segundo método GET

Este procedimento demonstra o seguinte:

  • Crie e integre a solicitação de método de GET /petstorewalkthrough/pets/{petId} com a solicitação de integração de GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}.

  • Mapeie os parâmetros de caminho da solicitação de método de petId para os parâmetros de caminho da solicitação de integração de id.

  1. Na lista Resources (Recursos), escolha /petstorewalkthrough/pets/{petId}, Create Method (Criar método) no menu suspenso Actions (Ações) e, em seguida, escolha GET como o verbo HTTP para o método.

  2. No painel Setup (Configuração), escolha HTTP para Integration type (Tipo de integração) e escolha GET para HTTP method (Método HTTP).

  3. Em Endpoint URL (URL do endpoint), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}.

  4. Escolha Save (Salvar).

  5. No painel Method Execution (Execução de método), escolha Integration Request (Solicitação de integração) e escolha a seta próxima a URL Path Parameters (Parâmetros de caminho de URL).

  6. Escolha Add path (Adicionar caminho).

  7. Para Name (Nome), digite id.

  8. Em Mapped from (Mapeado de), digite method.request.path.petId.

    Isso mapeia o parâmetro de caminho da solicitação de método de petId para o parâmetro de caminho da solicitação de integração de id.

  9. Escolha o ícone de marca de seleção para terminar de criar o parâmetro de caminho da URL.

  10. Escolha Method Execution (Execução de método) e, na caixa Client (Cliente), escolha TEST. Na área Path (Caminho), em petId, digite 1.

  11. Escolha Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    { "id": 1, "type": "dog", "price": 249.99 }
Para configurar e testar o método POST

Este procedimento demonstra o seguinte:

  • Crie e integre a solicitação de método de POST /petstorewalkthrough/pets com a solicitação de integração de POST http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  • Transmita a carga JSON da solicitação de método para a carga da solicitação de integração sem modificação.

  1. No painel Resources (Recursos), escolha /petstorewalkthrough/pets, Create Method (Criar método) no menu suspenso Actions (Ações) e, em seguida, escolha POST como o verbo HTTP para o método.

  2. No painel Setup (Configuração), escolha HTTP para Integration type (Tipo de integração) e escolha POST para HTTP method (Método HTTP).

  3. Em Endpoint URL (URL do endpoint), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets.

  4. Escolha Save (Salvar).

  5. No painel Method Execution (Execução de método), na caixa Client (Cliente), escolha TEST. Expanda Request Body (Corpo da solicitação) e digite o seguinte:

    { "type": "dog", "price": 249.99 }
  6. Escolha Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    { "pet": { "type": "dog", "price": 249.99 }, "message": "success" }

Etapa 3: implantar a API

Nesta etapa, você implantará a API para poder começar a chamá-la fora do console do API Gateway.

Para implantar a API
  1. No painel Resources (Recursos), escolha Deploy API (Implantar API).

  2. Em Deployment stage (Estágio de implantação), selecione test.

    nota

    A entrada deve ser texto codificado UTF-8 (ou seja, não localizado).

  3. For Deployment description (Descrição da implantação), digite Calling HTTP endpoint walkthrough.

  4. Escolha Deploy (Implantar).

Etapa 4: testar a API

Nesta etapa, você sairá do console do API Gateway e usará sua API para acessar o endpoint HTTP.

  1. No painel Stage Editor (Editor de estágio), ao lado de Invoke URL (Invocar URL), copie a URL na área de transferência. A aparência será semelhante à seguinte:

    https://my-api-id.execute-api.region-id.amazonaws.com/test
  2. Cole esta URL na caixa de endereço de uma nova guia do navegador.

  3. Acrescente /petstorewalkthrough/pets para obter a seguinte aparência:

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

    Navegue até a URL. As seguintes informações devem ser exibidas:

    [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ]
  4. Depois de petstorewalkthrough/pets, digite ?petType=cat&petsPage=2 para que fique semelhante a isto:

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets?petType=cat&petsPage=2
  5. Navegue até a URL. As seguintes informações devem ser exibidas:

    [ { "id": 4, "type": "cat", "price": 999.99 }, { "id": 5, "type": "cat", "price": 249.99 }, { "id": 6, "type": "cat", "price": 49.97 } ]
  6. Depois de petstorewalkthrough/pets, substitua ?petType=cat&petsPage=2 por /1 para que fique semelhante a isto:

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets/1
  7. Navegue até a URL. As seguintes informações devem ser exibidas:

    { "id": 1, "type": "dog", "price": 249.99 }
  8. Usando uma ferramenta de proxy de depuração da Web ou a ferramenta de linha de comando cURL, envie uma solicitação de método POST à URL do procedimento anterior. Acrescente /petstorewalkthrough/pets para obter a seguinte aparência:

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

    Anexe o seguinte cabeçalho:

    Content-Type: application/json

    Adicione o seguinte código ao corpo da solicitação:

    { "type": "dog", "price": 249.99 }

    Por exemplo, se você usar a ferramenta de linha de comando cURL, execute um comando semelhante ao seguinte:

    curl -H "Content-Type: application/json" -X POST -d "{\"type\": \"dog\",\"price\": 249.99}" https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/pets

    As seguintes informações devem ser retornadas no corpo da resposta:

    { "pet": { "type": "dog", "price": 249.99 }, "message": "success" }

Você chegou ao final deste passo a passo.

Mapear carga da resposta

Nesta demonstração, mostraremos como usar modelos e modelos de mapeamento no API Gateway para transformar a saída de uma chamada de API de um esquema de dados para outro. Este passo-a-passo baseia-se nas instruções e nos conceitos em Conceitos básicos do API Gateway e Mapear parâmetros de solicitação para uma API do API Gateway. Se você ainda não completou esses tutoriais passo-a-passo, sugerimos que faça isso primeiro.

Esta demonstração usa o API Gateway para obter dados de exemplo de um endpoint HTTP publicamente acessível e de uma função do AWS Lambda criada por você. Tanto o endpoint HTTP quanto a função do Lambda retornam os mesmos dados demonstrativos:

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

Você usará modelos e modelos de mapeamento para transformar esses dados em um ou mais formatos de saída. No API Gateway, um módulo define o formato, também conhecido como o esquema ou forma, de alguns dados. No API Gateway, um modelo do mapeamento é usado para transformar alguns dados de um formato em outros. Para obter mais informações, consulte Noções básicas dos modelos de dados.

O primeiro modelo e o modelo de mapeamento são usados para renomear id como number, type como class e price como salesPrice, da seguinte maneira:

[ { "number": 1, "class": "dog", "salesPrice": 249.99 }, { "number": 2, "class": "cat", "salesPrice": 124.99 }, { "number": 3, "class": "fish", "salesPrice": 0.99 } ]

O segundo modelo e modelo de mapeamento são usados para combinar id e type em description e para renomear price como askingPrice, da seguinte maneira:

[ { "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 terceiro modelo e modelo de mapeamento são usados para combinar id, type e price em um conjunto de listings, da seguinte maneira:

{ "listings": [ "Item 1 is a dog. The asking price is 249.99.", "Item 2 is a cat. The asking price is 124.99.", "Item 3 is a fish. The asking price is 0.99." ] }

Etapa 1: criar uma função do Lambda

Primeiro, você criará uma função do Lambda que retornará os dados da amostra da integração personalizada do Lambda.

Como criar a função do Lambda.
  1. Abra o console do AWS Lambda em https://console.aws.amazon.com/lambda/.

  2. Escolha Create function (Criar função).

  3. Escolha Author from scratch (Criar do zero).

  4. Em Function name (Nome da função), insira GetPetsInfo.

  5. Escolha Create function (Criar função).

  6. Copie a função do Lambda a seguir e cole-a no editor de código do console do Lambda. Escolha Deploy (Implantar) para atualizar a sua função.

    console.log('Loading event'); export const handler = function(event, context, callback) { callback(null, [{"id": 1, "type": "dog", "price": 249.99}, {"id": 2, "type": "cat", "price": 124.99}, {"id": 3, "type": "fish", "price": 0.99}]); // SUCCESS with message };
    dica

    No código anterior, escrito em Node.js, o console.log grava informações em um Amazon CloudWatch log. O event contém a entrada da função do Lambda. O context contém o contexto de chamada. O callback retorna o resultado. Para obter mais informações sobre como escrever o código da função do Lambda, consulte a seção “Modelo de programação” em AWS Lambda: Como funciona e as instruções de exemplo no Guia do desenvolvedor do AWS Lambda.

Etapa 2: criar modelos

Nesta etapa, você cria quatro modelos. Os três primeiros modelos representam os formatos de saída de dados para uso com o endpoint HTTP. O último modelo representa o esquema de entrada de dados para uso com a função do Lambda.

Para criar o primeiro modelo de saída
  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Se MyDemoAPI for exibido, escolha Models (Modelos).

  3. Escolha Create (Criar).

  4. Em Model name (Nome do modelo), digite PetsModelNoFlatten.

  5. Em Content type (Tipo de conteúdo)application/json, digite .

  6. Em Model description (Descrição do modelo), digite Changes id to number, type to class, and price to salesPrice.

  7. Em Model schema (Esquema do modelo), digite a seguinte definição compatível com o Esquema JSON:

    { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetsModelNoFlatten", "type": "array", "items": { "type": "object", "properties": { "number": { "type": "integer" }, "class": { "type": "string" }, "salesPrice": { "type": "number" } } } }
  8. Escolha Create model (Criar modelo).

Para criar o segundo modelo de saída
  1. Escolha Create (Criar).

  2. Em Model name (Nome do modelo), digite PetsModelFlattenSome.

  3. Em Content type (Tipo de conteúdo)application/json, digite .

  4. Em Model description (Descrição do modelo), digite Combines id and type into description, and changes price to askingPrice.

  5. Em Model schema (Esquema do modelo), digite o seguinte:

    { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetsModelFlattenSome", "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string" }, "askingPrice": { "type": "number" } } } }
  6. Escolha Create model (Criar modelo).

Para criar o terceiro modelo de saída
  1. Escolha Create (Criar).

  2. Em Model name (Nome do modelo), digite PetsModelFlattenAll.

  3. Em Content type (Tipo de conteúdo)application/json, digite .

  4. Em Model description (Descrição do modelo), digite Combines id, type, and price into a set of listings.

  5. Em Model schema (Esquema do modelo), digite o seguinte:

    { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetsModelFlattenAll", "type": "object", "properties": { "listings": { "type": "array", "items": { "type": "string" } } } }
  6. Escolha Create model (Criar modelo).

Para criar o modelo de entrada
  1. Escolha Create (Criar).

  2. Em Model name (Nome do modelo), digite PetsLambdaModel.

  3. Em Content type (Tipo de conteúdo)application/json, digite .

  4. Em Model description (Descrição do modelo), digite GetPetsInfo model.

  5. Em Model schema (Esquema do modelo), digite o seguinte:

    { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetsLambdaModel", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "price": { "type": "number" } } } }
  6. Escolha Create model (Criar modelo).

Etapa 3: criar recursos

Nesta etapa, você cria quatro recursos. Os três primeiros recursos permitem que você obtenha os dados de exemplo do endpoint HTTP nos três formatos de saída. O último recurso permite que você obtenha os dados de exemplo da função do Lambda no mesmo esquema de saída de /flattensome.

Para criar o primeiro recurso
  1. Na lista de links, escolha Resources (Recursos).

  2. No painel Resources (Recursos), escolha /petstorewalkthrough e, em seguida, Create Resource (Criar recurso).

  3. Em Resource Name (Nome do recurso), digite NoFlatten.

  4. Em Resource Path (Caminho do recurso), aceite o padrão de /petstorewalkthrough/noflatten e, depois, escolha Create Resource (Criar recurso).

Para criar o segundo recurso
  1. No painel Resources (Recursos), escolha /petstorewalkthrough novamente e, em seguida, Create Resource (Criar recurso).

  2. Em Resource Name (Nome do recurso), digite FlattenSome.

  3. Em Resource Path (Caminho do recurso), aceite o padrão de /petstorewalkthrough/flattensome e, depois, escolha Create Resource (Criar recurso).

Para criar o terceiro recurso
  1. No painel Resources (Recursos), escolha /petstorewalkthrough novamente e, em seguida, Create Resource (Criar recurso).

  2. Em Resource Name (Nome do recurso), digite FlattenAll.

  3. Em Resource Path (Caminho do recurso), aceite o padrão de /petstorewalkthrough/flattenall e, depois, escolha Create Resource (Criar recurso).

Para criar o quarto recurso
  1. No painel Resources (Recursos), escolha /petstorewalkthrough novamente e, em seguida, Create Resource (Criar recurso).

  2. Em Resource Name (Nome do recurso), digite LambdaFlattenSome.

  3. Em Resource Path (Caminho do recurso), aceite o padrão de /petstorewalkthrough/lambdaflattensome e, depois, escolha Create Resource (Criar recurso).

Etapa 4: criar métodos GET

Nesta etapa, você cria um método GET para cada um dos recursos que criou na etapa anterior.

Para criar o primeiro método GET
  1. Na lista Resources (Recursos), escolha /petstorewalkthrough/flattenall novamente e, depois, Create Method (Criar método).

  2. Na lista suspensa, escolha GET e, em seguida, escolha o ícone de marca de seleção para salvar sua opção.

  3. No painel de configuração, selecione HTTP para o Integration type (Tipo de integração) e GET para HTTP method (Método HTTP), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets em Endpoint URL (URL do endpoint) e escolha Save (Salvar).

Para criar o segundo método GET
  1. Na lista Resources (Recursos), escolha /petstorewalkthrough/lambdaflattensome e, depois, Create Method (Criar método).

  2. Na lista suspensa, escolha GET e, em seguida, escolha a marca de seleção para salvar sua opção.

  3. No painel Setup (Configuração), selecione Lambda Function (Função do Lambda) para o Integration type (Tipo de integração).

  4. Deixe a caixa Use Lambda Proxy integration (Usar integração de proxy do Lambda) desmarcada.

  5. Insira GetPetsInfo para a função do Lambda.

  6. Escolha OK quando solicitado a adicionar permissão para a função do Lambda.

Para criar o terceiro método GET
  1. Na lista Resources (Recursos), escolha /petstorewalkthrough/flattensome e, depois, Create Method (Criar método).

  2. Na lista suspensa, escolha GET e, em seguida, escolha o ícone de marca de seleção para salvar sua opção.

  3. No painel de configuração, selecione HTTP para o Integration type (Tipo de integração) e GET para HTTP method (Método HTTP), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets em Endpoint URL (URL do endpoint) e, em seguida, escolha Save (Salvar).

Para criar o quarto método GET
  1. Na lista Resources (Recursos), escolha /petstorewalkthrough/noflatten e, depois, Actions (Ações), Create Method (Criar método).

  2. Na lista suspensa, escolha GET e, em seguida, escolha o ícone de marca de seleção para salvar sua opção.

  3. No painel de configuração, selecione HTTP para o Integration type (Tipo de integração) e GET para HTTP method (Método HTTP), digite http://petstore-demo-endpoint.execute-api.com/petstore/pets em Endpoint URL (URL do endpoint) e, em seguida, escolha Save (Salvar).

Etapa 5: Configurar e testar os métodos

Nessa etapa, você configurará as respostas de método, as solicitações de integração e as respostas de integração para especificar os esquemas (ou modelos) de dados de entrada e saída para os métodos GET associados ao endpoint HTTP e à função do Lambda. Você também aprenderá a testar a chamada desses métodos usando o console do API Gateway.

Para configurar a integração para o primeiro método GET e testá-lo em seguida
  1. Na árvore Resources (Recursos) da API, escolha GET no nó /petstorewalkthrough/flattenall.

  2. No painel Method Execution (Execução de método), escolha Method Response (Resposta de método) e escolha a seta ao lado de 200.

  3. Na área Response Models for 200 (Modelos de resposta para 200), para application/json, escolha o ícone de lápis para começar a configurar o modelo para a saída do método. Em Models (Modelos), escolha PetsModelFlattenAll e, depois, escolha o ícone de marca de seleção para salvar a configuração.

  4. Escolha Method Execution (Execução de método), Integration Response (Resposta de integração) e escolha a seta ao lado de 200.

  5. Expanda a seção Mapping Templates (Modelos de mapeamento) e selecione application/json (aplicação/json) em Content-Type (Tipo de conteúdo).

  6. Em Generate template from model (Gerar modelo a partir do modelo), escolha PetsModelFlattenAll para exibir um modelo de mapeamento após o modelo PetsModelFlattenAll como um ponto de partida.

  7. Modifique o código do modelo de mapeamento da seguinte maneira:

    #set($inputRoot = $input.path('$')) { "listings" : [ #foreach($elem in $inputRoot) "Item number $elem.id is a $elem.type. The asking price is $elem.price."#if($foreach.hasNext),#end #end ] }
  8. Escolha Save (Salvar).

  9. Escolha Method Execution (Execução de método) e na caixa Client (Cliente), escolha TEST e selecione Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    { "listings" : [ "Item number 1 is a dog. The asking price is 249.99.", "Item number 2 is a cat. The asking price is 124.99.", "Item number 3 is a fish. The asking price is 0.99." ] }
Para configurar a integração para o segundo método GET e testá-lo em seguida
  1. Na árvore Resources (Recursos) da API, escolha GET no nó /petstorewalkthrough/lambdaflattensome .

  2. Em Method Execution (Execução de método), selecione Method Response (Resposta de método). Em seguida, escolha a seta ao lado de 200 para expandir a seção.

  3. Na área Response Models for 200 (Modelos de resposta para 200), escolha o ícone de lápis na linha para o tipo de conteúdo de aplicativo/json. Escolha PetsModelFlattenSome para Models (Modelos) e, depois, escolha o ícone de marca de seleção para salvar a escolha.

  4. Volte para Method Execution (Execução de método). Escolha Integration Response (Resposta de integração) e, em seguida, selecione a seta ao lado de 200.

  5. Na seção Mapping Templates (Modelos de mapeamento), selecione application/json (aplicação/json) em Content-Type (Tipo de conteúdo).

  6. Em Generate template (Gerar modelo), escolha PetsModelFlattenSome para exibir o modelo de script de mapeamento para a saída desse método.

  7. Modifique o código da seguinte maneira e escolha Save (Salvar):

    #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ]
  8. Escolha Method Execution (Execução de método) e na caixa Client (Cliente), escolha TEST e selecione Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    [ { "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 } ]
Para configurar a integração para o terceiro método GET e testá-lo em seguida
  1. Na árvore Resources (Recursos) da API, escolha GET no nó /petstorewalkthrough/flattensome.

  2. No painel Method Execution (Execução de ), selecione Method Response (Resposta de método).

  3. Escolha a seta ao lado de 200.

  4. Na área Response Models for 200 (Modelos de resposta para 200), para application/json, escolha o ícone de lápis. Em Models (Modelos), escolha PetsModelFlattenSome e, depois, escolha o ícone de marca de seleção para salvar a escolha.

  5. Volte para Method Execution (Execução de método) e escolha Integration Response (Resposta de integração).

  6. Escolha a seta ao lado de 200 para expandir a seção.

  7. Expanda a área Mapping Templates (Modelos de mapeamento). Escolha application/json para Content-Type (Tipo de conteúdo). Em Generate template (Gerar modelo), escolha PetsModelFlattenSome para exibir um modelo de script de mapeamento para a saída desse método.

  8. Modifique o código da seguinte maneira:

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

  10. Volte para Method Execution (Execução de método) e escolha TEST na caixa Client (Cliente). Em seguida, escolha Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    [ { "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 } ]
Para configurar a integração para o quarto método GET e testá-lo em seguida
  1. Na árvore Resources (Recursos) da API, escolha GET no nó /petstorewalkthrough/noflatten.

  2. No painel Method Execution (Execução de método), escolha Method Response (Resposta de método) e depois expanda a seção 200.

  3. Na área Response Models for 200 (Modelos de resposta para 200), para application/json, escolha o ícone de lápis para atualizar o modelo de resposta para esse método.

  4. Escolha PetsModelNoFlatten como o modelo para o tipo de conteúdo de application/json e escolha o ícone de marca de verificação para salvar a escolha.

  5. Escolha Method Execution (Execução de método), Integration Response (Resposta de integração) e escolha a seta ao lado de 200 para expandir a seção.

  6. Expanda a seção Mapping Templates (Modelos de mapeamento). Escolha application/json para Content-Type (Tipo de conteúdo). Em Generate templates (Gerar modelos), escolha PetsModelNoFlatten para exibir um modelo de script de mapeamento para a saída desse método.

  7. Modifique o código da seguinte maneira:

    #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "number": $elem.id, "class": "$elem.type", "salesPrice": $elem.price }#if($foreach.hasNext),#end #end ]
  8. Escolha Save (Salvar).

  9. Volte para Method Execution (Execução de método) e, na caixa Client (Cliente), escolha TEST e selecione Test (Testar). Se bem-sucedido, Response Body (Corpo da solicitação) exibe o seguinte:

    [ { "number": 1, "class": "dog", "salesPrice": 249.99 }, { "number": 2, "class": "cat", "salesPrice": 124.99 }, { "number": 3, "class": "fish", "salesPrice": 0.99 } ]

Etapa 6: implantar a API

Nesta etapa, você implantará a API para poder começar a chamá-la fora do console do API Gateway.

Para implantar a API
  1. No painel Resources (Recursos), escolha Deploy API (Implantar API).

  2. Em Deployment stage (Estágio de implantação), selecione test.

  3. For Deployment description (Descrição da implantação), digite Using models and mapping templates walkthrough.

  4. Escolha Deploy (Implantar).

Etapa 7: testar a API

Nesta etapa, você sairá do console do API Gateway para interagir com o endpoint HTTP e com a função do Lambda.

  1. No painel Stage Editor (Editor de estágio), ao lado de Invoke URL (Invocar URL), copie a URL na área de transferência. A aparência será semelhante à seguinte:

    https://my-api-id.execute-api.region-id.amazonaws.com/test
  2. Cole esta URL na caixa de endereço de uma nova guia do navegador.

  3. Acrescente /petstorewalkthrough/noflatten para obter a seguinte aparência:

    https://my-api-id.execute-api.region-id.amazonaws.com/test/petstorewalkthrough/noflatten

    Navegue até a URL. As seguintes informações devem ser exibidas:

    [ { "number": 1, "class": "dog", "salesPrice": 249.99 }, { "number": 2, "class": "cat", "salesPrice": 124.99 }, { "number": 3, "class": "fish", "salesPrice": 0.99 } ]
  4. Depois de petstorewalkthrough/, substitua noflatten por flattensome.

  5. Navegue até a URL. As seguintes informações devem ser exibidas:

    [ { "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 } ]
  6. Depois de petstorewalkthrough/, substitua flattensome por flattenall.

  7. Navegue até a URL. As seguintes informações devem ser exibidas:

    { "listings" : [ "Item number 1 is a dog. The asking price is 249.99.", "Item number 2 is a cat. The asking price is 124.99.", "Item number 3 is a fish. The asking price is 0.99." ] }
  8. Depois de petstorewalkthrough/, substitua flattenall por lambdaflattensome.

  9. Navegue até a URL. As seguintes informações devem ser exibidas:

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

Etapa 8: Limpar

Se você não precisar mais da função do Lambda criada para esta demonstração, poderá excluí-la agora. Você também pode excluir os recursos do IAM que o acompanham.

Atenção

Se você excluir uma função do Lambda da qual dependem as suas APIs, elas deixarão de funcionar. A exclusão de uma função do Lambda não pode ser desfeita. Se quiser usar a função do Lambda novamente, você deverá recriar essa função.

Se você excluir um recurso do IAM do qual depende uma função do Lambda, ela deixará de funcionar, juntamente com as APIs que dependem dela. A exclusão de um recurso do IAM não pode ser desfeita. Se quiser usar o recurso do IAM novamente, você deverá recriá-lo. Se você planeja continuar a testar os recursos criados para esta e outras demonstrações, não exclua a função de invocação do Lambda nem a função de execução do Lambda.

Como excluir a função do Lambda
  1. Faça login no AWS Management Console e abra o console AWS Lambda em https://console.aws.amazon.com/lambda/.

  2. Na página Lambda: Function list (Lambda: lista de funções), escolha o botão ao lado de GetPetsInfo e, depois, escolha Actions (Ações), Delete (Excluir). Quando solicitado, escolha Delete (Excluir) novamente.

Como excluir os recursos do IAM associados
  1. Abra o console do IAM em https://console.aws.amazon.com/iam/.

  2. Na área Details (Detalhes), escolha Roles (Funções).

  3. Selecione APIGatewayLambdaExecRole e, depois, escolha Role Actions (Ações da função), Delete Role (Excluir função). Quando solicitado, escolha Yes, Delete (Sim, excluir).

  4. Na área Details (Detalhes), escolha Policies (Políticas).

  5. Selecione APIGatewayLambdaExecPolicy e, depois, escolha Policy Actions (Ações da política), Delete (Excluir). Quando solicitado, escolha Delete (Excluir).

Você chegou ao final deste passo a passo.