# Tutoriais e workshops do Amazon API Gateway
Os tutoriais e workshops a seguir fornecem exercícios práticos para ajudar você a aprender mais sobre o API Gateway. Para começar, recomendamos que você complete [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md).
**Tutoriais da API REST**
+ [Escolher um tutorial de integração do AWS Lambda](getting-started-with-lambda-integration.md)
+ [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md)
+ [Escolher um tutorial de integração HTTP](getting-started-http-integrations.md)
+ [Tutorial: Crie uma API REST com uma integração privada](getting-started-with-private-integration.md)
+ [Tutorial: Crie uma API REST com uma integração da AWS](getting-started-aws-proxy.md)
+ [Tutorial: Criar uma API REST de calculadora com duas integrações de serviços da AWS e uma integração sem proxy do Lambda](integrating-api-with-aws-services-lambda.md)
+ [Tutorial: Crie uma API REST como um proxy do Amazon S3](integrating-api-with-aws-services-s3.md)
+ [Tutorial: Criar uma API REST como um proxy do Amazon Kinesis](integrating-api-with-aws-services-kinesis.md)
+ [Tutorial: como criar uma API REST usando SDKs da AWS ou a AWS CLI](api-gateway-create-api-cli-sdk.md)
+ [Tutorial: Crie uma API REST privada](private-api-tutorial.md)
**Tutoriais da API HTTP**
+ [Tutorial: Crie uma API HTTP CRUD com o Lambda e o DynamoDB](http-api-dynamo-db.md)
+ [Tutorial: Crie uma API HTTP com uma integração privada a um serviço do Amazon ECS](http-api-private-integration.md)
**Tutoriais da API WebSocket**
+ [Tutorial: Crie uma aplicação de bate-papo de WebSocket com uma API de WebSocket, o Lambda e o DynamoDB](websocket-api-chat-app.md)
**Workshops**
+ [Crie uma aplicação Web sem servidor](https://webapp.serverlessworkshops.io)
+ [CI/CD para aplicações sem servidor](https://cicd.serverlessworkshops.io)
+ [Workshop de segurança sem servidor](https://github.com/aws-samples/aws-serverless-security-workshop)
+ [Gerenciamento, autenticação e autorização de identidade sem servidor](https://auth.serverlessworkshops.io)
+ [The Amazon API Gateway Workshop](https://catalog.workshops.aws/apigateway/en-US)
# Tutoriais da API REST do Amazon API Gateway
Os tutoriais a seguir fornecem exercícios práticos para ajudar você a saber mais sobre as APIs REST do API Gateway.
**Topics**
+ [Escolher um tutorial de integração do AWS Lambda](getting-started-with-lambda-integration.md)
+ [Tutorial: Criar uma API REST importando um exemplo](api-gateway-create-api-from-example.md)
+ [Escolher um tutorial de integração HTTP](getting-started-http-integrations.md)
+ [Tutorial: Crie uma API REST com uma integração privada](getting-started-with-private-integration.md)
+ [Tutorial: Crie uma API REST com uma integração da AWS](getting-started-aws-proxy.md)
+ [Tutorial: Criar uma API REST de calculadora com duas integrações de serviços da AWS e uma integração sem proxy do Lambda](integrating-api-with-aws-services-lambda.md)
+ [Tutorial: Crie uma API REST como um proxy do Amazon S3](integrating-api-with-aws-services-s3.md)
+ [Tutorial: Criar uma API REST como um proxy do Amazon Kinesis](integrating-api-with-aws-services-kinesis.md)
+ [Tutorial: como criar uma API REST usando SDKs da AWS ou a AWS CLI](api-gateway-create-api-cli-sdk.md)
+ [Tutorial: Crie uma API REST privada](private-api-tutorial.md)
# Escolher um tutorial de integração do AWS Lambda
Para criar uma API com integrações do Lambda, é possível usar a integração de proxy ou sem proxy do Lambda.
Com a integração de proxy do Lambda, a entrada da função do Lambda pode ser expressa como qualquer combinação de cabeçalhos de solicitação, variáveis de caminho, parâmetros de strings de consulta, corpo e dados de configuração de API. Só é necessário escolher uma função do Lambda. O API Gateway configura a solicitação de integração e a resposta de integração para você. Após a configuração, o método de API poderá evoluir sem modificar as configurações existentes. Isso é possível porque a função do Lambda de backend analisa os dados da solicitação recebida e responde ao cliente.
Na integração sem proxy do Lambda, é necessário garantir que a entrada da função do Lambda seja fornecida como a carga da solicitação de integração. Você deve mapear todos os dados de entrada fornecidos pelo cliente como parâmetros da solicitação no corpo da solicitação de integração apropriada. Também pode ser necessário converter o corpo da solicitação fornecida pelo cliente em um formato reconhecido pela função do Lambda.
Nas integrações com ou sem proxy do Lambda, é possível usar uma função do Lambda em uma conta diferente da conta em que criou a API.
**Topics**
+ [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md)
+ [Tutorial: Crie uma API REST com uma integração de não proxy do Lambda](getting-started-lambda-non-proxy-integration.md)
+ [Tutorial: Crie uma API REST com uma integração de proxy do Lambda entre contas](apigateway-cross-account-lambda-integrations.md)
# Tutorial: Crie uma API REST com uma integração de proxy do Lambda
A [integração de proxy do Lambda](set-up-lambda-proxy-integrations.md) é um tipo de integração leve e flexível da API do API Gateway que permite integrar um método de API ou uma API inteira a uma função do Lambda. A função do Lambda pode ser escrita em [qualquer linguagem compatível com o Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html). Por se tratar de uma integração de proxy, você pode alterar a implementação da função do Lambda a qualquer momento, sem necessidade de implantar sua API novamente.
Neste tutorial, você faz o seguinte:
+ Criar um "Hello, World\$1" Função do Lambda para ser o backend da API.
+ Criar e testar um "Hello, World\$1" API com integração de proxy do Lambda.
**Topics**
+ [Criar um "Hello, World\$1" Função do Lambda](#api-gateway-proxy-integration-create-lambda-backend)
+ [Criar um "Hello, World\$1" API](#api-gateway-create-api-as-simple-proxy-for-lambda-build)
+ [Implantar e testar a API](#api-gateway-create-api-as-simple-proxy-for-lambda-test)
## Criar um "Hello, World\$1" Função do Lambda
**Como criar um “Hello, World\$1” Função do Lambda no console do Lambda**
1. Abra o console do Lambda em [https://console.aws.amazon.com/lambda](https://console.aws.amazon.com/lambda)
1. Na barra de navegação da AWS, escolha uma [Região da AWS](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
**nota**
Anote a região na qual você criará a função do Lambda. Você precisará dela ao criar a API.
1. Selecione **Functions (Funções)** no painel de navegação.
1. Escolha **Create function** (Criar função).
1. Escolha **Author from scratch** (Criar do zero).
1. Em **Basic information (Informações básicas)**, faça o seguinte:
1. Em **Function name (Nome da função)**, insira **GetStartedLambdaProxyIntegration**.
1. Em **Tempo de execução**, escolha o último runtime **Node.js** ou **Python** compatível.
1. Em **Arquitetura**, mantenha a configuração padrão.
1. Em **Permissions** (Permissões), expanda **Change default execution role** (Alterar função de execução padrão). Na lista suspensa **Perfil de execução**, escolha **Criar perfil com base em modelos de política da AWS**.
1. Em **Role name (Nome da função)**, insira **GetStartedLambdaBasicExecutionRole**.
1. Deixe em branco o campo **Policy templates** (Modelos de política).
1. Escolha **Create function** (Criar função).
1. Em **Function code (Código de função)**, no editor de código em linha, copie/cole o seguinte código:
------
#### [ Node.js ]
```
export const handler = async(event, context) => {
console.log('Received event:', JSON.stringify(event, null, 2));
var res ={
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
}
};
var greeter = 'World';
if (event.greeter && event.greeter!=="") {
greeter = event.greeter;
} else if (event.body && event.body !== "") {
var body = JSON.parse(event.body);
if (body.greeter && body.greeter !== "") {
greeter = body.greeter;
}
} else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") {
greeter = event.queryStringParameters.greeter;
} else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") {
greeter = event.multiValueHeaders.greeter.join(" and ");
} else if (event.headers && event.headers.greeter && event.headers.greeter != "") {
greeter = event.headers.greeter;
}
res.body = "Hello, " + greeter + "!";
return res
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
greeter = 'World'
try:
if (event['queryStringParameters']) and (event['queryStringParameters']['greeter']) and (
event['queryStringParameters']['greeter'] is not None):
greeter = event['queryStringParameters']['greeter']
except KeyError:
print('No greeter')
try:
if (event['multiValueHeaders']) and (event['multiValueHeaders']['greeter']) and (
event['multiValueHeaders']['greeter'] is not None):
greeter = " and ".join(event['multiValueHeaders']['greeter'])
except KeyError:
print('No greeter')
try:
if (event['headers']) and (event['headers']['greeter']) and (
event['headers']['greeter'] is not None):
greeter = event['headers']['greeter']
except KeyError:
print('No greeter')
if (event['body']) and (event['body'] is not None):
body = json.loads(event['body'])
try:
if (body['greeter']) and (body['greeter'] is not None):
greeter = body['greeter']
except KeyError:
print('No greeter')
res = {
"statusCode": 200,
"headers": {
"Content-Type": "*/*"
},
"body": "Hello, " + greeter + "!"
}
return res
```
------
1. Escolha **Deploy** (Implantar).
## Criar um "Hello, World\$1" API
Agora crie uma API para “Hello, World\$1” Função do Lambda usando o console do API Gateway.
**Como criar um “Hello, World\$1” solicitações de**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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. Em **API name (Nome da API)**, insira **LambdaProxyAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
Depois de criar uma API, você criará um recurso. Normalmente, os recursos da API são organizados em uma árvore de recursos, de acordo com a lógica do aplicativo. Neste exemplo, você criará um recurso **/helloworld**.
**Para criar um recurso**
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **helloworld**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Em uma integração de proxy, a solicitação inteira é enviada à função do Lambda de backend como está, por meio de um método `ANY` genérico que representa qualquer método HTTP. O método HTTP real é especificado pelo cliente no tempo de execução. O método `ANY` permite usar uma única configuração do método da API para todos os métodos HTTP compatíveis: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`.
**Como criar um método `ANY`**
1. Selecione o recurso **/helloworld** e, depois, **Criar método**.
1. Em **Tipo de método**, selecione **ANY**.
1. Em **Tipo de integração**, selecione **Função do Lambda**.
1. Ative **Integração de proxy do Lambda**.
1. Em **Função do Lambda**, selecione a Região da AWS onde você criou a função do Lambda e, depois, insira o nome da função.
1. Para usar o valor de tempo limite padrão de 29 segundos, deixe a opção **Tempo limite padrão** ativada. Para definir um tempo limite personalizado, selecione **Tempo limite padrão** e insira um valor de tempo limite entre `50` e `29000` milissegundos.
1. Escolha **Criar método**.
## Implantar e testar a API
**Para implantar sua API**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **test**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API.
### Usar o navegador e cURL para testar uma API com integração de proxy do Lambda
Você pode usar um navegador ou [cURL](https://curl.se/) para testar sua API.
Para testar solicitações `GET` usando apenas parâmetros de string de consulta, você pode inserir o URL do recurso `helloworld` da API em uma barra de endereço do navegador.
Para criar o URL do recurso `helloworld` da API, acrescente o recurso `helloworld` e o parâmetro da string de consulta `?greeter=John` ao URL de invocação. Seu URL deve ter uma aparência semelhante ao seguinte.
```
https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?greeter=John
```
Para outros métodos, é necessário usar utilitários de teste de API REST mais avançados, como o [POSTMAN](https://www.postman.com/) ou o [cURL](https://curl.se/). Este tutorial usa cURL. Os exemplos de comando cURL a seguir pressupõem que cURL foi instalado em seu computador.
**Para testar a API implantada usando cURL:**
1. Abra uma janela do terminal.
1. Copie o comando cURL a seguir e cole-o na janela do terminal, substituindo o URL de invocação pelo que foi copiado na etapa anterior e adicione **/helloworld** ao final do URL.
**nota**
Se você estiver executando o comando no Windows, use a seguinte sintaxe:
```
curl -v -X POST "https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld" -H "content-type: application/json" -d "{ \"greeter\": \"John\" }"
```
1. Para chamar a API com o parâmetro de string de consulta de `?greeter=John`:
```
curl -X GET 'https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld?greeter=John'
```
1. Para chamar a API com um parâmetro de cabeçalho de `greeter:John`:
```
curl -X GET https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld \
-H 'content-type: application/json' \
-H 'greeter: John'
```
1. Como chamar a API com um corpo de `{"greeter":"John"}`:
```
curl -X POST https://r275xc9bmd.execute-api.us-east-1.amazonaws.com/test/helloworld \
-H 'content-type: application/json' \
-d '{ "greeter": "John" }'
```
Em todos os casos, a saída é uma resposta 200 com o corpo de resposta a seguir:
```
Hello, John!
```
# Tutorial: Crie uma API REST com uma integração de não proxy do Lambda
Nesta demonstração, usamos o console do API Gateway para criar uma API que permite a um cliente chamar funções do Lambda por meio da integração não proxy do Lambda (também conhecida como integração personalizada). Para obter mais informações sobre AWS Lambda e as funções do Lambda, consulte o [Guia do desenvolvedor do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/).
Para facilitar o aprendizado, escolhemos uma função do Lambda simples com configuração mínima da API para orientar você pelas etapas de criação de uma API do API Gateway com a integração personalizada do Lambda. Quando necessário, descrevemos parte da lógica. Para ver um exemplo mais detalhado da integração personalizada do Lambda, consulte [Tutorial: Criar uma API REST de calculadora com duas integrações de serviços da AWS e uma integração sem proxy do Lambda](integrating-api-with-aws-services-lambda.md).
Antes de criar a API, configure o backend do Lambda criando uma função do Lambda no AWS Lambda, conforme descrito a seguir.
**Topics**
+ [Criar uma função do Lambda para integração não proxy do Lambda](#getting-started-new-lambda)
+ [Criar uma API com integração não proxy do Lambda](#getting-started-new-api)
+ [Testar a chamada do método de API](#getting-started-new-get)
+ [Implantar a API](#getting-started-deploy-api)
+ [Testar a API em uma etapa de implantação](#getting-started-test)
+ [Limpar](#getting-started-clean-up)
## Criar uma função do Lambda para integração não proxy do Lambda
**nota**
A criação de funções do Lambda pode resultar em cobranças na conta da AWS.
Nesta etapa, crie uma função do Lambda no estilo “Hello, World\$1” para a integração personalizada do Lambda. Durante esta demonstração, a função é chamada `GetStartedLambdaIntegration`.
A implementação dessa função do Lambda `GetStartedLambdaIntegration` é a seguinte:
------
#### [ Node.js ]
```
'use strict';
var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
var times = ['morning', 'afternoon', 'evening', 'night', 'day'];
export const handler = async(event) => {
console.log(event);
// Parse the input for the name, city, time and day property values
let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name;
let city = event.city === undefined ? 'World' : event.city;
let time = times.indexOf(event.time)<0 ? 'day' : event.time;
let day = days.indexOf(event.day)<0 ? null : event.day;
// Generate a greeting
let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. ';
if (day) greeting += 'Happy ' + day + '!';
// Log the greeting to CloudWatch
console.log('Hello: ', greeting);
// Return a greeting to the caller
return {"greeting": greeting}
};
```
------
#### [ Python ]
```
import json
days = {
'Sunday',
'Monday',
'Tuesday',
'Wednesday',
'Thursday',
'Friday',
'Saturday'}
times = {'morning', 'afternoon', 'evening', 'night', 'day'}
def lambda_handler(event, context):
print(event)
# parse the input for the name, city, time, and day property values
name = event.get("name") or 'you'
city = event.get("city") or 'World'
try:
if event['time'] in times:
time = event['time']
else:
time = 'day'
except KeyError:
time = 'day'
try:
if event['day'] in days:
day = event['day']
else:
day = ''
except KeyError:
day = ''
# Generate a greeting
greeting = 'Good ' + time + ', ' + name + ' of ' + \
city + '.' + ['', ' Happy ' + day + '!'][day != '']
# Log the greeting to CloudWatch
print(greeting)
# Return a greeting to the caller
return {"greeting": greeting}
```
------
Para a integração personalizada do Lambda o API Gateway transmite a entrada para a função do Lambda do cliente como o corpo da solicitação de integração. O objeto `event` do manipulador da função do Lambda é a entrada.
Nossa função do Lambda é simples. Ela analisa o objeto de entrada `event` para as propriedades `name`, `city`, `time`e `day`. Em seguida, ela retorna uma saudação, como um objeto JSON de `{"message":greeting}`, para o autor da chamada. A mensagem é no padrão `"Good [morning|afternoon|day], [name|you] in [city|World]. Happy day!"`. Presume-se que a entrada para a função do Lambda seja um dos seguintes objetos JSON:
```
{
"city": "...",
"time": "...",
"day": "...",
"name" : "..."
}
```
Para obter mais informações, consulte o [Guia do desenvolvedor do AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html).
Além disso, a função registra sua execução no Amazon CloudWatch chamando `console.log(...)`. Isso é útil para rastrear as chamadas ao depurar a função. Para permitir que a função `GetStartedLambdaIntegration` registre a chamada, defina uma função do IAM com as políticas apropriadas para que a função do Lambda crie os streams do CloudWatch e adicione entradas de log aos streams. O console do Lambda orienta você na criação das funções e políticas do IAM necessárias.
Se você configurar a API sem usar o console do API Gateway, tal como ao [importar uma API de um arquivo do OpenAPI](https://github.com/aws-samples/api-gateway-secure-pet-store/blob/master/src/main/resources/swagger.yaml#L39), é necessário criar explicitamente, se necessário, e configurar uma função e política de invocação para que o API Gateway invoque as funções do Lambda. Para obter mais informações sobre como configurar funções de invocação e execução do Lambda para uma API do API Gateway, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md).
Em comparação com `GetStartedLambdaProxyIntegration`, a função do Lambda para a integração de proxy do Lambda, a função `GetStartedLambdaIntegration` do Lambda para a integração personalizada do Lambda recebe apenas a entrada do corpo da solicitação de integração da API do API Gateway. A função pode retornar uma saída de qualquer objeto JSON, uma string, um número, um Booleano ou até mesmo um blob binário. Em contrapartida, a função do Lambda para a integração de proxy do Lambda pode aceitar a entrada de quaisquer dados da solicitação, mas deve retornar uma saída de determinado objeto JSON. A função `GetStartedLambdaIntegration` para a integração personalizada do Lambda pode ter os parâmetros de solicitação de API como entrada, desde que o API Gateway mapeie os parâmetros de solicitação de API necessários para o corpo da solicitação de integração antes de encaminhar a solicitação do cliente ao backend. Para que isso aconteça, o desenvolvedor da API deve criar um modelo de mapeamento e configurá-lo no método de API ao criar a API.
Agora, crie a função do Lambda `GetStartedLambdaIntegration`.
**Como criar a função do Lambda `GetStartedLambdaIntegration` para integração personalizada do Lambda**
1. Abra o console do AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).
1. Execute um destes procedimentos:
+ Se a página de boas-vindas for exibida, escolha **Get Started Now (Começar a usar agora)** e **Create function (Criar função)**.
+ Se a página da lista **Lambda > Functions (Lambda > Funções)** for exibida, escolha **Create function (Criar função)**.
1. Escolha **Author from scratch** (Criar do zero).
1. Na tela **Author from scratch (Criar do zero)**, faça o seguinte:
1. Em **Name (Nome)**, insira **GetStartedLambdaIntegration** como o nome da função do Lambda.
1. Em **Tempo de execução**, escolha o último runtime **Node.js** ou **Python** compatível.
1. Em **Arquitetura**, mantenha a configuração padrão.
1. Em **Permissions** (Permissões), expanda **Change default execution role** (Alterar função de execução padrão). Na lista suspensa **Perfil de execução**, escolha **Criar perfil com base em modelos de política da AWS**.
1. Para **Role name (Nome da função)**, insira um nome para sua função (por exemplo, **GetStartedLambdaIntegrationRole**).
1. Para **Policy templates (Modelos de política)**, escolha **Simple microservice permissions (Permissões de microsserviço simples)**.
1. Escolha **Create function** (Criar função).
1. No painel **Configure function (Configurar função)**, em **Function code (Código de função)** faça o seguinte:
1. Copie o código da função do Lambda listado no início desta seção e cole-o no editor de código em linha.
1. Deixe as opções padrão para todos os outros campos nesta seção.
1. Escolha **Deploy** (Implantar).
1. Para testar a função recém-criada, escolha a guia **Teste**.
1. Em **Nome do evento**, insira **HelloWorldTest**.
1. Para **JSON do evento**, substitua o código padrão pelo seguinte.
```
{
"name": "Jonny",
"city": "Seattle",
"time": "morning",
"day": "Wednesday"
}
```
1. Escolha **Test (Testar)** para invocar a função. A seção **Execution result: succeeded (Resultada da execução: bem-sucedida)** é exibida. Expanda **Detalhes** veja a saída a seguir.
```
{
"greeting": "Good morning, Jonny of Seattle. Happy Wednesday!"
}
```
A saída também é gravada no CloudWatch Logs.
Como exercício extra, você pode usar o console do IAM para visualizar a função do IAM (`GetStartedLambdaIntegrationRole`) criada como parte da criação da função do Lambda. Há duas políticas em linha anexadas à esta função do IAM. Uma estipula as permissões mais básicas para execução do Lambda. Ela permite chamar o `CreateLogGroup` do CloudWatch para quaisquer recursos do CloudWatch de sua conta na região onde a função do Lambda for criada. Essa política também permite a criação de streams e eventos de registro em log do CloudWatch para a função do Lambda `GetStartedLambdaIntegration`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:CreateLogGroup",
"Resource": "arn:aws:logs:us-east-1:111111111111:*"
},
{
"Effect": "Allow",
"Action": [
"logs:CreateLogStream",
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111111111111:log-group:/aws/lambda/GetStartedLambdaIntegration:*"
]
}
]
}
```
------
O outro documento de política se aplica à invocação de outro serviço da AWS que não é usado neste exemplo. Você pode ignorá-lo por enquanto.
Associada à função do IAM, há uma entidade confiável, que é `lambda.amazonaws.com`. Esta é a relação de confiança:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
A combinação dessa relação de confiança e da política em linha possibilita que a função do Lambda invoque uma função `console.log()` para registro de eventos no CloudWatch Logs.
## Criar uma API com integração não proxy do Lambda
Com a função do Lambda (`GetStartedLambdaIntegration`) criada e testada, você está pronto para expor a função por meio de uma API do API Gateway. Para fins de ilustração, a função do Lambda está exposta com um método HTTP genérico. Usamos o corpo de solicitação, uma variável do caminho URL, uma string de consulta e um cabeçalho para receber os dados de entrada necessários do cliente. Ativamos o validador de solicitações do API Gateway para a API a fim de garantir que todos os dados necessários sejam definidos e especificados apropriadamente. Configuramos um modelo para mapeamento para o API Gateway para transformar os dados de solicitação fornecidos pelo cliente no formato válido, conforme exigido pela função de backend do Lambda.
**Como criar uma API com uma integração não proxy do Lambda**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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. Em **API name (Nome da API)**, insira **LambdaNonProxyAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
Depois de criar uma API, você criará um recurso **/\$1city\$1**. Este é um exemplo de recurso com uma variável de caminho que recebe uma entrada do cliente. Posteriormente, você vai associar essa variável de caminho à entrada da função do Lambda usando um modelo de mapeamento.
**Para criar um recurso**
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1city\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Depois de criar um recurso **/\$1city\$1**, você criará um método `ANY`. O verbo HTTP `ANY` é um espaço reservado para um método HTTP válido que um cliente envia na ocasião da execução. Este exemplo mostra que o método `ANY` pode ser usado para integração personalizada do Lambda assim como para integração de proxy do Lambda.
**Como criar um método `ANY`**
1. Selecione o recurso **/\$1city\$1** e, depois, **Criar método**.
1. Em **Tipo de método**, selecione **ANY**.
1. Em **Tipo de integração**, selecione **Função do Lambda**.
1. Mantenha a opção **Integração do proxy do Lambda** desativada.
1. Em **Função do Lambda**, selecione a Região da AWS onde você criou a função do Lambda e, depois, insira o nome da função.
1. Escolha **Configurações de solicitação de método**.
Agora, ative um validador de solicitações para uma variável de caminho de URL, um parâmetro de string de consulta e um cabeçalho a fim de garantir que todos os dados necessários sejam definidos. Neste exemplo, você vai criar um parâmetro de string de consulta `time` e um cabeçalho `day`.
1. Em **Validador de solicitação**, selecione **Validar parâmetros de string de consulta e cabeçalhos**.
1. Selecione **Parâmetros de string de consulta de URL** e faça o seguinte:
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, digite **time**.
1. Ative a opção **Obrigatório**.
1. Mantenha **Armazenamento em cache** desativado.
1. Selecione **Cabeçalhos de solicitação HTTP** e faça o seguinte:
1. Escolha **Add header** (Adicionar cabeçalho).
1. Em **Nome**, digite **day**.
1. Ative a opção **Obrigatório**.
1. Mantenha **Armazenamento em cache** desativado.
1. Escolha **Criar método**.
Depois de ativar um validador de solicitações, você vai configurar a solicitação de integração do método `ANY` adicionando um modelo de mapeamento de corpo para transformar a solicitação recebida em uma carga útil do JSON, conforme exigido pela função do Lambda de back-end.
**Como configurar a solicitação de integração**
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**.
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 código:
```
#set($inputRoot = $input.path('$'))
{
"city": "$input.params('city')",
"time": "$input.params('time')",
"day": "$input.params('day')",
"name": "$inputRoot.callerName"
}
```
1. Escolha **Salvar**.
## Testar a chamada do método de API
O console do API Gateway fornece uma instalação de testes para que você teste a invocação à API antes que ela seja implantada. Você pode usar o recurso de teste do console para testar a API enviando a seguinte solicitação:
```
POST /Seattle?time=morning
day:Wednesday
{
"callerName": "John"
}
```
Nesta solicitação de teste, você definirá `ANY` como `POST`, definirá `{city}` como `Seattle`, atribuirá `Wednesday` como o valor de cabeçalho `day` e atribuirá `"John"` como o valor `callerName`.
**Como testar o método `ANY`**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Tipo de método**, selecione `POST`.
1. Em **Caminho**, em **cidade**, insira **Seattle**.
1. Em **Strings de consulta**, digite **time=morning**.
1. Em **Cabeçalhos**, insira **day:Wednesday**.
1. Em **Corpo da solicitação**, insira **\$1 "callerName": "John" \$1**.
1. Escolha **Test** (Testar).
Verifique se a carga de resposta retornada é como se segue:
```
{
"greeting": "Good morning, John of Seattle. Happy Wednesday!"
}
```
Também é possível visualizar os logs para examinar como o API Gateway processa a solicitação e a resposta.
```
Execution log for request test-request
Thu Aug 31 01:07:25 UTC 2017 : Starting execution for request: test-invoke-request
Thu Aug 31 01:07:25 UTC 2017 : HTTP Method: POST, Resource Path: /Seattle
Thu Aug 31 01:07:25 UTC 2017 : Method request path: {city=Seattle}
Thu Aug 31 01:07:25 UTC 2017 : Method request query string: {time=morning}
Thu Aug 31 01:07:25 UTC 2017 : Method request headers: {day=Wednesday}
Thu Aug 31 01:07:25 UTC 2017 : Method request body before transformations: { "callerName": "John" }
Thu Aug 31 01:07:25 UTC 2017 : Request validation succeeded for content type application/json
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request URI: https://lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:GetStartedLambdaIntegration/invocations
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request headers: {x-amzn-lambda-integration-tag=test-request, Authorization=****************************************************************************************************************************************************************************************************************************************************************************************************************************************338c72, X-Amz-Date=20170831T010725Z, x-amzn-apigateway-api-id=beags1mnid, X-Amz-Source-Arn=arn:aws:execute-api:us-west-2:123456789012:beags1mnid/null/POST/{city}, Accept=application/json, User-Agent=AmazonAPIGateway_beags1mnid, X-Amz-Security-Token=FQoDYXdzELL//////////wEaDMHGzEdEOT/VvGhabiK3AzgKrJw+3zLqJZG4PhOq12K6W21+QotY2rrZyOzqhLoiuRg3CAYNQ2eqgL5D54+63ey9bIdtwHGoyBdq8ecWxJK/YUnT2Rau0L9HCG5p7FC05h3IvwlFfvcidQNXeYvsKJTLXI05/yEnY3ttIAnpNYLOezD9Es8rBfyruHfJfOqextKlsC8DymCcqlGkig8qLKcZ0hWJWVwiPJiFgL7laabXs++ZhCa4hdZo4iqlG729DE4gaV1mJVdoAagIUwLMo+y4NxFDu0r7I0/EO5nYcCrppGVVBYiGk7H4T6sXuhTkbNNqVmXtV3ch5bOlh7 [TRUNCATED]
Thu Aug 31 01:07:25 UTC 2017 : Endpoint request body after transformations: {
"city": "Seattle",
"time": "morning",
"day": "Wednesday",
"name" : "John"
}
Thu Aug 31 01:07:25 UTC 2017 : Sending request to https://lambda.us-west-2.amazonaws.com/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:GetStartedLambdaIntegration/invocations
Thu Aug 31 01:07:25 UTC 2017 : Received response. Integration latency: 328 ms
Thu Aug 31 01:07:25 UTC 2017 : Endpoint response body before transformations: {"greeting":"Good morning, John of Seattle. Happy Wednesday!"}
Thu Aug 31 01:07:25 UTC 2017 : Endpoint response headers: {x-amzn-Remapped-Content-Length=0, x-amzn-RequestId=c0475a28-8de8-11e7-8d3f-4183da788f0f, Connection=keep-alive, Content-Length=62, Date=Thu, 31 Aug 2017 01:07:25 GMT, X-Amzn-Trace-Id=root=1-59a7614d-373151b01b0713127e646635;sampled=0, Content-Type=application/json}
Thu Aug 31 01:07:25 UTC 2017 : Method response body after transformations: {"greeting":"Good morning, John of Seattle. Happy Wednesday!"}
Thu Aug 31 01:07:25 UTC 2017 : Method response headers: {X-Amzn-Trace-Id=sampled=0;root=1-59a7614d-373151b01b0713127e646635, Content-Type=application/json}
Thu Aug 31 01:07:25 UTC 2017 : Successfully completed execution
Thu Aug 31 01:07:25 UTC 2017 : Method completed with status: 200
```
Os logs mostram a solicitação recebida antes do mapeamento e a solicitação de integração após o mapeamento. Quando um teste falha, os logs são úteis para avaliar se a entrada original está correta ou se o modelo de mapeamento funciona corretamente.
## Implantar a API
A invocação de teste é uma simulação e tem limitações. Por exemplo, ela ignora qualquer mecanismo de autorização promulgado na API. Para testar a execução da API em tempo real, você deve implantar a API primeiro. Para implantar uma API, você cria um estágio para criar um snapshot da API naquele momento. O nome do estágio também define o caminho base após o nome de host padrão da API. O recurso raiz da API é anexado após o nome do estágio. Quando você modifica a API, deve reimplantá-la em um estágio novo ou existente antes que as alterações entrem em vigor.
**Para implantar a API em um estágio**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **test**.
**nota**
A entrada deve ser texto codificado UTF-8 (ou seja, não localizado).
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API. O padrão geral do URL básico da API é `https://api-id.region.amazonaws.com/stageName`. Por exemplo, o URL básico da API (`beags1mnid`) criada na região `us-west-2` e implantada no estágio `test` é `https://beags1mnid.execute-api.us-west-2.amazonaws.com/test`.
## Testar a API em uma etapa de implantação
Há várias maneiras para testar uma API implantada. Para solicitações GET usando apenas variáveis de caminho do URL ou parâmetros de strings de consulta, é possível digitar o URL de recurso da API em um navegador. Para outros métodos, é necessário usar utilitários de teste de API REST mais avançados, como o [POSTMAN](https://www.postman.com/) ou o [cURL](https://curl.se/).
**Para testar a API usando cURL**
1. Abra uma janela de terminal em seu computador local conectado à Internet.
1. Para testar `POST /Seattle?time=evening`:
Copie o seguinte comando cURL e cole-o na janela do terminal.
```
curl -v -X POST \
'https://beags1mnid.execute-api.us-west-2.amazonaws.com/test/Seattle?time=evening' \
-H 'content-type: application/json' \
-H 'day: Thursday' \
-H 'x-amz-docs-region: us-west-2' \
-d '{
"callerName": "John"
}'
```
Você receberá uma resposta bem-sucedida com a seguinte carga:
```
{"greeting":"Good evening, John of Seattle. Happy Thursday!"}
```
Se você alterar `POST` para `PUT` nesta solicitação de método, obterá a mesma resposta.
## Limpar
Se você não precisar mais das funções do Lambda criadas para esta demonstração, poderá excluí-las agora. Você também pode excluir os recursos do IAM que o acompanham.
**Atenção**
Se você pretende completar as outras demonstrações desta série, não exclua a função de execução Lambda ou a função de invocação do Lambda. Se você excluir uma função do Lambda da qual as suas APIs dependem, essas APIs 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, esta última deixará de funcionar, juntamente com as APIs que dependem dessa função. 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.
**Como excluir a função do Lambda**
1. Faça login no Console de gerenciamento da AWS e abra o console AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).
1. Na lista de funções, escolha **GetStartedLambdaIntegration**, **Ações** e **Excluir função**. 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/](https://console.aws.amazon.com/iam/).
1. Em **Details (Detalhes)**, escolha **Roles (Funções)**.
1. Na lista de funções, escolha **GetStartedLambdaIntegrationRole**, **Ações da função** e **Excluir função**. Siga as etapas no console para excluir o perfil.
# Tutorial: Crie uma API REST com uma integração de proxy do Lambda entre contas
Agora você pode usar a função do AWS Lambda de uma conta da AWS diferente como seu backend de integração da API. Cada conta pode estar em qualquer região onde o Amazon API Gateway está disponível. Isso facilita o gerenciamento centralizado e o compartilhamento das funções do Lambda de backend em várias APIs.
Nesta seção, mostramos como configurar a integração de proxy do Lambda entre contas usando o console do Amazon API Gateway.
## Criar uma API para integração do Lambda entre contas do API Gateway
**Como criar uma API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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. Em **API name (Nome da API)**, insira **CrossAccountLambdaAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
## Criar a função de integração do Lambda em outra conta
Agora você criará uma função do Lambda em uma conta diferente daquela em que criou a API demonstrativa.
**Criar uma função do Lambda em outra conta**
1. Faça login no console do Lambda usando uma conta diferente daquela em que você criou sua API do API Gateway.
1. Escolha **Create function** (Criar função).
1. Escolha **Author from scratch** (Criar do zero).
1. Em **Author from scratch (Criar do zero)**, faça o seguinte:
1. Em **Function name (Nome da função)**, insira um nome.
1. Na lista suspensa **Runtime (Tempo de execução)**, escolha um tempo de execução Node.js compatível.
1. Em **Arquitetura**, mantenha a configuração padrão.
1. Em **Permissions (Permissões)**, expanda **Choose or create an execution role (Escolher ou criar uma função de execução)**. É possível criar uma função ou escolher uma função existente.
1. Escolha **Create function (Criar função)** para continuar.
1. Role para baixo, até o painel **Function code (Código da função)**.
1. Insira a implementação da função Node.js de [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md).
1. Escolha **Deploy** (Implantar).
1. Anote o ARN completo da sua função (no canto superior direito do painel de funções do Lambda). Você precisará dele ao criar a integração do Lambda entre contas.
## Configurar a integração do Lambda entre contas
Depois de ter uma função de integração do Lambda em uma conta diferente, você poderá usar o console do API Gateway para adicioná-la à sua API na sua primeira conta.
**nota**
Se você estiver configurando um autorizador entre regiões e entre contas, o `sourceArn` que é adicionado à função de destino deve usar a região da função, e não a região da API.
Depois de criar uma API, você criará um recurso. Normalmente, os recursos da API são organizados em uma árvore de recursos, de acordo com a lógica do aplicativo. Neste exemplo, você criará um recurso **/helloworld**.
**Para criar um recurso**
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **helloworld**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Depois de criar um recurso, você criará um método `GET`. Você vai integrar o método `GET` a uma função do Lambda em outra conta.
**Como criar um método `GET`**
1. Selecione o recurso **/helloworld** e, depois, **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Função do Lambda**.
1. Ative **Integração de proxy do Lambda**.
1. Em **Função do Lambda**, insira o ARN completo da função do Lambda na Etapa 1.
No console do Lambda, você pode encontrar o ARN da sua função no canto superior direito da janela.
1. Ao inserir o ARN, uma string de comando `aws lambda add-permission` é exibida. Esta política concederá acesso da sua primeira conta à função do Lambda da segunda conta. Copie e cole a string de comando `aws lambda add-permission` em uma janela da AWS CLI configurada para a segunda conta.
1. Escolha **Criar método**.
É possível ver a política atualizada da função no console do Lambda.
**(Opcional) Como ver a política atualizada**
1. Faça login no Console de gerenciamento da AWS e abra o console do AWS Lambda em [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/).
1. Selecione a função do Lambda.
1. Escolha **Permissions (Permissões)**.
É necessário ver uma política `Allow` com uma cláusula `Condition` na qual o `AWS:SourceArn` é o ARN para o método `GET` da sua API.
# Tutorial: Criar uma API REST importando um exemplo
Você pode usar o console do Amazon API Gateway para criar e testar uma API REST simples com a integração HTTP de um site PetStore. A definição de API é pré-configurada como um arquivo OpenAPI 2.0. Depois de carregar a definição da API no API Gateway, é possível usar o console do API Gateway para examinar a estrutura básica da API ou simplesmente implantar e testar a API.
A API PetStore de exemplo oferece suporte aos métodos a seguir para que um cliente acesse o site de backend HTTP de `http://petstore-demo-endpoint.execute-api.com/petstore/pets`.
**nota**
Esse tutorial usa um endpoint HTTP como exemplo. Ao criar suas próprias APIs, recomendamos que você use endpoints HTTPS para as integrações HTTP.
+ `GET /`: para acesso de leitura do recurso raiz da API que não está integrado a qualquer endpoint de backend. O API Gateway responde com uma visão geral do site PetStore. Este é um exemplo do tipo de integração `MOCK`.
+ `GET /pets`: para acesso de leitura ao recurso `/pets` da API que está integrado ao recurso de backend `/pets` de nome idêntico. O backend retorna uma página de animais de estimação disponíveis na PetStore. Este é um exemplo do tipo de integração `HTTP`. O URL do endpoint de integração é `http://petstore-demo-endpoint.execute-api.com/petstore/pets`.
+ `POST /pets`: para acesso de gravação ao recurso `/pets` da API que está integrado ao recurso de backend `/petstore/pets`. Depois de receber uma solicitação correta, o backend adiciona o animal de estimação especificado à PetStore e retorna o resultado para o autor da chamada. A integração também é `HTTP`.
+ `GET /pets/{petId}`: para acesso de leitura a um animal de estimação conforme identificado por um valor `petId` especificado como uma variável de caminho do URL da solicitação recebida. Este método também tem o tipo de integração `HTTP`. O backend retorna o animal de estimação especificado encontrado na PetStore. O URL do endpoint HTTP de backend é `http://petstore-demo-endpoint.execute-api.com/petstore/pets/n`, onde `n` é um número inteiro como o identificador do animal de estimação consultado.
A API oferece suporte ao acesso de CORS através dos métodos `OPTIONS` do tipo de integração `MOCK`. O API Gateway retorna os cabeçalhos necessários para suporte ao acesso de CORS.
O procedimento a seguir descreve as etapas para criar e testar uma API a partir de um exemplo usando o console do API Gateway.
**Para importar, criar e testar a API de exemplo**
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Execute um destes procedimentos:
+ Para criar sua primeira API, em **API REST**, escolha **Criar**.
+ Se você criou uma API antes, escolha **Criar API** e, depois, escolha **Criar** para **API REST**.
1. Em **Criar API REST**, selecione **API de exemplo** e escolha **Importar** para criar a API de exemplo.
![\[Exemplo de API REST no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-new-console.png)
É possível percorrer a definição do OpenAPI para conhecer os detalhes dessa API de exemplo antes de selecionar **Importar**.
1. No painel de navegação principal, selecione **Recursos**. A API recém-criada é mostrada da seguinte forma:
![\[O exemplo de API depois de importá-lo no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-result-new-console.png)
O painel **Resources (Recursos)** mostra a estrutura da API criada como uma árvore de nós. Os métodos de API definidos em cada recurso são as extremidades da árvore. Quando um recurso é selecionado, todos os respectivos métodos são listados na tabela **Métodos** à direita. Com cada método, são exibidos o tipo de método, o tipo de integração, o tipo de autorização e o requisito da chave de API.
1. Para visualizar os detalhes de um método, modificar sua configuração ou testar a invocação do método, escolha o nome do método na lista de métodos ou na árvore de recursos. Aqui, escolhemos o método `POST /pets` como uma ilustração:
![\[O método POST /pets para o exemplo de API no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-post-method-execution-new-console.png)
O painel **Execução de método** resultante apresenta uma visão lógica da estrutura e dos comportamentos do método escolhido (`POST /pets`).
A **Solicitação de método** e a **Resposta de método** representam a interface da API com o front-end, ao passo que a **Solicitação de integração** e a **Resposta de integração** representam a interface da API com o back-end.
Um cliente usa a API para acessar um recurso de back-end por meio da **Solicitação de método**. Se necessário, o API Gateway converte a solicitação do cliente no formato aceitável para o back-end em **Solicitação de integração** antes de encaminhá-la ao back-end. A solicitação transformada é conhecida como a solicitação de integração. De maneira semelhante, o back-end retorna a resposta ao API Gateway em **Resposta de integração**. Depois, o API Gateway a roteia para **Method Response (Resposta de método)** antes de enviá-la ao cliente. Novamente, se necessário, o API Gateway poderá mapear os dados da resposta de backend para um formulário esperado pelo cliente.
Para o método `POST` em um recurso da API, a carga de solicitação de método poderá ser passada para a solicitação de integração sem modificação, se a carga de solicitação de método estiver no mesmo formato que a carga de solicitação de integração.
A solicitação do método `GET /` usa o tipo de integração `MOCK` e não está vinculada a nenhum endpoint de backend real. A **Resposta de integração** correspondente é configurada para gerar uma página HTML estática. Quando o método é chamado, o API Gateway simplesmente aceita a solicitação e retorna imediatamente a resposta de integração configurada para o cliente como **Resposta de método**. Você pode usar a integração fictícia para testar uma API sem exigir um endpoint de backend. Você também pode usá-la para atender a uma resposta local, gerada a partir de um modelo de mapeamento de corpo de resposta.
Como desenvolvedor de APIs, você pode controlar os comportamentos das interações de front-end da sua API, configurando a solicitação do método e uma resposta do método. Você controla os comportamentos das interações de backend da sua API configurando a solicitação de integração e a resposta da integração. Isso envolve mapeamentos de dados entre um método e sua integração correspondente. Por enquanto, nos concentraremos em testar a API para fornecer uma experiência de usuário de ponta a ponta.
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Por exemplo, para testar o método `POST /pets`, digite a carga útil **\$1"type": "dog","price": 249.99\$1** a seguir no **Corpo da solicitação** e escolha **Testar**.
![\[Teste o método POST no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-post-method-test-new-console.png)
A entrada especifica os atributos do animal de estimação que queremos adicionar à lista de animais de estimação no site PetStore.
1. Os resultados são exibidos da seguinte forma:
![\[O resultado do teste do método POST no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-post-method-test-result-new-console.png)
A entrada **Log** da saída mostra as alterações de estado da solicitação de método para a solicitação de integração e da resposta de integração para a resposta de método. Isso pode ser útil para solucionar problemas com erros de mapeamento que causam a falha da solicitação. Neste exemplo, nenhum mapeamento é aplicado: a carga da solicitação do método é passada por meio de uma solicitação de integração para o backend e, de maneira semelhante, a resposta do backend é passada por meio da resposta da integração para a resposta do método.
Para testar a API usando um cliente diferente do recurso test-invoke-request do API Gateway, é necessário primeiro implantar a API em um estágio.
1. Para implantar o exemplo de API, selecione **Implantar API**.
![\[Use o botão de implantação para implantar a API, para que os chamadores de API possam invocá-la.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-by-importing-example-deploy-api-new-console.png)
1. Em **Estágio**, selecione **Novo estágio** e insira **test**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
1. No painel **Estágios** resultante, em **Detalhes do estágio**, **Invocar URL** exibe o URL para invocar a solicitação de método `GET /` da API.
![\[Após a criação da API REST, o console mostra o URL de chamada da API.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png)
1. Escolha o ícone de cópia para copiar o URL de invocação da API e insira o URL de invocação da sua API em um navegador da web. Uma resposta bem-sucedida retornará o resultado, gerada a partir do modelo de mapeamento na resposta de integração.
1. No painel de navegação **Stages** (Estágios), expanda o estágio **test** (teste), selecione **GET** em `/pets/{petId}` e, em seguida, copie o valor de **Invoke URL** (Invocar URL) de `https://api-id.execute-api.region.amazonaws.com/test/pets/{petId}`. `{petId}` representa uma variável de caminho.
Cole o valor de **Invoke URL (Invocar URL)** (obtido na etapa anterior) na barra de endereços de um navegador, substituindo `{petId}` por, por exemplo, `1` e pressione Enter para enviar a solicitação. Uma resposta 200 OK será retornada com a seguinte carga JSON:
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
É possível invocar o método de API conforme mostrado porque seu tipo **Authorization (Autorização)** está definido como `NONE`. Se a autorização do `AWS_IAM` fosse usada, você assinaria a solicitação usando os protocolos [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) (SigV4) ou [Signature Version 4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works) (SigV4a). Para obter um exemplo dessa solicitação, consulte [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md).
# Escolher um tutorial de integração HTTP
Para criar uma API com integração HTTP, você pode usar uma integração de proxy HTTP ou uma integração HTTP personalizada.
Em uma integração de proxy HTTP, só é necessário definir o método HTTP e o URI de endpoint HTTP de acordo com os requisitos de back-end. Recomendamos o uso da integração de proxy HTTP sempre que possível para aproveitar a configuração simplificada da API.
Talvez você queira usar uma integração HTTP personalizada se precisar transformar os dados de solicitação do cliente para o back-end ou transformar os dados de resposta do back-end para o cliente.
**Topics**
+ [Tutorial: Crie uma API REST com uma integração de proxy de HTTP](api-gateway-create-api-as-simple-proxy-for-http.md)
+ [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md)
# Tutorial: Crie uma API REST com uma integração de proxy de HTTP
A integração de proxy HTTP é um mecanismo simples, eficiente e versátil para criar uma API que permite que um aplicativo web acesse vários recursos ou características do endpoint HTTP integrado, por exemplo, todo o site, com a configuração simplificada de um único método da API. Na integração de proxy HTTP, o API Gateway transmite a solicitação de método enviada pelo cliente para o backend. Os dados da solicitação que são transmitidos incluem os cabeçalhos da solicitação, parâmetros da string de consulta, variáveis do caminho do URL e carga. O endpoint HTTP do backend ou o servidor web analisará os dados da solicitação recebida para determinar a resposta que ele retorna. A integração de proxy HTTP faz com que o cliente e o backend interajam diretamente sem qualquer intervenção do API Gateway após a configuração do método da API, exceto problemas conhecidos, como caracteres incompatíveis, que estão listados em [Notas importantes do Amazon API Gateway](api-gateway-known-issues.md).
Com o recurso de proxy totalmente abrangente `{proxy+}`e o verbo global `ANY` para o método HTTP, é possível usar uma integração de proxy HTTP para criar uma API de um único método de API. O método expõe o conjunto completo de recursos HTTP de acesso público e operações de um site. Quando o servidor web de backend abre mais recursos para o acesso público, o cliente pode usar esses novos recursos com a mesma configuração de API. Para habilitar isso, o desenvolvedor do site deve comunicar claramente ao desenvolvedor cliente quais são os novos recursos e quais operações são aplicáveis a cada um deles.
Como uma rápida introdução, o tutorial a seguir demonstra a integração de proxy HTTP. No tutorial, criamos uma API usando o console do API Gateway para integração com o site PetStore por meio de um recurso de proxy genérico `{proxy+}` e criamos o espaço reservado do método HTTP de `ANY`.
**Topics**
+ [Criar uma API com integração de proxy HTTP usando o console do API Gateway](#api-gateway-create-api-as-simple-proxy-for-http-build)
+ [Testar uma API com a integração de proxy HTTP](#api-gateway-create-api-as-simple-proxy-for-http-test)
## Criar uma API com integração de proxy HTTP usando o console do API Gateway
O procedimento a seguir descreve as etapas para criar e testar uma API com um recurso de proxy para um backend HTTP usando o console do API Gateway. O backend HTTP é o site `PetStore` (`http://petstore-demo-endpoint.execute-api.com/petstore/pets`) de [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md), no qual capturas de tela são usadas como auxílios visuais para ilustrar os elementos da IU do API Gateway. Se você ainda não sabe usar o console do API Gateway para criar uma API, talvez precise consultar essa seção primeiro.
**Como criar uma API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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. Em **API name (Nome da API)**, insira **HTTPProxyAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
Nesta etapa, você vai criar um caminho de recurso de proxy de `{proxy+}`. Esse é o espaço reservado de qualquer um dos endpoints de back-end em `http://petstore-demo-endpoint.execute-api.com/`. Por exemplo, ele pode ser `petstore`, `petstore/pets` e `petstore/pets/{petId}`. O API Gateway cria o método `ANY` quando você cria o recurso `{proxy+}` e serve como um espaço reservado para qualquer um dos verbos HTTP compatíveis em runtime.
**Como criar um recurso **/\$1proxy\$1\$1****
1. Selecione a API.
1. No painel de navegação principal, selecione **Recursos**.
1. Selecione **Criar recurso**.
1. Ative **Recurso proxy**.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1proxy\$1\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
![\[Crie um recurso filho.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-simple-proxy-create-proxy-resource-new-console.png)
Nesta etapa, você vai integrar o método `ANY` a um endpoint HTTP de back-end usando uma integração de proxy. Na integração de proxy, o API Gateway transmite a solicitação de método enviada pelo cliente ao back-end, sem intervenção do API Gateway.
**Como criar um método `ANY`**
1. Selecione o recurso**/\$1proxy\$1\$1**.
1. Selecione o método **ANY**.
1. Sob o símbolo de aviso, selecione **Editar integração**. Não é possível implantar uma API que tenha um método sem uma integração.
1. Em **Tipo de integração**, selecione **HTTP**.
1. Ative **Integração de proxy HTTP**.
1. Em **Método HTTP**, selecione **ANY**.
1. Em **URL do endpoint**, insira **http://petstore-demo-endpoint.execute-api.com/\$1proxy\$1**.
1. Escolha **Salvar**.
## Testar uma API com a integração de proxy HTTP
O êxito de determinada solicitação do cliente depende do seguinte:
+ Se o backend disponibilizou o endpoint de backend correspondente e, se esse for o caso, se as permissões de acesso necessárias foram concedidas.
+ Se o cliente forneceu a entrada correta.
Por exemplo, a API da PetStore usada aqui não expõe o recurso `/petstore`. Dessa forma, você obtém uma resposta `404 Resource Not Found` contendo a mensagem de erro `Cannot GET /petstore`.
Além disso, o cliente deve ser capaz de lidar com o formato de saída do backend para analisar o resultado corretamente. O API Gateway não se interpõe para facilitar as interações entre o cliente e o backend.
**Para testar uma API integrada ao site PetStore usando a integração de proxy HTTP por meio do recurso de proxy**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Tipo de método**, selecione `GET`.
1. Em **Caminho**, em **proxy**, insira **petstore/pets**.
1. Em **Strings de consulta**, digite **type=fish**.
1. Escolha **Testar**.
![\[Use o recurso de teste para testar um método.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-simple-proxy-petstore-call-proxy-resource-new-console.png)
Como o site de backend oferece suporte para a solicitação `GET /petstore/pets?type=fish`, ele retorna uma resposta bem-sucedida semelhante à seguinte:
```
[
{
"id": 1,
"type": "fish",
"price": 249.99
},
{
"id": 2,
"type": "fish",
"price": 124.99
},
{
"id": 3,
"type": "fish",
"price": 0.99
}
]
```
Se você tentar chamar `GET /petstore`, receberá uma resposta `404` com uma mensagem de erro `Cannot GET /petstore`. Isso acontece porque o backend não oferece suporte à operação especificada. Se você chamar `GET /petstore/pets/1`, receberá uma resposta `200 OK` com a carga a seguir, pois a solicitação recebe suporte do site PetStore.
```
{
"id": 1,
"type": "dog",
"price": 249.99
}
```
Também é possível usar um navegador para testar a API. Implante a API e associe-a a um estágio para criar o URL de invocação da API.
**Para implantar sua API**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **test**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
Agora, os clientes podem chamar sua API.
**Como invocar a API**
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 a API.
1. No painel de navegação principal, selecione **Estágio**.
1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API.
Copie o URL de invocação da API em um navegador web.
O URL deve ser semelhante a `https://abcdef123.execute-api.us-east-2.amazonaws.com/test/petstore/pets?type=fish`.
Seu navegador envia uma solicitação `GET` à API.
1. O resultado deve ser o mesmo que o gerado ao usar **Testar** no console do API Gateway.
# Tutorial: Crie uma API REST com uma integração de não proxy de HTTP
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.
**Topics**
+ [Criar uma API com integração personalizada HTTP](#api-gateway-create-resource-and-methods)
+ [(Opcional) Associar parâmetros de solicitação](#api-gateway-create-resources-and-methods-next-steps)
## 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.
Nesta etapa, você cria uma API vazia. Nas etapas a seguir, você vai criar recursos e métodos para conectar a API ao endpoint `http://petstore-demo-endpoint.execute-api.com/petstore/pets` usando uma integração HTTP sem proxy.
**Como criar uma API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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. Em **API name (Nome da API)**, insira **HTTPNonProxyAPI**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
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.
**Como criar um recurso /pets**
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **pets**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Nesta etapa, você vai criar um método `GET` para o recurso **/pets**. O método `GET` é integrado ao site `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. São outras opções para um método de API:
+ **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.
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.
**Como criar um método `GET` no recurso **/pets****
1. Selecione o recurso **/pets**.
1. Escolha **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Integração HTTP**.
1. Mantenha a opção **Integração do proxy HTTP** desativada.
1. Em **Método HTTP**, selecione **GET**.
1. Em **URL do endpoint**, insira **http://petstore-demo-endpoint.execute-api.com/petstore/pets**.
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 página específica.
1. Em **Manuseio de conteúdo**, selecione **Passagem**.
1. Selecione **Parâmetros de string de consulta de URL**.
Ele usa os parâmetros de string de consulta `type` e `page` para aceitar uma entrada. Adicione os parâmetros de string de consulta à solicitação de método e mapeie-os para os parâmetros de string de consulta correspondentes da solicitação de integração.
1. Para adicionar parâmetros de string de consulta, faça o seguinte:
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, insira **type**.
1. Mantenha **Obrigatório** e **Armazenamento em cache** desativados.
Repita as etapas anteriores para criar uma string de consulta adicional com o nome **page**.
1. Escolha **Criar método**.
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 associar parâmetros de entrada à solicitação de integração**
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de string de consulta de URL** e faça o seguinte:
1. Selecione **Adicionar parâmetro de string de consulta**.
1. Em **Nome**, digite **type**.
1. Em **Mapeado de**, insira **method.request.querystring.type**.
1. Mantenha **Armazenamento em cache** desativado.
1. Selecione **Adicionar parâmetro de string de consulta**.
1. Em **Nome**, digite **page**.
1. Em **Mapeado de**, insira **method.request.querystring.page**.
1. Mantenha **Armazenamento em cache** desativado.
1. Escolha **Salvar**.
**Como testar a API**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Strings de consulta**, digite **type=Dog&page=2**.
1. Escolha **Testar**.
O resultado é semelhante ao seguinte:
![\[Testar/invocar o resultado do método GET on pets\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-create-api-step-by-step-test-invoke-get-on-pets-result-new-console.png)
Agora que o teste foi bem-sucedido, podemos implantar a API para torná-la disponível publicamente.
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **Prod**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
1. (Opcional) Em **Detalhes do estágio**, para **Invocar URL**, é possível selecionar o ícone de cópia para copiar o URL de invocação da API. Você pode usá-lo com ferramentas, como [Postman](https://www.postman.com) e [cURL](https://curl.se/) para testar sua API.
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](https://aws.amazon.com/developer/tools/) 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.
## (Opcional) Associar parâmetros de solicitação
### Mapear parâmetros de solicitação para uma API do API Gateway
Este tutorial mostra como criar um parâmetro de caminho de `{petId}` na solicitação de método da API para especificar um ID de item, associá-lo ao parâmetro de caminho `{id}` no URL da solicitação de integração e enviar a solicitação ao endpoint HTTP.
**nota**
Se você digitar uma letra de tamanho incorreto, por exemplo, minúscula em vez de maiúscula, poderá causar erros mais adiante no processo.
#### Etapa 1: Criar recursos
Nesta etapa, você vai criar um recurso com um parâmetro de caminho \$1petId\$1.
**Como criar o recurso \$1petId\$1**
1. Selecione o recurso **/pets** e, depois, escolha **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Em **Caminho do recurso**, selecione**/pets**.
1. Em **Resource Name (Nome do recurso)**, insira **\$1petId\$1**.
Use as chaves (`{ }`) ao redor de `petId` para que **/pets/\$1petId\$1** seja exibido.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
#### Etapa 2: Criar e testar métodos
Nesta etapa, você vai criar um método `GET` com um parâmetro de caminho `{petId}`.
**Como configurar o método GET**
1. Selecione o recurso **/\$1petId\$1** e, depois, **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Integração HTTP**.
1. Mantenha a opção **Integração do proxy HTTP** desativada.
1. Em **Método HTTP**, selecione **GET**.
1. Em **URL do endpoint**, insira **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**.
1. Em **Manuseio de conteúdo**, selecione **Passagem**.
1. Mantenha o **Tempo limite padrão** ativado.
1. Escolha **Criar método**.
Agora você vai associar o parâmetro de caminho `{petId}` que você acabou de criar ao parâmetro de caminho `{id}` no URL do endpoint HTTP da solicitação de integração. O endpoint HTTP era **http://petstore-demo-endpoint.execute-api.com/petstore/pets/\$1id\$1**.
**Como associar o parâmetro de caminho `{petId}`**
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de caminho de URL**.
1. O API Gateway cria um parâmetro de caminho para a solicitação de integração chamado **petId**, mas ele não é válido para o URL do endpoint HTTP que você define como a integração de backend. O endpoint HTTP usa `{id}` como o parâmetro de caminho. Em **Nome**, exclua **petId** e insira **id**.
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`.
1. Escolha **Salvar**.
Agora teste o método.
**Como testar o método **
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Caminho** para **petId**, insira **4**.
1. Escolha **Test** (Testar).
Se bem-sucedido, o **Corpo da resposta** exibirá o seguinte:
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### 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. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Prod**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. 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 de navegação principal, selecione **Estágio**.
1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API.
A aparência será semelhante à seguinte:
```
https://my-api-id.execute-api.region-id.amazonaws.com/prod
```
1. Insira este URL na caixa de endereço da nova guia do navegador e anexe `/pets/4` ao URL antes de enviar a solicitação.
1. O navegador exibirá o seguinte:
```
{
"id": 4,
"type": "bird",
"price": 999.99
}
```
#### Próximas etapas
É possível personalizar ainda mais a API ativando a validação de solicitações, transformando dados ou criando respostas de gateway personalizadas.
Para examinar mais formas de personalizar a API, veja os seguintes tutoriais:
+ Para obter mais informações sobre a validação de solicitação, consulte [Configurar a validação básica de solicitações no API Gateway](api-gateway-request-validation-set-up.md).
+ Para obter informações sobre como transformar cargas úteis de solicitação e resposta, consulte [Tutorial: modificar a solicitação e a resposta de integração para integrações a serviços da AWS](set-up-data-transformations-in-api-gateway.md).
+ Para obter informações sobre como criar respostas de gateway personalizadas, consulte [Configurar uma resposta de gateway para uma API REST usando o console do API Gateway](set-up-gateway-response-using-the-console.md).
# Tutorial: Crie uma API REST com uma integração privada
Neste tutorial, você vai criar uma API REST que se conecte a um serviço do Amazon ECS executado em uma Amazon VPC. Clientes fora da sua Amazon VPC podem usar a API para acessar seu serviço do Amazon ECS.
Este tutorial leva aproximadamente uma hora para ser concluído. Primeiro, você usa um modelo do CloudFormation para criar um serviço da Amazon VPC e do Amazon ECS. Depois, você vai usar o console do API Gateway para criar um link da VPC V2. O link da VPC permite que o API Gateway acesse o serviço do Amazon ECS executado em sua Amazon VPC. Depois, você vai criar uma API REST que use o link da VPC V2 para se conectar ao seu serviço do Amazon ECS. Por fim, você testa a sua API.
Quando você invoca sua API REST, o API Gateway encaminha a solicitação para o serviço do Amazon ECS por meio do link da VPC V2 e, depois, exibe a resposta do serviço.
**nota**
Anteriormente, esse tutorial comportava APIs HTTP e agora só comporta APIs REST que utilizem o link da VPC V2.
![\[Visão geral da API REST criada neste tutorial.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/private-integration-rest.png)
Para concluir esse tutorial, você precisa de uma conta da AWS e de um usuário do AWS Identity and Access Management com acesso ao console. Para obter mais informações, consulte [Configurar para usar o API Gateway](setting-up.md).
**Topics**
+ [Etapa 1: Crie um serviço do Amazon ECS](#rest-api-private-integration-create-ecs-service)
+ [Etapa 2: Crie um link da VPC](#http-api-private-integration-vpc-link)
+ [Etapa 3: criar uma API REST](#http-api-private-integration-create-api)
+ [Etapa 4: Testar sua API](#rest-api-private-integration-test-api)
+ [Etapa 5: Implante sua API](#rest-api-private-integration-deploy-api)
+ [Etapa 6: chamar a API](#rest-api-private-integration-call)
+ [Etapa 7: limpar](#rest-api-private-integration-cleanup)
## Etapa 1: Crie um serviço do Amazon ECS
O Amazon ECS é um serviço de gerenciamento de contêineres que facilita a execução, a interrupção e o gerenciamento de contêineres do Docker em um cluster. Neste tutorial, você executa seu cluster em uma infraestrutura sem servidor gerenciada pelo Amazon ECS.
Baixe e descompacte [este modelo do CloudFormation](samples/rest-private-integration-tutorial.zip) que cria todas as dependências do serviço, incluindo uma Amazon VPC. Use o modelo para criar um serviço do Amazon ECS que usa um Application Load Balancer.
**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 **rest-api-private-integrations-tutorial** 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**.
CloudFormation provisiona o serviço ECS, que pode levar alguns minutos. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, você estará pronto para passar para a próxima etapa.
## Etapa 2: Crie um link da VPC
Um link da VPC permite que o API Gateway acesse recursos privados em uma Amazon VPC. Você deve usar um link da VPC para permitir que os clientes acessem seu serviço do Amazon ECS por meio da API REST.
**Para criar um link da VPC**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. No painel de navegação principal, escolha **Links da VPC** e selecione **Criar**.
Escolha o ícone do menu para se for necessário abrir o painel de navegação principal.
1. Em **Escolher versão do link de VPC**, selecione **Link da VPC V2**.
1. Em **Name (Nome)**, insira **private-integrations-tutorial**.
1. Em **VPC**, escolha a VPC criada na etapa 1. O nome deve começar com **RestApiStack**.
1. Para **Sub-redes**, selecione as duas sub-redes privadas em sua VPC. Os nomes delas terminam com `PrivateSubnet`.
1. Em **Grupos de segurança**, selecione o ID do grupo que começa com `private-integrations-tutorial` e tem a descrição de `RestApiStack/RestApiTutorialService/Service/SecurityGroup`.
1. Escolha **Criar**.
Depois de criar seu link da VPC V2, o API Gateway provisiona as interfaces de rede elásticas para acessar sua VPC. O processo pode levar alguns minutos. Enquanto isso, você pode criar sua API.
## Etapa 3: criar uma API REST
A API REST fornece um endpoint HTTP para o seu serviço do Amazon ECS.
**Como criar uma API REST**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Criar API**e, em seguida, para **API REST**, escolha **Criar**.
1. Em **Name (Nome)**, insira **private-integration-api**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Criar API**.
Depois de criar a API, você criará um método.
1. Selecione **Criar método** e proceda da seguinte maneira:
1. Em **Tipo de método**, selecione `GET`.
1. Em **Tipo de integração**, selecione **Link de VPC**.
1. Ative **Integração de proxy VPC**.
1. Em **Método HTTP**, selecione `GET`.
1. Em **Link de VPC**, escolha o link da VPC V2 que você criou na etapa anterior.
1. Em **Destino de integração**, insira o balanceador de carga criado com o modelo do CloudFormation na Etapa 1. Seu nome deve começar com **rest-**.
1. Em **URL do endpoint**, insira `http://private-integrations-tutorial.com`.
O URL é utilizado para definir o cabeçalho `Host` da solicitação de integração. Nesse caso, o cabeçalho do host é **private-integrations-tutorial**.
1. Escolha **Criar método**.
Com a integração de proxy, a API está pronta para o teste.
## Etapa 4: Testar sua API
Depois, teste a invocação do método de API.
**Para testar sua API**
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 a API.
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Escolha **Testar**.
Verifique se a resposta da sua API é uma mensagem de boas-vindas que informa que seu aplicativo está sendo executado no Amazon ECS.
## Etapa 5: Implante sua API
Depois, implante a API.
**Para implantar sua API**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **Prod**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
## Etapa 6: chamar a API
Depois de implantar a API, você pode chamá-la.
**Como chamar a API**
1. Insira o URL de invocação em um navegador da web.
O URL deve ser semelhante a `https://abcd123.execute-api.us-east-2.amazonaws.com/Prod`.
Seu navegador envia uma solicitação `GET` à API.
1. Verifique se a resposta da sua API é uma mensagem de boas-vindas que informa que seu aplicativo está sendo executado no Amazon ECS.
Se você vir a mensagem de boas-vindas, é sinal de que criou corretamente um serviço do Amazon ECS executado em uma Amazon VPC e utilizou uma API REST do API Gateway com um link da VPC V2 para acessar o serviço do Amazon ECS.
## Etapa 7: limpar
Para evitar custos desnecessários, exclua os recursos que você criou como parte desse tutorial. As etapas a seguir excluem o link da VPC V2, a pilha do CloudFormation e a API REST.
**Para excluir uma API REST**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Na página **APIs** , selecione uma API. Escolha **Ações**, escolha **Excluir** e, em seguida, confirme sua escolha.
**Para excluir um link da VPC**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Link da VPC**.
1. Selecione seu link da VPC, escolha **Excluir**e confirme sua escolha.
**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.
# Tutorial: Crie uma API REST com uma integração da AWS
Os tópicos [Tutorial: Crie uma API REST com uma integração de proxy do Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md) e [Tutorial: Crie uma API REST com uma integração de não proxy do Lambda](getting-started-lambda-non-proxy-integration.md) descrevem como criar uma API do API Gateway para expor a função do Lambda integrada. Além disso, é possível criar uma API do API Gateway para expor outros serviços da AWS, como Amazon SNS, Amazon S3, Amazon Kinesis e até mesmo o AWS Lambda. Isso é possível através da integração da `AWS`. A integração do Lambda ou a integração de proxy do Lambda é um caso especial, em que a invocação da função do Lambda é exposta por meio da API do API Gateway.
Todos os serviços da AWS são compatíveis com APIs dedicadas para exposição de seus recursos. No entanto, os protocolos de aplicativos ou interfaces de programação provavelmente diferem de serviço para serviço. Uma API do API Gateway com integração da `AWS` tem a vantagem de fornecer um protocolo de aplicação consistente para que seu cliente acesse diferentes serviços da AWS.
Nesta demonstração, criamos uma API para expor o Amazon SNS. Para obter mais exemplos de integração de uma API a outros serviços da AWS, consulte [Tutoriais e workshops do Amazon API Gateway](api-gateway-tutorials.md).
Diferentemente da integração de proxy do Lambda não há integração de proxy correspondente para outros serviços da AWS. Portanto, um método de API é integrado a uma única ação da AWS. Para obter mais flexibilidade, semelhante à integração de proxy, é possível configurar uma integração de proxy do Lambda. A função do Lambda então analisa e processa as solicitações para outras ações da AWS.
O API Gateway não tenta novamente quando o endpoint atinge o tempo limite. O autor da chamada da API deve implementar lógica de novas tentativas para lidar com tempos limite do endpoint.
Este passo a passo se baseia nas instruções e nos conceitos em [Tutorial: Crie uma API REST com uma integração de não proxy do Lambda](getting-started-lambda-non-proxy-integration.md). Se você ainda não concluiu esse passo-a-passo, sugerimos que faça isso primeiro.
**Topics**
+ [Pré-requisitos](#getting-started-aws-proxy-prerequisites)
+ [Etapa 1: Criar o perfil de execução do proxy de serviço da AWS](#getting-started-aws-proxy-add-roles)
+ [Etapa 2: Criar o recurso](#getting-started-aws-proxy-add-resources)
+ [Etapa 3: Criar o método GET](#getting-started-aws-proxy-add-methods)
+ [Etapa 4: Especificar configurações de método e testar o método](#getting-started-aws-proxy-set-methods)
+ [Etapa 5: implantar a API](#getting-started-aws-proxy-deploy)
+ [Etapa 6: testar a API](#getting-started-aws-proxy-test)
+ [Etapa 7: Limpeza](#getting-started-aws-proxy-clean-up)
## Pré-requisitos
Antes de iniciar esta demonstração, você deve fazer o seguinte:
1. Siga as etapas em [Configurar para usar o API Gateway](setting-up.md).
1. Criar uma nova API chamada `MyDemoAPI`. Para obter mais informações, consulte [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md).
1. Implante a API pelo menos uma vez em um estágio denominado `test`. Para obter mais informações, consulte [Implantar a API](getting-started-lambda-non-proxy-integration.md#getting-started-deploy-api) em [Escolher um tutorial de integração do AWS Lambda](getting-started-with-lambda-integration.md).
1. Conclua as demais etapas em [Escolher um tutorial de integração do AWS Lambda](getting-started-with-lambda-integration.md).
1. Crie pelo menos um tópico no Amazon Simple Notification Service (Amazon SNS). Você usará a API implantada para obter uma lista de tópicos no Amazon SNS que estão associados à sua conta da AWS. Para saber como criar um tópico no Amazon SNS, consulte [Criar um tópico](https://docs.aws.amazon.com/sns/latest/dg/sns-create-topic.html). (Não é necessário copiar o ARN do tópico mencionado na etapa 5.)
## Etapa 1: Criar o perfil de execução do proxy de serviço da AWS
Para que a API invoque ações do Amazon SNS, é necessário que as políticas do IAM apropriadas sejam associadas a um perfil do IAM. Neste exercício, você cria um perfil do IAM.
**Como criar o perfil de execução do proxy de serviço da AWS**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM, em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Escolha **Perfis**.
1. Selecione **Criar perfil**.
1. Selecione **Serviço da AWS** em **Selecionar tipo de entidade confiável**, selecione **API Gateway** e **Permite que o API Gateway envie logs ao CloudWatch Logs**.
1. Selecione **Próximo** e, depois, **Próximo**.
1. Em **Role name (Nome da função)**, digite **APIGatewaySNSProxyPolicy** e escolha **Create role (Criar função)**.
1. Na lista **Roles (Funções)**, escolha a função que você acaba de criar. Talvez seja necessário rolar a página ou usar a barra de pesquisa para encontrar o perfil.
1. Para a função escolhida, selecione a guia **Adicionar permissões**.
1. Selecione **Anexar políticas** na lista suspensa.
1. Na barra de pesquisa, insira **AmazonSNSReadOnlyAccess** e escolha **Adicionar permissões**.
**nota**
Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.
1. Anote o **ARN do perfil** recém-criado, você o usará posteriormente.
## Etapa 2: Criar o recurso
Nesta etapa, crie um recurso que permite que o proxy de serviço da AWS interaja com o serviço da AWS.
**Para criar o recurso**
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 a API.
1. Selecione o recurso raiz, **/**, representado por uma única barra (**/**) e, depois, selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **mydemoawsproxy**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
## Etapa 3: Criar o método GET
Nesta etapa, crie um método GET que permite que o proxy de serviço da AWS interaja com o serviço da AWS.
**Como criar o método `GET`**
1. Selecione o recurso **/mydemoawsproxy** e **Criar método**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o tópico do Amazon SNS.
1. Para **AWS service (Serviço da AWS)**, selecione **Amazon SNS**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **ListTopics**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewaySNSProxyPolicy**.
1. Escolha **Criar método**.
## Etapa 4: Especificar configurações de método e testar o método
Agora, é possível testar o método `GET` para verificar se ele foi configurado corretamente para listar os tópicos do Amazon SNS.
**Como testar 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.
1. Escolha **Testar**.
O resultado exibe uma resposta semelhante ao seguinte:
```
{
"ListTopicsResponse": {
"ListTopicsResult": {
"NextToken": null,
"Topics": [
{
"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-1"
},
{
"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-2"
},
...
{
"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-N"
}
]
},
"ResponseMetadata": {
"RequestId": "abc1de23-45fa-6789-b0c1-d2e345fa6b78"
}
}
}
```
## Etapa 5: implantar a API
Nesta etapa, você implantará a API para poder chamá-la de fora do console do API Gateway.
**Para implantar a API**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **test**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Deploy** (Implantar).
## Etapa 6: testar a API
Nesta etapa, você sairá do console do API Gateway e usará seu proxy de serviço da AWS para interagir com o serviço Amazon SNS.
1. No painel de navegação principal, selecione **Estágio**.
1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API.
A aparência deve ser semelhante a esta:
```
https://my-api-id.execute-api.region-id.amazonaws.com/test
```
1. Cole o URL na caixa de endereço de uma nova guia do navegador.
1. Acrescente `/mydemoawsproxy` para que o URL tenha a seguinte aparência:
```
https://my-api-id.execute-api.region-id.amazonaws.com/test/mydemoawsproxy
```
Navegue até a URL. Devem ser exibidas informações semelhante às seguintes:
```
{"ListTopicsResponse":{"ListTopicsResult":{"NextToken": null,"Topics":[{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-1"},{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-2"},...{"TopicArn": "arn:aws:sns:us-east-1:80398EXAMPLE:MySNSTopic-N}]},"ResponseMetadata":{"RequestId":"abc1de23-45fa-6789-b0c1-d2e345fa6b78}}}
```
## Etapa 7: Limpeza
É possível excluir os recursos da IAM necessários que o proxy de serviço da AWS precisa para trabalhar.
**Atenção**
Se você excluir um recurso do IAM do qual o proxy de serviço da AWS depende, esse proxy de serviço da AWS e qualquer API que depender dele deixarão de funcionar. A exclusão de um recurso do IAM não pode ser desfeita. Se quiser usar o recurso do IAM novamente, será necessário recriá-lo.
**Como excluir os recursos do IAM associados**
1. Abra o console do IAM em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Na área **Details** (Detalhes), escolha **Roles** (Funções).
1. Selecione **APIGatewayAWSProxyExecRole** e, depois, escolha **Role Actions (Ações da função)**, **Delete Role (Excluir função)**. Quando solicitado, escolha **Yes, Delete** (Sim, excluir).
1. Na área **Details** (Detalhes), escolha **Policies** (Políticas).
1. Selecione **APIGatewayAWSProxyExecPolicy** 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. Para discussões mais detalhadas sobre como criar uma API como um proxy de serviço da AWS, consulte [Tutorial: Crie uma API REST como um proxy do Amazon S3](integrating-api-with-aws-services-s3.md), [Tutorial: Criar uma API REST de calculadora com duas integrações de serviços da AWS e uma integração sem proxy do Lambda](integrating-api-with-aws-services-lambda.md), ou [Tutorial: Criar uma API REST como um proxy do Amazon Kinesis](integrating-api-with-aws-services-kinesis.md).
# Tutorial: Criar uma API REST de calculadora com duas integrações de serviços da AWS e uma integração sem proxy do Lambda
O [Tutorial: Crie uma API REST com uma integração de não proxy do Lambda](getting-started-lambda-non-proxy-integration.md) usa a integração `Lambda Function` exclusivamente. A integração `Lambda Function` é um caso especial do tipo de integração do `AWS Service` que executa grande parte da configuração de integração para você, como adicionar automaticamente as permissões necessárias com base em recursos para invocar a função do Lambda. Aqui, duas das três integrações usam a integração `AWS Service` Nesse tipo de integração, você tem mais controle, mas precisará executar tarefas manualmente, como criar e especificar uma função do IAM que contém as permissões adequadas.
Neste tutorial, você criará uma função do Lambda `Calc` que implementa operações aritméticas básicas, aceitando e retornando a entrada e a saída formatadas em JSON. Você vai criar uma API REST e integrá-la à função do Lambda das seguintes formas:
1. Ao expor um método `GET` no recurso `/calc` para invocar a função do Lambda, fornecendo a entrada como parâmetros de string de consulta. (Integração `AWS Service`)
1. Ao expor um método `POST` no recurso `/calc` para invocar a função do Lambda, fornecendo a entrada na carga de solicitação do método. (Integração `AWS Service`)
1. Ao expor um `GET` em recursos `/calc/{operand1}/{operand2}/{operator}` aninhados para invocar a função do Lambda, fornecendo a entrada como parâmetros de caminho. (Integração `Lambda Function`)
Além de experimentar este tutorial, talvez você queira estudar o [arquivo de definição do OpenAPI](api-as-lambda-proxy-export-swagger-with-extensions.md) para a API `Calc`, que pode ser importado para o API Gateway seguindo as instruções em [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md).
**Topics**
+ [Criar uma função do IAM que pode ser assumida](#api-as-lambda-proxy-setup-iam-role-policies)
+ [Criar uma função do Lambda `Calc`](#api-as-lambda-proxy-create-lambda-function)
+ [Testar a função do Lambda `Calc`](#api-as-lambda-proxy-test-lambda-function-)
+ [Criar uma API `Calc`](#api-as-lambda-proxy-create-api-resources)
+ [Integração 1: Criar um método `GET` com parâmetros de consulta para chamar a função do Lambda](#api-as-lambda-proxy-expose-get-method-with-query-strings-to-call-lambda-function)
+ [Integração 2: Criar um método `POST` com uma carga JSON para chamar a função do Lambda](#api-as-lambda-proxy-expose-post-method-with-json-body-to-call-lambda-function)
+ [Integração 3: Criar um método `GET` com parâmetros de caminho para chamar a função do Lambda](#api-as-lambda-proxy-expose-get-method-with-path-parameters-to-call-lambda-function)
+ [Definições do OpenAPI da API demonstrativa integrada com uma função do Lambda](api-as-lambda-proxy-export-swagger-with-extensions.md)
## Criar uma função do IAM que pode ser assumida
Para que sua API invoque sua função do Lambda `Calc`, você precisará ter uma função do IAM do API Gateway que pode ser assumida, que é uma função do IAM com o seguinte relacionamento confiável:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": "apigateway.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
A função criada precisará ter uma permissão do Lambda [InvokeFunction](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Caso contrário, o autor da chamada de API receberá uma resposta `500 Internal Server Error`. Para conceder essa permissão à função, você anexará a política do IAM a ela:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
------
Veja a seguir como fazer isso:
**Criar uma função do IAM do API Gateway que possa ser assumida**
1. Faça login no console do IAM.
1. Escolha **Roles**.
1. Selecione **Create Role**.
1. Em **Select type of trusted entity** (Selecionar tipo de entidade confiável), selecione **AWS Serviço**.
1. Em **Choose the service that will use this role** (Escolha o serviço que usará essa função), escolha **Lambda**.
1. Escolha **Next: Permissions** (Próximo: Permissões).
1. Selecione **Create Policy** (Criar política).
Uma nova janela do console **Create Policy** (Criar Política) será aberta. Nessa janela, faça o seguinte:
1. Na guia **JSON**, substitua a política existente pela política a seguir:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "lambda:InvokeFunction",
"Resource": "*"
}
]
}
```
------
1. Escolha **Review policy** (Revisar política).
1. Em **Review Policy (Revisar política)**, faça o seguinte:
1. Em **Name**, digite um nome de usuário, como **lambda\$1execute**.
1. Selecione **Create Policy** (Criar política).
1. Na janela do console **Create Role (Criar função)** original, faça o seguinte:
1. Em **Attach permissions policies (Anexar permissões políticas)**, escolha a política **lambda\$1execute** na lista suspensa.
Se você não vir a política na lista, selecione o botão Atualizar na parte superior da lista. (Não atualize a página do navegador.)
1. Selecione **Next: Tags (Próximo: tags)**.
1. Selecione **Next:Review (Próximo: análise)**.
1. Em **Role name (Nome da função)**, digite um nome como **lambda\$1invoke\$1function\$1assume\$1apigw\$1role**.
1. Selecione **Create role**.
1. Escolha **lambda\$1invoke\$1function\$1assume\$1apigw\$1role** na lista de funções.
1. Selecione a guia **Trust relationships (Relações de confiança)**.
1. Escolha **Edit trust relationship (Editar relação de confiança)**.
1. Substitua a política existente pela seguinte:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"Service": [
"lambda.amazonaws.com",
"apigateway.amazonaws.com"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
1. Escolha **Update Trust Policy**.
1. Anote o ARN da função para a função que acabou de criar. Você precisará disso mais tarde.
## Criar uma função do Lambda `Calc`
Depois, você criará uma função do Lambda usando o console do Lambda.
1. No console do Lambda, escolha **Create function (Criar função)**.
1. Escolha **Author from Scratch**.
1. Em **Name (Nome)**, insira **Calc**.
1. Em **Tempo de execução**, escolha o último runtime **Node.js** ou **Python** compatível.
1. Em todas as outras opções, use a configuração padrão.
1. Escolha a opção **Criar função**.
1. Copie a função do Lambda a seguir em seu runtime preferido e cole-a no editor de código do console do Lambda.
------
#### [ Node.js ]
```
export const handler = async function (event, context) {
console.log("Received event:", JSON.stringify(event));
if (
event.a === undefined ||
event.b === undefined ||
event.op === undefined
) {
return "400 Invalid Input";
}
const res = {};
res.a = Number(event.a);
res.b = Number(event.b);
res.op = event.op;
if (isNaN(event.a) || isNaN(event.b)) {
return "400 Invalid Operand";
}
switch (event.op) {
case "+":
case "add":
res.c = res.a + res.b;
break;
case "-":
case "sub":
res.c = res.a - res.b;
break;
case "*":
case "mul":
res.c = res.a * res.b;
break;
case "/":
case "div":
if (res.b == 0) {
return "400 Divide by Zero";
} else {
res.c = res.a / res.b;
}
break;
default:
return "400 Invalid Operator";
}
return res;
};
```
------
#### [ Python ]
```
import json
def lambda_handler(event, context):
print(event)
try:
(event['a']) and (event['b']) and (event['op'])
except KeyError:
return '400 Invalid Input'
try:
res = {
"a": float(
event['a']), "b": float(
event['b']), "op": event['op']}
except ValueError:
return '400 Invalid Operand'
if event['op'] == '+':
res['c'] = res['a'] + res['b']
elif event['op'] == '-':
res['c'] = res['a'] - res['b']
elif event['op'] == '*':
res['c'] = res['a'] * res['b']
elif event['op'] == '/':
if res['b'] == 0:
return '400 Divide by Zero'
else:
res['c'] = res['a'] / res['b']
else:
return '400 Invalid Operator'
return res
```
------
1. Em Execution role (Função de execução), selecione **Choose an existing role (Selecionar uma função existente)**.
1. Insira o ARN da função para a função **lambda\$1invoke\$1function\$1assume\$1apigw\$1role** que você criou anteriormente.
1. Escolha **Deploy** (Implantar).
Essa função requer dois operandos (`a` e `b`) e um operador (`op`) a partir do parâmetro de entrada `event`. A entrada é um objeto JSON no seguinte formato:
```
{
"a": "Number" | "String",
"b": "Number" | "String",
"op": "String"
}
```
Essa função retorna o resultado calculado (`c`) e a entrada. Para uma entrada inválida, a função retorna o valor nulo ou a string "Invalid op" como resultado. A saída é do seguinte formato JSON:
```
{
"a": "Number",
"b": "Number",
"op": "String",
"c": "Number" | "String"
}
```
É necessário testar a função no console do Lambda antes de integrá-la à API na próxima etapa.
## Testar a função do Lambda `Calc`
Veja a seguir como testar a função `Calc` no console do Lambda:
1. Selecione a guia **Testar**.
1. Para o nome de evento de teste, insira **calc2plus5**.
1. Substitua a definição de eventos de teste pelo seguinte:
```
{
"a": "2",
"b": "5",
"op": "+"
}
```
1. Escolha **Save** (Salvar).
1. Escolha **Test** (Testar).
1. Expanda **Execution result: succeeded (Resultado da execução: com êxito)**. Você deve ver o seguinte:
```
{
"a": 2,
"b": 5,
"op": "+",
"c": 7
}
```
## Criar uma API `Calc`
O procedimento a seguir mostra como criar uma API para a função do Lambda `Calc` que você acabou de criar. Nas seções a seguir, você adicionará recursos e métodos a ela.
**Como criar uma API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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. Em **API name (Nome da API)**, insira **LambdaCalc**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Mantenha **Tipo de endpoint de API** definido como **Regional**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Create API** (Criar API).
## Integração 1: Criar um método `GET` com parâmetros de consulta para chamar a função do Lambda
Ao criar um método `GET` que transmita parâmetros de string de consulta para a função do Lambda, habilite a API para ser invocada de um navegador. Essa abordagem pode ser útil, especialmente para APIs que permitem acesso aberto.
Depois de criar uma API, você criará um recurso. Normalmente, os recursos da API são organizados em uma árvore de recursos, de acordo com a lógica do aplicativo. Para esta etapa, você vai criar um recurso **/calc**.
**Como criar um recurso **/calc****
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Mantenha **Caminho do recurso** como `/`.
1. Em **Resource Name (Nome do recurso)**, insira **calc**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Ao criar um método `GET` que transmita parâmetros de string de consulta para a função do Lambda, habilite a API para ser invocada de um navegador. Essa abordagem pode ser útil, especialmente para APIs que permitem acesso aberto.
Neste método, o Lambda requer que a solicitação `POST` seja usada para invocar qualquer função do Lambda. Esse exemplo mostra que o método HTTP em uma solicitação de método de front-end pode ser diferente da solicitação de integração no backend.
**Como criar um método `GET`**
1. Selecione o recurso **/calc** e **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou a função do Lambda.
1. Em **AWS service (Serviço da AWS)**, selecione **Lambda**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **POST**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**. Essa opção nos permite especificar o ARN da ação [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) para executar nossa função `Calc`.
1. Em **Substituição de caminho**, digite **2015-03-31/functions/arn:aws:lambda:*us-east-2*:*account-id*:function:Calc/invocations**. Em ** *account-id***, insira o ID da Conta da AWS. Em ***us-east-2***, insira a Região da AWS onde você criou a função do Lambda.
1. Em **Perfil de execução**, digite o ARN do perfil para **lambda\$1invoke\$1function\$1assume\$1apigw\$1role**.
1. Não altere as configurações do **Cache de credenciais** e do **Tempo limite padrão**.
1. Escolha **Configurações de solicitação de método**.
1. Em **Validador de solicitação**, selecione **Validar parâmetros de string de consulta e cabeçalhos**.
Essa configuração fará com que uma mensagem de erro seja gerada se o cliente não especificar os parâmetros necessários.
1. Selecione **Parâmetros de string de consulta de URL**.
Agora configure parâmetros de string de consulta para o método **GET** no recurso **/calc** para que ele possa receber a entrada em nome da função do Lambda de back-end.
Para criar parâmetros de string de consulta, faça o seguinte:
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, digite **operand1**.
1. Ative a opção **Obrigatório**.
1. Mantenha **Armazenamento em cache** desativado.
Repita as mesmas etapas e crie uma string de consulta chamada **operand2** e uma string de consulta chamada **operator**.
1. Escolha **Criar método**.
Agora, você vai criar um modelo de mapeamento para converter as strings de consulta fornecidas pelo cliente na carga útil de solicitações de integração, conforme exigido pela função `Calc`. Esse modelo associa os três parâmetros de consulta declarados em **Solicitação de método** a valores de propriedade designados do objeto JSON como entrada para a função do Lambda de back-end. O objeto JSON transformado será incluído como a carga útil da solicitação de integração.
**Como associar parâmetros de entrada à solicitação de integração**
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**.
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 código:
```
{
"a": "$input.params('operand1')",
"b": "$input.params('operand2')",
"op": "$input.params('operator')"
}
```
1. Escolha **Salvar**.
Agora, é possível testar o método `GET` para verificar se ele foi configurado corretamente para invocar a função do Lambda:
**Como testar 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.
1. Em **Strings de consulta**, digite **operand1=2&operand2=3&operator=\$1**.
1. Escolha **Test** (Testar).
Os resultados devem ser semelhantes ao seguinte:
![\[Criar uma API no API Gateway como um proxy do Lambda\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_lambda_calc_get_method_test_new_console.png)
## Integração 2: Criar um método `POST` com uma carga JSON para chamar a função do Lambda
Depois da criação de um método `POST` com uma carga JSON para chamar a função do Lambda, o cliente deve enviar a entrada necessária para a função de backend no corpo da solicitação. Para garantir que o cliente faça upload dos dados de entrada corretos, você habilitará a validação de solicitações na carga.
**Como criar um método `POST` com uma carga útil do JSON**
1. Selecione o recurso **/calc** e **Criar método**.
1. Em **Tipo de método**, selecione **POST**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou a função do Lambda.
1. Em **AWS service (Serviço da AWS)**, selecione **Lambda**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **POST**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**. Essa opção nos permite especificar o ARN da ação [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html) para executar nossa função `Calc`.
1. Em **Substituição de caminho**, digite **2015-03-31/functions/arn:aws:lambda:*us-east-2*:*account-id*:function:Calc/invocations**. Em ** *account-id***, insira o ID da Conta da AWS. Em ***us-east-2***, insira a Região da AWS onde você criou a função do Lambda.
1. Em **Perfil de execução**, digite o ARN do perfil para **lambda\$1invoke\$1function\$1assume\$1apigw\$1role**.
1. Não altere as configurações do **Cache de credenciais** e do **Tempo limite padrão**.
1. Escolha **Criar método**.
Agora você vai criar um modelo de **entrada** para descrever a estrutura de dados de entrada e validar o corpo da solicitação recebida.
**Como criar o modelo de entrada**
1. No painel de navegação principal, selecione **Modelos**.
1. Escolha **Criar modelo**.
1. Em **Nome**, digite **input**.
1. Em **Tipo de conteúdo**, insira **application/json**.
Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira **\$1default**.
1. Em **Esquema do modelo**, insira o seguinte modelo:
```
{
"type":"object",
"properties":{
"a":{"type":"number"},
"b":{"type":"number"},
"op":{"type":"string"}
},
"title":"input"
}
```
1. Escolha **Criar modelo**.
Agora você vai criar um modelo de **saída**. Esse modelo descreve a estrutura de dados da saída calculada do backend. Ele pode ser usado para mapear dados de resposta de integração para um modelo diferente. Este tutorial depende do comportamento de passagem direta e não usa este modelo.
**Como criar um modelo de saída**
1. Escolha **Criar modelo**.
1. Em **Nome**, digite **output**.
1. Em **Tipo de conteúdo**, insira **application/json**.
Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira **\$1default**.
1. Em **Esquema do modelo**, insira o seguinte modelo:
```
{
"type":"object",
"properties":{
"c":{"type":"number"}
},
"title":"output"
}
```
1. Escolha **Criar modelo**.
Agora você vai criar um modelo de **resultado**. Esse modelo descreve a estrutura de dados dos dados de resposta retornados. Ele faz referência aos esquemas de **entrada** e de **saída** definidos na API.
**Como criar um modelo de resultado**
1. Escolha **Criar modelo**.
1. Em **Nome**, digite **result**.
1. Em **Tipo de conteúdo**, insira **application/json**.
Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira **\$1default**.
1. Em **Esquema do modelo**, insira o modelo a seguir com o *restapi-id*. O *restapi-id* está listado entre parênteses na parte superior do console no seguinte fluxo: `API Gateway > APIs > LambdaCalc (abc123).`
```
{
"type":"object",
"properties":{
"input":{
"$ref":"https://apigateway.amazonaws.com/restapis/restapi-id/models/input"
},
"output":{
"$ref":"https://apigateway.amazonaws.com/restapis/restapi-id/models/output"
}
},
"title":"result"
}
```
1. Escolha **Criar modelo**.
Agora, você vai configurar a solicitação do método POST para habilitar a validação de solicitações no corpo da solicitação recebida.
**Habilitar a validação da solicitação no método POST**
1. No painel de navegação principal, selecione **Recursos** e, depois, selecione o método `POST` na árvore de recursos.
1. Na guia **Solicitação de método**, em **Configurações de solicitação de método**, escolha **Editar**.
1. Em **Validador de solicitação**, selecione **Validar corpo.**
1. Selecione **Corpo da solicitação** e, depois, **Adicionar modelo**.
1. Em **Tipo de conteúdo**, insira **application/json**.
Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira **\$1default**.
1. Em **Modelo**, selecione **entrada**.
1. Escolha **Salvar**.
Agora, é possível testar o método `POST` para verificar se ele foi configurado corretamente para invocar a função do Lambda:
**Como testar o método `POST`**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Corpo da solicitação**, insira a carga útil do JSON a seguir.
```
{
"a": 1,
"b": 2,
"op": "+"
}
```
1. Escolha **Testar**.
A seguinte saída deverá ser mostrada:
```
{
"a": 1,
"b": 2,
"op": "+",
"c": 3
}
```
## Integração 3: Criar um método `GET` com parâmetros de caminho para chamar a função do Lambda
Agora, você criará um método `GET` em um recurso especificado por uma sequência de parâmetros de caminho para chamar a função do Lambda de backend. Os valores de parâmetros de caminho especificam os dados de entrada para a função do Lambda. Você usará um modelo de mapeamento para mapear os valores de parâmetro de caminho de entrada para a carga necessária de solicitação de integração.
A aparência da estrutura de recursos de API resultante será semelhante a esta:
![\[Criar uma API no API Gateway como um proxy do Lambda\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_lambda_create_api_resources_new_console.png)
**Como criar um recurso**/\$1operand1\$1/\$1operand2\$1/\$1operator\$1****
1. Selecione **Criar recurso**.
1. Em **Caminho do recurso**, selecione `/calc`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1operand1\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
1. Em **Caminho do recurso**, selecione `/calc/{operand1}/`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1operand2\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
1. Em **Caminho do recurso**, selecione `/calc/{operand1}/{operand2}/`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1operator\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
Dessa vez, você usará a integração do Lambda incorporada no console do API Gateway para configurar a integração do método.
**Como configurar uma integração de método**
1. Selecione o recurso **/\$1operand1\$1/\$1operand2\$1/\$1operator\$1** e, depois, escolha **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Lambda**.
1. Mantenha a opção **Integração do proxy do Lambda** desativada.
1. Em **Função do Lambda**, selecione a Região da AWS onde você criou a função do Lambda e insira **Calc**.
1. Mantenha o **Tempo limite padrão** ativado.
1. Escolha **Criar método**.
Agora, você vai criar um modelo de mapeamento para associar os três parâmetros de caminho de URL, declarados quando o recurso **/calc/\$1operand1\$1/\$1operand2\$1/\$1operator\$1** foi criado, a valores de propriedade designados no objeto JSON. Como os caminhos de URL devem ser codificados em URL, o operador de divisão deve ser especificado como `%2F` em vez de `/`. Esse modelo converte o `%2F` em `'/'` antes de transferi-lo para a função do Lambda.
**Como criar 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**.
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Corpo do modelo**, insira o seguinte código:
```
{
"a": "$input.params('operand1')",
"b": "$input.params('operand2')",
"op": #if($input.params('operator')=='%2F')"/"#{else}"$input.params('operator')"#end
}
```
1. Escolha **Salvar**.
Agora, é possível testar o método `GET` para verificar se ele foi configurado corretamente para invocar a função do Lambda e passar a saída original pela resposta de integração sem mapeamento.
**Como testar 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.
1. Para o **Caminho**, faça o seguinte:
1. Em **operand1**, insira **1**.
1. Em **operand2**, insira **1**.
1. Em **operador**, insira **\$1**.
1. Escolha **Test** (Testar).
1. O resultado deve ser semelhante ao seguinte:
![\[Teste o método GET no console do API Gateway.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_lambda_calc_get_method_test_path_parm_new_console.png)
Depois, você modelará a estrutura de dados da carga útil de resposta de método após o esquema `result`.
Por padrão, o corpo de resposta de método recebe um modelo vazio. Isso fará com que o corpo de resposta de integração seja repassado sem mapeamento. No entanto, quando você gerar um SDK para uma das linguagens de tipo forte, como Java ou Objective-C, os usuários do seu SDK receberão um objeto vazio como resultado. Para garantir que tanto o cliente REST quanto os clientes do SDK recebam o resultado desejado, você deve modelar os dados de resposta usando uma esquema predefinido. Aqui, você definirá um modelo para o corpo de resposta de método e para construir um modelo de mapeamento a fim de traduzir o corpo da resposta de integração no corpo da resposta de método.
**Como criar uma resposta de método**
1. Na guia **Resposta de método**, em **Resposta 200**, selecione **Editar**.
1. Em **Corpo da resposta**, selecione **Adicionar modelo**.
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Modelo**, selecione o **resultado**.
1. Escolha **Salvar**.
Definir o modelo `result` para o corpo da resposta de método garante que os dados da resposta serão convertidos no objeto de um determinado SDK. Para garantir que os dados de resposta de integração sejam mapeados de acordo, você precisará de um modelo de mapeamento.
**Como criar um modelo de mapeamento**
1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**.
1. Selecione **Modelos de mapeamento**.
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Corpo do modelo**, insira o seguinte código:
```
#set($inputRoot = $input.path('$'))
{
"input" : {
"a" : $inputRoot.a,
"b" : $inputRoot.b,
"op" : "$inputRoot.op"
},
"output" : {
"c" : $inputRoot.c
}
}
```
1. Escolha **Salvar**.
**Como testar o modelo de mapeamento**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Para o **Caminho**, faça o seguinte:
1. Em **operand1**, insira **1**.
1. Em **operand2**, insira **2**.
1. Em **operador**, insira **\$1**.
1. Escolha **Testar**.
1. O resultado terá esta aparência:
```
{
"input": {
"a": 1,
"b": 2,
"op": "+"
},
"output": {
"c": 3
}
}
```
Nesse momento, somente é possível chamar a API usando o atributo **Testar** no console do API Gateway. Para disponibilizá-la para os clientes, será necessário implantar a API. Certifique-se de reimplantar sua API sempre que você adicionar, modificar ou excluir um recurso ou método, atualizar um mapeamento de dados ou atualizar as configurações de estágio. Caso contrário, novos atributos ou atualizações não estarão disponíveis para clientes da API.
**Para implantar a API**
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **Prod**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Implantar**.
1. (Opcional) Em **Detalhes do estágio**, para **Invocar URL**, é possível selecionar o ícone de cópia para copiar o URL de invocação da API. Você pode usá-lo com ferramentas, como [Postman](https://www.postman.com) e [cURL](https://curl.se/) para testar sua API.
**nota**
Reimplante a API sempre que você adicionar, modificar ou excluir um recurso ou um método, atualizar um mapeamento de dados ou atualizar as configurações de estágio. Caso contrário, novos recursos ou atualizações não estarão disponíveis para clientes de sua API.
# Definições do OpenAPI da API demonstrativa integrada com uma função do Lambda
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2017-04-20T04:08:08Z",
"title": "LambdaCalc"
},
"host": "uojnr9hd57.execute-api.us-east-1.amazonaws.com",
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/calc": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "operand2",
"in": "query",
"required": true,
"type": "string"
},
{
"name": "operator",
"in": "query",
"required": true,
"type": "string"
},
{
"name": "operand1",
"in": "query",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
},
"headers": {
"operand_1": {
"type": "string"
},
"operand_2": {
"type": "string"
},
"operator": {
"type": "string"
}
}
}
},
"x-amazon-apigateway-request-validator": "Validate query string parameters and headers",
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.operator": "integration.response.body.op",
"method.response.header.operand_2": "integration.response.body.b",
"method.response.header.operand_1": "integration.response.body.a"
},
"responseTemplates": {
"application/json": "#set($res = $input.path('$'))\n{\n \"result\": \"$res.a, $res.b, $res.op => $res.c\",\n \"a\" : \"$res.a\",\n \"b\" : \"$res.b\",\n \"op\" : \"$res.op\",\n \"c\" : \"$res.c\"\n}"
}
}
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"a\": \"$input.params('operand1')\",\n \"b\": \"$input.params('operand2')\", \n \"op\": \"$input.params('operator')\" \n}"
},
"type": "aws"
}
},
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"in": "body",
"name": "Input",
"required": true,
"schema": {
"$ref": "#/definitions/Input"
}
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-request-validator": "Validate body",
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : $inputRoot.op,\n \"c\" : $inputRoot.c\n}"
}
}
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_templates",
"httpMethod": "POST",
"type": "aws"
}
}
},
"/calc/{operand1}/{operand2}/{operator}": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "operand2",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "operator",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "operand1",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Result"
}
}
},
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"default": {
"statusCode": "200",
"responseTemplates": {
"application/json": "#set($inputRoot = $input.path('$'))\n{\n \"input\" : {\n \"a\" : $inputRoot.a,\n \"b\" : $inputRoot.b,\n \"op\" : \"$inputRoot.op\"\n },\n \"output\" : {\n \"c\" : $inputRoot.c\n }\n}"
}
}
},
"uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:Calc/invocations",
"passthroughBehavior": "when_no_templates",
"httpMethod": "POST",
"requestTemplates": {
"application/json": "{\n \"a\": \"$input.params('operand1')\",\n \"b\": \"$input.params('operand2')\",\n \"op\": #if($input.params('operator')=='%2F')\"/\"#{else}\"$input.params('operator')\"#end\n \n}"
},
"contentHandling": "CONVERT_TO_TEXT",
"type": "aws"
}
}
}
},
"definitions": {
"Input": {
"type": "object",
"required": [
"a",
"b",
"op"
],
"properties": {
"a": {
"type": "number"
},
"b": {
"type": "number"
},
"op": {
"type": "string",
"description": "binary op of ['+', 'add', '-', 'sub', '*', 'mul', '%2F', 'div']"
}
},
"title": "Input"
},
"Output": {
"type": "object",
"properties": {
"c": {
"type": "number"
}
},
"title": "Output"
},
"Result": {
"type": "object",
"properties": {
"input": {
"$ref": "#/definitions/Input"
},
"output": {
"$ref": "#/definitions/Output"
}
},
"title": "Result"
}
},
"x-amazon-apigateway-request-validators": {
"Validate body": {
"validateRequestParameters": false,
"validateRequestBody": true
},
"Validate query string parameters and headers": {
"validateRequestParameters": true,
"validateRequestBody": false
}
}
}
```
------
# Tutorial: Crie uma API REST como um proxy do Amazon S3
Como exemplo para mostrar o uso de uma API REST no API Gateway para o proxy do Amazon S3, esta seção descreve como criar e configurar uma API REST para expor as seguintes operações do Amazon S3:
+ Expor GET no recurso raiz da API para [listar todos os buckets do Amazon S3 de um autor da chamada](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html).
+ Expor GET em um recurso Folder para [visualizar uma lista de todos os objetos no bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).
+ Expor GET em um recurso Folder/Item para [visualizar ou baixar um objeto de um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
É recomendável importar a API de exemplo como um proxy do Amazon S3, conforme mostrado em [Definições do OpenAPI da API de amostra como um proxy do Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md). Este exemplo contém mais métodos expostos. Para obter instruções sobre como importar uma API usando a definição do OpenAPI, consulte [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md).
**nota**
Para integrar sua API do API Gateway ao Amazon S3, é necessário escolher uma região onde os serviços API Gateway e Amazon S3 estejam disponíveis. Para obter a disponibilidade da região, consulte [Endpoints e cotas do Amazon API Gateway](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
**Topics**
+ [Configurar permissões do IAM para a API invocar ações do Amazon S3](#api-as-s3-proxy-iam-permissions)
+ [Criar recursos de API para representar recursos do Amazon S3](#api-as-s3-proxy-create-resources)
+ [Expor um método de API para listar os buckets do Amazon S3 do autor da chamada](#api-root-get-as-s3-get-service)
+ [Expor métodos de API para acessar um bucket do Amazon S3](#api-folder-operations-as-s3-bucket-actions)
+ [Expor métodos de API para acessar um objeto do Amazon S3 em um bucket](#api-items-in-folder-as-s3-objects-in-bucket)
+ [Definições do OpenAPI da API de amostra como um proxy do Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md)
+ [Chamar a API usando um cliente de API REST](api-as-s3-proxy-test-using-postman.md)
## Configurar permissões do IAM para a API invocar ações do Amazon S3
Para permitir que a API invoque ações do Amazon S3, é necessário que as políticas do IAM apropriadas sejam associadas a um perfil do IAM. Neste exercício, você cria um perfil do IAM.
**Como criar o perfil de execução do proxy de serviço da AWS**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM, em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Escolha **Perfis**.
1. Selecione **Criar perfil**.
1. Selecione **Serviço da AWS** em **Selecionar tipo de entidade confiável**, selecione **API Gateway** e **Permite que o API Gateway envie logs ao CloudWatch Logs**.
1. Selecione **Próximo** e, depois, **Próximo**.
1. Em **Role name (Nome da função)**, digite **APIGatewayS3ProxyPolicy** e escolha **Create role (Criar função)**.
1. Na lista **Roles (Funções)**, escolha a função que você acaba de criar. Talvez seja necessário rolar a página ou usar a barra de pesquisa para encontrar o perfil.
1. Para a função escolhida, selecione a guia **Adicionar permissões**.
1. Selecione **Anexar políticas** na lista suspensa.
1. Na barra de pesquisa, insira **AmazonS3FullAccess** e escolha **Adicionar permissões**.
**nota**
Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.
1. Anote o **ARN do perfil** recém-criado, você o usará posteriormente.
## Criar recursos de API para representar recursos do Amazon S3
Use o recurso-raiz da API (`/`) como o contêiner de buckets do Amazon S3 de um chamador autenticado. Também crie recursos `Folder` e `Item` para representar um bucket do Amazon S3 específico e um determinado objeto do Amazon S3, respectivamente. O nome da pasta e a chave do objeto serão especificados, no formato de parâmetros de caminho como parte de uma URL de solicitação, pelo autor da chamada.
**nota**
Ao acessar objetos cuja chave de objeto inclua `/` ou qualquer outro caractere especial, o caractere deverá ser codificado por URL. Por exemplo, `test/test.txt` deve ser codificado para `test%2Ftest.txt`.
**Como criar um recurso de API que expõe os recursos de serviços do Amazon S3**
1. Na mesma em Região da AWS onde você criou o bucket do Amazon S3, crie uma API chamada **MyS3**. O recurso raiz dessa API (**/**) representa o serviço Amazon S3. Nesta etapa, você vai criar dois recursos adicionais**/\$1folder\$1** e**/\$1item\$1**.
1. Selecione **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Em **Caminho do recurso**, selecione `/`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1folder\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desmarcado.
1. Selecione **Criar recurso**.
1. Selecione o recurso **/\$1folder\$1** e, depois, **Criar recurso**.
1. Use as etapas anteriores para criar um recurso secundário de **/\$1folder\$1** chamado **\$1item\$1**.
A API final deverá ser semelhante à seguinte:
![\[Criar uma API no API Gateway como um proxy do Amazon S3\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_s3_create_api-resources_new_console.png)
## Expor um método de API para listar os buckets do Amazon S3 do autor da chamada
Obter a lista de buckets do Amazon S3 do autor da chamada envolve invocar a ação [GET Service](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html) no Amazon S3. No recurso raiz do API, (**/**), crie o método GET. Configure o método GET para integrar-se ao Amazon S3 da maneira a seguir.
**Para criar e inicializar o método `GET /` da API**
1. Selecione o recurso **/** e **Criar método**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Para **Região da AWS**, selecione a Região da AWS onde você criou o bucket do Amazon S3.
1. Em **AWS service (Serviço da AWS)**, selecione **Amazon Simple Storage Service**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**.
Com a substituição de caminho, o API Gateway encaminha a solicitação do cliente para o Amazon S3 como a [solicitação no estilo de caminho da API REST do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RESTAPI.html) correspondente em que um recurso do Amazon S3 é expresso pelo caminho de recurso do padrão `s3-host-name/bucket/key`. O API Gateway define o `s3-host-name` e transmite o `bucket` especificado pelo cliente e `key` do cliente para o Amazon S3.
1. Em **Substituição de caminho**, digite **/**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewayS3ProxyPolicy**.
1. Escolha **Configurações de solicitação de método**.
Use as configurações de solicitação de método para controlar quem pode chamar esse método da sua API.
1. Em **Autorização**, no menu suspenso, selecione `AWS_IAM`.
![\[Declarar tipos de resposta de método\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_s3_setup_method_request_authorization_new_console.png)
1. Escolha **Criar método**.
Essa configuração integra a solicitação `GET https://your-api-host/stage/` do front-end com o `GET https://your-s3-host/` do backend.
Para que a API retorne respostas bem-sucedidas e exceções corretamente ao chamador, declare as respostas 200, 400 e 500 em **Resposta de método**. Use o mapeamento padrão para respostas 200 para que as respostas do back-end do código de status não declaradas aqui sejam retornadas ao chamador como respostas 200.
**Como declarar tipos de resposta para o método `GET /`**
1. Na guia **Resposta de método**, em **Resposta 200**, selecione **Editar**.
1. Selecione **Adicionar usuário** e faça o seguinte:
1. Em **Nome do cabeçalho**, insira **Content-Type**.
1. Escolha **Add header** (Adicionar cabeçalho).
Repita essas etapas para criar um cabeçalho **Timestamp** e um **Content-Length**.
1. Escolha **Salvar**.
1. Na guia **Resposta de método**, em **Respostas do método**, selecione **Criar resposta**.
1. Para o **código de status HTTP**, insira **400**.
Você não vai definir nenhum cabeçalho para essa resposta.
1. Escolha **Salvar**.
1. Repita as etapas a seguir para criar a resposta 500.
Você não vai definir nenhum cabeçalho para essa resposta.
Como a resposta de integração bem-sucedida do Amazon S3 retorna a lista de buckets como uma carga útil XML, e a resposta de método padrão do API Gateway retorna uma carga útil JSON, você deve mapear o valor do parâmetro do cabeçalho Content-Type do back-end para sua contraparte do front-end. Caso contrário, o cliente receberá `application/json` para o tipo de conteúdo quando o corpo da resposta é na verdade uma string XML. O procedimento a seguir mostra como configurar isso. Além disso, mostre também para o cliente outros parâmetros de cabeçalho, como Date e Content-Length.
**Para configurar mapeamentos de cabeçalho de resposta para o método GET /**
1. Na guia **Resposta de integração**, em **Padrão - Resposta**, selecione **Editar**.
1. Para o cabeçalho **Content-Length**, insira **integration.response.header.Content-Length** para o valor do mapeamento.
1. Para o cabeçalho **Content-Type**, insira **integration.response.header.Content-Type** para o valor do mapeamento.
1. Para o cabeçalho **Carimbo de data e hora**, insira **integration.response.header.Date** para o valor do mapeamento.
1. Escolha **Salvar**. O resultado deve ser semelhante ao seguinte:
![\[Mapear cabeçalhos de resposta de integração para cabeçalhos de resposta de método\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_s3_setup_integration_response_headers_new_console.png)
1. Na guia **Resposta de integração**, em **Respostas de integração**, selecione **Criar resposta**.
1. Em **HTTP status regex (Regex de status HTTP)**, insira **4\$1d\$12\$1**. Isso associa todos os códigos de status de resposta HTTP 4xx à resposta do método.
1. Em **Código de status de resposta do método**, selecione **400**.
1. Escolha **Criar**.
1. Repita as etapas a seguir para criar uma resposta de integração para a resposta do método 500. Em **HTTP status regex (Regex de status HTTP)**, insira **5\$1d\$12\$1**.
Como prática recomendada, teste a API que você configurou até agora.
**Como testar 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.
1. Escolha **Testar**. O resultado deve ser algo semelhante à seguinte imagem:
![\[Testar o resultado do bucket GET raiz da API\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_s3_test_root_get_result_new_console.png)
## Expor métodos de API para acessar um bucket do Amazon S3
Para trabalhar com um bucket do Amazon S3, exponha o método `GET` no recurso /\$1folder\$1 para listar objetos em um bucket. As instruções são semelhantes às descritas em [Expor um método de API para listar os buckets do Amazon S3 do autor da chamada](#api-root-get-as-s3-get-service). Para conhecer mais métodos, é possível importar a API de exemplo aqui, [Definições do OpenAPI da API de amostra como um proxy do Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md).
**Como expor o método GET em um recurso de pasta**
1. Selecione o recurso **/\$1folder\$1** e, depois, **Criar método**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Para **Região da AWS**, selecione a Região da AWS onde você criou o bucket do Amazon S3.
1. Em **AWS service (Serviço da AWS)**, selecione **Amazon Simple Storage Service**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**.
1. Em **Substituição de caminho**, digite **\$1bucket\$1**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewayS3ProxyPolicy**.
1. Escolha **Criar método**.
Você vai definir os parâmetros de caminho `{folder}` no URL do endpoint do Amazon S3. É necessário associar o parâmetro de caminho `{folder}` da solicitação de método ao parâmetro de caminho `{bucket}` da solicitação de integração.
**Como associar `{folder}` a `{bucket}`**
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de caminho de URL** e, depois, **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **bucket**.
1. Em **Mapeado de**, insira **method.request.path.folder**.
1. Escolha **Salvar**.
Agora, você vai testar a API.
**Como testar o método `/{folder} GET`.**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Caminho**, em **pasta**, insira o nome do bucket.
1. Escolha **Testar**.
O resultado do teste conterá uma lista de objetos no bucket.
![\[Teste o método GET para criar um bucket do Amazon S3.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_s3_test_api_folder_get_new_console.png)
## Expor métodos de API para acessar um objeto do Amazon S3 em um bucket
O Amazon S3 oferece suporte a ações GET, DELETE, HEAD, OPTIONS, POST e PUT para acessar e gerenciar objetos em um determinado bucket. Neste tutorial, você vai expor um método `GET` no recurso `{folder}/{item}` para obter uma imagem de um bucket. Para conhecer mais aplicações do recurso `{folder}/{item}`, consulte a API de exemplo, [Definições do OpenAPI da API de amostra como um proxy do Amazon S3](api-as-s3-proxy-export-swagger-with-extensions.md).
**Como expor o método GET em um recurso de item**
1. Selecione o recurso **/\$1item\$1** e, depois, **Criar método**.
1. Em tipo de método, selecione **GET**.
1. Em **Tipo de integração**, selecione **AWS service (Serviço da AWS)**.
1. Para **Região da AWS**, selecione a Região da AWS onde você criou o bucket do Amazon S3.
1. Em **AWS service (Serviço da AWS)**, selecione **Amazon Simple Storage Service**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, selecione **GET**.
1. Em **Tipo de ação**, escolha **Usar substituição de caminho**.
1. Em **Substituição de caminho**, insira **\$1bucket\$1/\$1object\$1**.
1. Em **Perfil de execução**, digite o ARN do perfil para **APIGatewayS3ProxyPolicy**.
1. Escolha **Criar método**.
Você vai definir os parâmetros de caminho `{folder}` e o `{item}` no URL do endpoint do Amazon S3. É necessário associar o parâmetro de caminho da solicitação de método ao parâmetro de caminho da solicitação de integração.
Nesta etapa, faça o seguinte:
+ Mapeie o parâmetro de caminho `{folder}` da solicitação de método ao parâmetro de caminho `{bucket}` da solicitação de integração.
+ Mapeie o parâmetro de caminho `{item}` da solicitação de método ao parâmetro de caminho `{object}` da solicitação de integração.
**Como associar `{folder}` a `{bucket}` e `{item}` a `{object}`**
1. Na guia **Solicitação de integração**, em **Configurações de solicitação de integração**, selecione **Editar**.
1. Selecione **Parâmetros de caminho de URL**.
1. Selecione **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **bucket**.
1. Em **Mapeado de**, insira **method.request.path.folder**.
1. Selecione **Adicionar parâmetro de caminho**.
1. Em **Nome**, digite **object**.
1. Em **Mapeado de**, insira **method.request.path.item**.
1. Escolha **Salvar**.
**Como testar o método `/{folder}/{object} GET`.**
1. Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Em **Caminho**, em **pasta**, insira o nome do bucket.
1. Em **Caminho**, em **item**, insira o nome de um item.
1. Escolha **Testar**.
O corpo da resposta incluirá o conteúdo do item.
![\[Teste o método GET para criar um bucket do Amazon S3.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/aws_proxy_s3_test_api_item_get_new_console.png)
A solicitação exibe corretamente o texto sem formatação (“Hello world”) como o conteúdo do arquivo especificado (test.txt) no bucket do Amazon S3 especificado (amzn-s3-demo-bucket).
Para fazer download ou upload de arquivos binários, que no API Gateway é qualquer conteúdo que não seja JSON codificado em utf-8, são necessárias configurações de API adicionais. Isto é descrito da seguinte forma:
**Para fazer download ou upload de arquivos binários do S3**
1. Registre os tipos de mídia do arquivo afetado para binaryMediaTypes da API. Você pode fazer isso no console:
1. Selecione **Configurações** para a API.
1. Em **Tipos de mídia binária**, selecione **Adicionar tipo de mídia binária**.
1. Selecione **Adicionar tipo de mídia binária** e insira o tipo de mídia necessário, por exemplo, `image/png`.
1. Selecione **Save changes** (Salvar alterações) para salvar a configuração.
1. Adicione o cabeçalho `Content-Type` (para upload) e/ou `Accept` (para download) à solicitação de método para exigir que o cliente especifique o tipo de mídia binário necessário e o mapeie para a solicitação de integração.
1. Defina **Tratamento de conteúdo** como `Passthrough` na solicitação de integração (para upload) e em uma resposta de integração (para download). Certifique-se de que nenhum modelo de mapeamento está definido para o tipo de conteúdo afetado. Para ter mais informações, consulte [Transformações de dados para APIs REST no API Gateway](rest-api-data-transformations.md).
O tamanho máximo da carga é 10 MB. Consulte [Cotas para configurar e executar uma API REST no API Gateway](api-gateway-execution-service-limits-table.md).
Certifique-se de que os arquivos no Amazon S3 tenham os tipos de conteúdo corretos adicionados como metadados de arquivos. Para a transmissão de conteúdo de mídia, talvez também seja necessário adicionar `Content-Disposition:inline` aos metadados.
Para obter mais informações sobre o suporte binário no API Gateway, consulte [Conversões de tipo de conteúdo no API Gateway](api-gateway-payload-encodings-workflow.md).
# Definições do OpenAPI da API de amostra como um proxy do Amazon S3
As definições da OpenAPI a seguir descrevem uma API que funciona como um proxy do Amazon S3. Essa API contém mais operações do Amazon S3 do que a API que você criou no tutorial. Os seguintes métodos estão expostos nas definições da OpenAPI:
+ Expor GET no recurso raiz da API para [listar todos os buckets do Amazon S3 de um autor da chamada](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListBuckets.html).
+ Expor GET em um recurso Folder para [visualizar uma lista de todos os objetos no bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html).
+ Expor PUT em um recurso Folder para [adicionar um bucket ao Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateBucket.html).
+ Expor DELETE em um recurso Folder para [remover um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html).
+ Expor GET em um recurso Folder/Item para [visualizar ou baixar um objeto de um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html).
+ Expor PUT em um recurso Folder/Item para [fazer upload de um objeto em um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html).
+ Expor HEAD em um recurso Folder/Item para [obter um objeto de metadados em um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html).
+ Expor DELETE em um recurso Folder/Item para [remover um objeto de um bucket do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html).
Para obter instruções sobre como importar uma API usando a definição do OpenAPI, consulte [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md).
Para obter instruções sobre como criar uma API simples, consulte [Tutorial: Crie uma API REST como um proxy do Amazon S3](integrating-api-with-aws-services-s3.md).
Para saber como invocar essa API usando o [Postman](https://www.postman.com/), que é compatível com a autorização do IAM AWS, consulte [Chamar a API usando um cliente de API REST](api-as-s3-proxy-test-using-postman.md).
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-10-13T23:04:43Z",
"title": "MyS3"
},
"host": "9gn28ca086.execute-api.{region}.amazonaws.com",
"basePath": "/S3",
"schemes": [
"https"
],
"paths": {
"/": {
"get": {
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Timestamp": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type",
"method.response.header.Content-Length": "integration.response.header.Content-Length",
"method.response.header.Timestamp": "integration.response.header.Date"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"uri": "arn:aws:apigateway:us-west-2:s3:path//",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
}
},
"/{folder}": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Date": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type",
"method.response.header.Date": "integration.response.header.Date",
"method.response.header.Content-Length": "integration.response.header.content-length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"put": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type",
"method.response.header.Content-Length": "integration.response.header.Content-Length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.bucket": "method.request.path.folder",
"integration.request.header.Content-Type": "method.request.header.Content-Type"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws"
}
},
"delete": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Date": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type",
"method.response.header.Date": "integration.response.header.Date"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"passthroughBehavior": "when_no_match",
"httpMethod": "DELETE",
"type": "aws"
}
}
},
"/{folder}/{item}": {
"get": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"content-type": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.content-type": "integration.response.header.content-type",
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "GET",
"type": "aws"
}
},
"head": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type",
"method.response.header.Content-Length": "integration.response.header.Content-Length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "HEAD",
"type": "aws"
}
},
"put": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type",
"method.response.header.Content-Length": "integration.response.header.Content-Length"
}
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder",
"integration.request.header.Content-Type": "method.request.header.Content-Type"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "PUT",
"type": "aws"
}
},
"delete": {
"produces": [
"application/json"
],
"parameters": [
{
"name": "item",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "folder",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Length": {
"type": "string"
},
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response"
},
"500": {
"description": "500 response"
}
},
"security": [
{
"sigv4": []
}
],
"x-amazon-apigateway-integration": {
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"responses": {
"4\\d{2}": {
"statusCode": "400"
},
"default": {
"statusCode": "200"
},
"5\\d{2}": {
"statusCode": "500"
}
},
"requestParameters": {
"integration.request.path.object": "method.request.path.item",
"integration.request.path.bucket": "method.request.path.folder"
},
"uri": "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"passthroughBehavior": "when_no_match",
"httpMethod": "DELETE",
"type": "aws"
}
}
}
},
"securityDefinitions": {
"sigv4": {
"type": "apiKey",
"name": "Authorization",
"in": "header",
"x-amazon-apigateway-authtype": "awsSigv4"
}
},
"definitions": {
"Empty": {
"type": "object",
"title": "Empty Schema"
}
}
}
```
------
#### [ OpenAPI 3.0 ]
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "MyS3",
"version" : "2016-10-13T23:04:43Z"
},
"servers" : [ {
"url" : "https://9gn28ca086.execute-api.{region}.amazonaws.com/{basePath}",
"variables" : {
"basePath" : {
"default" : "S3"
}
}
} ],
"paths" : {
"/{folder}" : {
"get" : {
"parameters" : [ {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Content-Length" : {
"schema" : {
"type" : "string"
}
},
"Date" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "GET",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.Content-Type" : "integration.response.header.Content-Type",
"method.response.header.Date" : "integration.response.header.Date",
"method.response.header.Content-Length" : "integration.response.header.content-length"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.bucket" : "method.request.path.folder"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
},
"put" : {
"parameters" : [ {
"name" : "Content-Type",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Content-Length" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "PUT",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.Content-Type" : "integration.response.header.Content-Type",
"method.response.header.Content-Length" : "integration.response.header.Content-Length"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.bucket" : "method.request.path.folder",
"integration.request.header.Content-Type" : "method.request.header.Content-Type"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
},
"delete" : {
"parameters" : [ {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Date" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "DELETE",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.Content-Type" : "integration.response.header.Content-Type",
"method.response.header.Date" : "integration.response.header.Date"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.bucket" : "method.request.path.folder"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
}
},
"/{folder}/{item}" : {
"get" : {
"parameters" : [ {
"name" : "item",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"content-type" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "GET",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.content-type" : "integration.response.header.content-type",
"method.response.header.Content-Type" : "integration.response.header.Content-Type"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.object" : "method.request.path.item",
"integration.request.path.bucket" : "method.request.path.folder"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
},
"put" : {
"parameters" : [ {
"name" : "Content-Type",
"in" : "header",
"schema" : {
"type" : "string"
}
}, {
"name" : "item",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Content-Length" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "PUT",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.Content-Type" : "integration.response.header.Content-Type",
"method.response.header.Content-Length" : "integration.response.header.Content-Length"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.object" : "method.request.path.item",
"integration.request.path.bucket" : "method.request.path.folder",
"integration.request.header.Content-Type" : "method.request.header.Content-Type"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
},
"delete" : {
"parameters" : [ {
"name" : "item",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Content-Length" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "DELETE",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200"
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.object" : "method.request.path.item",
"integration.request.path.bucket" : "method.request.path.folder"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
},
"head" : {
"parameters" : [ {
"name" : "item",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
}, {
"name" : "folder",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Content-Length" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "HEAD",
"uri" : "arn:aws:apigateway:us-west-2:s3:path/{bucket}/{object}",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.Content-Type" : "integration.response.header.Content-Type",
"method.response.header.Content-Length" : "integration.response.header.Content-Length"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"requestParameters" : {
"integration.request.path.object" : "method.request.path.item",
"integration.request.path.bucket" : "method.request.path.folder"
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
}
},
"/" : {
"get" : {
"responses" : {
"400" : {
"description" : "400 response",
"content" : { }
},
"500" : {
"description" : "500 response",
"content" : { }
},
"200" : {
"description" : "200 response",
"headers" : {
"Content-Length" : {
"schema" : {
"type" : "string"
}
},
"Timestamp" : {
"schema" : {
"type" : "string"
}
},
"Content-Type" : {
"schema" : {
"type" : "string"
}
}
},
"content" : {
"application/json" : {
"schema" : {
"$ref" : "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration" : {
"credentials" : "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"httpMethod" : "GET",
"uri" : "arn:aws:apigateway:us-west-2:s3:path//",
"responses" : {
"4\\d{2}" : {
"statusCode" : "400"
},
"default" : {
"statusCode" : "200",
"responseParameters" : {
"method.response.header.Content-Type" : "integration.response.header.Content-Type",
"method.response.header.Content-Length" : "integration.response.header.Content-Length",
"method.response.header.Timestamp" : "integration.response.header.Date"
}
},
"5\\d{2}" : {
"statusCode" : "500"
}
},
"passthroughBehavior" : "when_no_match",
"type" : "aws"
}
}
}
},
"components" : {
"schemas" : {
"Empty" : {
"title" : "Empty Schema",
"type" : "object"
}
}
}
}
```
------
# Chamar a API usando um cliente de API REST
Para fornecer um tutorial abrangente, agora mostramos como chamar a API usando o [Postman](https://www.postman.com/), que oferece suporte à autorização do IAM da AWS.
**Como chamar nossa API de proxy do Amazon S3 usando Postman**
1. Implante ou reimplante a API. Anote a URL base da API que é exibida ao lado de **Invocar URL** na parte superior de **Editor de estágio**.
1. Inicie o Postman.
1. Escolha **Autorização** e `AWS Signature`. Insira o ID de chave de acesso e a chave de acesso secreta do usuário do IAM nos campos de entrada **AccessKey** e **SecretKey**, respectivamente. Insira a Região da AWS onde sua API está implantada na caixa de texto **Região da AWS**. Insira `execute-api` no campo de entrada **Nome do serviço**.
É possível criar um par de chaves da guia **Security Credentials (Credenciais de segurança)** da conta de usuário do IAM no Console de Gerenciamento do IAM.
1. Para adicionar um bucket denominado `amzn-s3-demo-bucket` à conta do Amazon S3 na região `{region}`:
1. Escolha **PUT** na lista suspensa de métodos e digite a URL do método (`https://api-id.execute-api.aws-region.amazonaws.com/stage/folder-name`)
1. Defina o valor do cabeçalho `Content-Type` como `application/xml`. Talvez seja necessário excluir todos os cabeçalhos existentes antes de definir o tipo de conteúdo.
1. Escolha o item de menu **Corpo** e digite o seguinte fragmento de XML como o corpo da solicitação:
```
{region}
```
1. Escolha **Enviar** para enviar a solicitação. Se for bem-sucedido, você receberá uma resposta `200 OK` com uma carga vazia.
1. Para adicionar um arquivo de texto a um bucket, siga as instruções acima. Se você especificar o nome de um bucket de **amzn-s3-demo-bucket** como `{folder}` e o nome de um arquivo de**Readme.txt** como `{item}` no URL e fornecer uma string de texto de **Hello, World\$1** como conteúdos de arquivos (tornando-a, dessa forma, a carga da solicitação), a solicitação se tornará
```
PUT /S3/amzn-s3-demo-bucket/Readme.txt HTTP/1.1
Host: 9gn28ca086.execute-api.{region}.amazonaws.com
Content-Type: application/xml
X-Amz-Date: 20161015T062647Z
Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-api/aws4_request, SignedHeaders=content-length;content-type;host;x-amz-date, Signature=ccadb877bdb0d395ca38cc47e18a0d76bb5eaf17007d11e40bf6fb63d28c705b
Cache-Control: no-cache
Postman-Token: 6135d315-9cc4-8af8-1757-90871d00847e
Hello, World!
```
Se tudo der certo, você receberá uma resposta `200 OK` com uma carga vazia.
1. Para obter o conteúdo do arquivo `Readme.txt` que acabamos de adicionar ao bucket `amzn-s3-demo-bucket`, faça uma solicitação GET como a seguinte:
```
GET /S3/amzn-s3-demo-bucket/Readme.txt HTTP/1.1
Host: 9gn28ca086.execute-api.{region}.amazonaws.com
Content-Type: application/xml
X-Amz-Date: 20161015T063759Z
Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ba09b72b585acf0e578e6ad02555c00e24b420b59025bc7bb8d3f7aed1471339
Cache-Control: no-cache
Postman-Token: d60fcb59-d335-52f7-0025-5bd96928098a
```
Se for bem-sucedido, você receberá uma resposta `200 OK` com uma string de texto `Hello, World!` como carga.
1. Para listar itens no bucket `amzn-s3-demo-bucket`, envie a seguinte solicitação:
```
GET /S3/amzn-s3-demo-bucket HTTP/1.1
Host: 9gn28ca086.execute-api.{region}.amazonaws.com
Content-Type: application/xml
X-Amz-Date: 20161015T064324Z
Authorization: AWS4-HMAC-SHA256 Credential=access-key-id/20161015/{region}/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=4ac9bd4574a14e01568134fd16814534d9951649d3a22b3b0db9f1f5cd4dd0ac
Cache-Control: no-cache
Postman-Token: 9c43020a-966f-61e1-81af-4c49ad8d1392
```
Se for bem-sucedido, você receberá uma resposta `200 OK` com uma carga XML mostrando um único item no bucket especificado, a menos que tenha adicionado mais arquivos ao bucket antes de enviar essa solicitação.
```
apig-demo-5
1000
false
Readme.txt
2016-10-15T06:26:48.000Z
"65a8e27d8879283831b664bd8b7f0ad4"
13
06e4b09e9d...603addd12ee
user-name
STANDARD
```
**nota**
Para carregar ou baixar uma imagem, você precisa configurar a manipulação de conteúdo para CONVERT\$1TO\$1BINARY.
# Tutorial: Criar uma API REST como um proxy do Amazon Kinesis
Esta página descreve como criar e configurar uma API REST com uma integração do tipo `AWS` para acessar o Kinesis.
**nota**
Para integrar sua API do API Gateway ao Kinesis, é necessário escolher uma região onde os serviços API Gateway e Kinesis estejam disponíveis. Para saber a disponibilidade da região, consulte [Endpoints e cotas de serviço](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html).
Para fins de ilustração, criamos uma API de exemplo para permitir que um cliente faça o seguinte:
1. Listar os streams disponíveis do usuário no Kinesis
1. Criar, descrever ou excluir um fluxo especificado
1. Leia registros de dados ou escreva registros de dados no fluxo especificado
Para realizar as tarefas anteriores, a API expõe métodos em vários recursos para invocar o seguinte, respectivamente:
1. A ação `ListStreams` no Kinesis
1. A ação `CreateStream`, `DescribeStream` ou `DeleteStream`
1. A ação `GetRecords` ou `PutRecords` (incluindo `PutRecord`) no Kinesis
Especificamente, construiremos a API da seguinte maneira:
+ Expondo um método HTTP GET no recurso `/streams` da API e integrando o método à ação [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html) no Kinesis para listar os streams na conta do autor da chamada.
+ Expondo um método HTTP POST no recurso `/streams/{stream-name}` da API e integrando esse método à ação [CreateStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_CreateStream.html) no Kinesis para criar um stream nomeado na conta do autor da chamada.
+ Expondo um método HTTP GET no recurso `/streams/{stream-name}` da API e integrando esse método à ação [DescribeStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStream.html) no Kinesis para descrever um stream nomeado na conta do autor da chamada.
+ Expondo um método HTTP DELETE no recurso `/streams/{stream-name}` da API e integrando o método à ação [DeleteStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DeleteStream.html) no Kinesis para excluir um stream na conta do autor da chamada.
+ Expondo um método HTTP PUT no recurso `/streams/{stream-name}/record` da API e integrando o método à ação [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) no Kinesis. Isso permite que o cliente adicione um único registro de dados ao fluxo nomeado.
+ Expondo um método HTTP PUT no recurso `/streams/{stream-name}/records` da API e integrando o método à ação [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html) no Kinesis. Isso permite que o cliente adicione uma lista de registros de dados ao fluxo nomeado.
+ Expondo um método HTTP GET no recurso `/streams/{stream-name}/records` da API e integrando esse método à ação [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html) no Kinesis. Isso permite que o cliente liste registros de dados no fluxo nomeado com um iterador de fragmentos especificado. Um iterador de fragmentos especifica a posição do fragmento a partir da qual começar a ler os registros de dados sequencialmente.
+ Expondo um método HTTP GET no recurso `/streams/{stream-name}/sharditerator` da API e integrando esse método à ação [GetShardIterator](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html) no Kinesis. Esse método auxiliar deve ser fornecido à ação `ListStreams` no Kinesis.
É possível aplicar as instruções apresentadas aqui a outras ações do Kinesis. Para obter a lista completa das ações do Kinesis, consulte [Referência de API do Amazon Kinesis](https://docs.aws.amazon.com/kinesis/latest/APIReference/Welcome.html).
Em vez de usar o console do API Gateway para criar a API demonstrativa, é possível importar a API demonstrativa para o API Gateway usando a [API de importação](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html) do API Gateway. Para obter informações sobre como usar o recurso Import API, consulte [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md).
## Criar uma função e política do IAM para a API acessar o Kinesis
Para que a API invoque ações do Kinesis, é necessário ter as políticas do IAM apropriadas anexadas a um perfil do IAM. Neste exercício, você cria um perfil do IAM.
**Como criar o perfil de execução do proxy de serviço da AWS**
1. Faça login no Console de gerenciamento da AWS e abra o console do IAM, em [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/).
1. Escolha **Perfis**.
1. Selecione **Criar perfil**.
1. Selecione **Serviço da AWS** em **Selecionar tipo de entidade confiável**, selecione **API Gateway** e **Permite que o API Gateway envie logs ao CloudWatch Logs**.
1. Selecione **Próximo** e, depois, **Próximo**.
1. Em **Role name (Nome da função)**, digite **APIGatewayKinesisProxyPolicy** e escolha **Create role (Criar função)**.
1. Na lista **Roles (Funções)**, escolha a função que você acaba de criar. Talvez seja necessário rolar a página ou usar a barra de pesquisa para encontrar o perfil.
1. Para a função escolhida, selecione a guia **Adicionar permissões**.
1. Selecione **Anexar políticas** na lista suspensa.
1. Na barra de pesquisa, insira **AmazonKinesisFullAccess** e escolha **Adicionar permissões**.
**nota**
Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.
1. Anote o **ARN do perfil** recém-criado, você o usará posteriormente.
## Criar uma API como um proxy do Kinesis
Use as etapas a seguir para criar a API no console do API Gateway.
**Como criar uma API como um proxy de serviço da AWS para o Kinesis**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. 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)**.
1. Em **API name (Nome da API)**, insira **KinesisProxy**. Mantenha os valores padrão para todos os outros campos.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Selecione **Create API** (Criar API).
Após a criação da API, o console do API Gateway exibe a página **Resources (Recursos)**, que contém apenas o recurso raiz (`/`) da API.
## Listar streams no Kinesis
O Kinesis é compatível com a ação `ListStreams` com a seguinte chamada da API REST:
```
POST /?Action=ListStreams HTTP/1.1
Host: kinesis..
Content-Length:
User-Agent:
Content-Type: application/x-amz-json-1.1
Authorization:
X-Amz-Date:
{
...
}
```
Na solicitação de API REST acima, a ação é especificada no parâmetro `Action` da consulta. Como alternativa, você pode especificar a ação em um cabeçalho `X-Amz-Target`:
```
POST / HTTP/1.1
Host: kinesis..
Content-Length:
User-Agent:
Content-Type: application/x-amz-json-1.1
Authorization:
X-Amz-Date:
X-Amz-Target: Kinesis_20131202.ListStreams
{
...
}
```
Neste tutorial, usamos o parâmetro de consulta para especificar a ação.
Para expor uma ação do Kinesis na API, adicione um recurso `/streams` à raiz da API. Depois, defina um método `GET` no recurso e integre o método com a ação `ListStreams` do Kinesis.
O procedimento a seguir descreve como listar streams do Kinesis usando o console do API Gateway.
**Como listar streams do Kinesis usando o console do API Gateway**
1. Selecione o recurso `/` e, depois, escolha **Criar recurso**.
1. Em **Resource Name (Nome do recurso)**, insira **streams**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
1. Selecione o recurso `/streams` e, depois, **Criar método** e faça o seguinte:
1. Em **Tipo de método**, selecione **GET**.
**nota**
O verbo HTTP para um método invocado por um cliente pode ser diferente do verbo HTTP para uma integração exigida pelo backend. Aqui, selecionamos `GET` porque a listagem de fluxos é intuitivamente uma operação READ.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
**nota**
Aqui, escolhemos `POST` porque o Kinesis exige que a ação `ListStreams` seja invocada com ele.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **ListStreams**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Criar método**.
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 **Parâmetros de cabeçalhos de solicitações de URL** e faça o seguinte:
1. Selecione **Adicionar parâmetro de cabeçalhos de solicitação**.
1. Em **Nome**, digite **Content-Type**.
1. Em **Mapeado de**, insira **'application/x-amz-json-1.1'**.
Usamos um mapeamento de parâmetros de solicitação para definir o cabeçalho `Content-Type` como o valor estático de `'application/x-amz-json-1.1'` para informar ao Kinesis que a entrada é de uma versão específica do JSON.
1. Selecione **Modelos de mapeamento**, **Adicionar modelo de mapeamento** e faça o seguinte:
1. Em **Tipo de conteúdo**, insira **application/json**.
1. Em **Corpo do modelo**, insira **\$1\$1**.
1. Escolha **Salvar**.
A solicitação [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html#API_ListStreams_RequestSyntax) requer uma carga com o seguinte formato JSON:
```
{
"ExclusiveStartStreamName": "string",
"Limit": number
}
```
No entanto, as propriedades são opcionais. Para usar os valores padrão, optamos por uma carga JSON vazia aqui.
1. Teste o método GET no recurso **/streams** para invocar a ação `ListStreams` no Kinesis:
Selecione a guia **Testar**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
Selecione **Testar** para testar o método.
Se você já criou dois streams chamados “myStream” e “yourStream” no Kinesis, o teste bem-sucedido retornará uma resposta 200 OK contendo a seguinte carga útil:
```
{
"HasMoreStreams": false,
"StreamNames": [
"myStream",
"yourStream"
]
}
```
## Criar, descrever e excluir um stream no Kinesis
As tarefas de criar, descrever e excluir um stream no Kinesis envolvem fazer as seguintes solicitações de API REST do Kinesis, respectivamente:
```
POST /?Action=CreateStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"ShardCount": number,
"StreamName": "string"
}
```
```
POST /?Action=DescribeStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"StreamName": "string"
}
```
```
POST /?Action=DeleteStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"StreamName":"string"
}
```
Podemos construir a API para aceitar a entrada necessária como uma carga de JSON da solicitação de método e passar essa carga diretamente à solicitação de integração. No entanto, para fornecer mais exemplos do mapeamento de dados entre solicitações de método e integração e respostas de método e integração, criamos nossa API de uma maneira um pouco diferente.
Expomos os métodos HTTP `GET`, `POST` e `Delete` em um recurso de `Stream` a ser nomeado. Usamos a variável de caminho `{stream-name}` como o espaço reservado do recurso de stream e integramos esses métodos de API às ações `DescribeStream`, `CreateStream` e `DeleteStream` do Kinesis, respectivamente. Exigimos que o cliente passe outros dados de entrada como cabeçalhos, parâmetros de consulta ou a carga de uma solicitação de método. Fornecemos modelos de mapeamento para transformar os dados na carga da solicitação de integração necessária.
**Como criar o recurso \$1stream-name\$1**
1. Selecione o recurso **/streams** e **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Em **Caminho do recurso**, selecione `/streams`.
1. Em **Resource Name (Nome do recurso)**, insira **\$1stream-name\$1**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
**Para configurar e testar o método GET em um recurso de fluxo**
1. Selecione o recurso **/\$1stream-name\$1** e **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **DescribeStream**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione os seguintes **parâmetros de cabeçalhos de solicitação de URL**:
```
Content-Type: 'x-amz-json-1.1'
```
A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método `GET /streams`.
1. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método `GET /streams/{stream-name}` à solicitação de integração `POST /?Action=DescribeStream`:
```
{
"StreamName": "$input.params('stream-name')"
}
```
Esse modelo de mapeamento gera a carga de solicitação de integração necessária para a ação `DescribeStream` do Kinesis do valor do parâmetro do caminho `stream-name` da solicitação do método.
1. Para testar o método `GET /stream/{stream-name}` para invocar a ação `DescribeStream` no Kinesis, selecione a guia **Testar**.
1. Em **Caminho**, em **stream-name**, insira o nome de um fluxo existente do Kinesis.
1. Escolha **Testar**. Se o teste for bem-sucedido, uma resposta 200 OK será retornada com uma carga semelhante à seguinte:
```
{
"StreamDescription": {
"HasMoreShards": false,
"RetentionPeriodHours": 24,
"Shards": [
{
"HashKeyRange": {
"EndingHashKey": "68056473384187692692674921486353642290",
"StartingHashKey": "0"
},
"SequenceNumberRange": {
"StartingSequenceNumber": "49559266461454070523309915164834022007924120923395850242"
},
"ShardId": "shardId-000000000000"
},
...
{
"HashKeyRange": {
"EndingHashKey": "340282366920938463463374607431768211455",
"StartingHashKey": "272225893536750770770699685945414569164"
},
"SequenceNumberRange": {
"StartingSequenceNumber": "49559266461543273504104037657400164881014714369419771970"
},
"ShardId": "shardId-000000000004"
}
],
"StreamARN": "arn:aws:kinesis:us-east-1:12345678901:stream/myStream",
"StreamName": "myStream",
"StreamStatus": "ACTIVE"
}
}
```
Depois de implantar a API, você poderá fazer uma solicitação REST com base neste método de API:
```
GET https://your-api-id.execute-api.region.amazonaws.com/stage/streams/myStream HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z
```
**Para configurar e testar o método POST em um recurso de fluxo**
1. Selecione o recurso **/\$1stream-name\$1** e **Criar método**.
1. Em **Tipo de método**, selecione **POST**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **CreateStream**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione os seguintes **parâmetros de cabeçalhos de solicitação de URL**:
```
Content-Type: 'x-amz-json-1.1'
```
A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método `GET /streams`.
1. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método `POST /streams/{stream-name}` à solicitação de integração `POST /?Action=CreateStream`:
```
{
"ShardCount": #if($input.path('$.ShardCount') == '') 5 #else $input.path('$.ShardCount') #end,
"StreamName": "$input.params('stream-name')"
}
```
No modelo de mapeamento anterior, definimos `ShardCount` como um valor fixo de 5 se o cliente não especificar um valor na carga da solicitação do método.
1. Para testar o método `POST /stream/{stream-name}` para invocar a ação `CreateStream` no Kinesis, selecione a guia **Testar**.
1. Em **Caminho**, em **stream-name**, insira o nome de um novo fluxo do Kinesis.
1. Escolha **Testar**. Se o teste for bem-sucedido, uma resposta 200 OK será retornado sem dados.
Depois de implantar a API, também será possível fazer uma solicitação de API REST no método POST em um recurso Stream para invocar a ação `CreateStream` no Kinesis:
```
POST https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z
{
"ShardCount": 5
}
```
**Configure e teste o método DELETE em um recurso de fluxo**
1. Selecione o recurso **/\$1stream-name\$1** e **Criar método**.
1. Em **Tipo de método**, selecione **DELETE**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **DeleteStream**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione os seguintes **parâmetros de cabeçalhos de solicitação de URL**:
```
Content-Type: 'x-amz-json-1.1'
```
A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método `GET /streams`.
1. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método `DELETE /streams/{stream-name}` à solicitação de integração correspondente de `POST /?Action=DeleteStream`:
```
{
"StreamName": "$input.params('stream-name')"
}
```
Esse modelo de mapeamento gera a entrada necessária para a ação `DELETE /streams/{stream-name}` no nome do caminho da URL de `stream-name` fornecido pelo cliente.
1. Para testar o método `DELETE /stream/{stream-name}` para invocar a ação `DeleteStream` no Kinesis, selecione a guia **Testar**.
1. Em **Caminho**, em **stream-name**, insira o nome de um fluxo existente do Kinesis.
1. Escolha **Testar**. Se o teste for bem-sucedido, uma resposta 200 OK será retornado sem dados.
Depois de implantar a API, você também poderá fazer a solicitação de API REST a seguir no método DELETE em um recurso Stream para chamar a ação `DeleteStream` no Kinesis:
```
DELETE https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
Host: your-api-id.execute-api.region.amazonaws.com
Content-Type: application/json
Authorization: ...
X-Amz-Date: 20160323T194451Z
{}
```
## Obter registros de e adicionar registros a um stream no Kinesis
Depois de criar um stream no Kinesis, você poderá adicionar registros de dados ao stream e ler os dados desse stream. Adicionar registros de dados envolve chamar a ação [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html#API_PutRecords_Examples) ou [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html#API_PutRecord_Examples) no Kinesis. O primeiro adiciona vários registros, enquanto o último adiciona um único registro ao fluxo.
```
POST /?Action=PutRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"Records": [
{
"Data": blob,
"ExplicitHashKey": "string",
"PartitionKey": "string"
}
],
"StreamName": "string"
}
```
ou
```
POST /?Action=PutRecord HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"Data": blob,
"ExplicitHashKey": "string",
"PartitionKey": "string",
"SequenceNumberForOrdering": "string",
"StreamName": "string"
}
```
Aqui, `StreamName` identifica o fluxo de destino para adicionar registros. `StreamName`, `Data` e `PartitionKey` são dados de entrada necessários. No nosso exemplo, podemos usar os valores padrão para todos os dados de entrada opcionais e não especificaremos explicitamente valores para eles na entrada para a solicitação de método.
Ler dados no Kinesis equivale a chamar a ação [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html#API_GetRecords_Examples):
```
POST /?Action=GetRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"ShardIterator": "string",
"Limit": number
}
```
Aqui, o stream de origem do qual estamos obtendo registros é especificado no valor `ShardIterator` necessário, conforme indicado na ação a seguir do Kinesis para obter um iterador de fragmentos:
```
POST /?Action=GetShardIterator HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
{
"ShardId": "string",
"ShardIteratorType": "string",
"StartingSequenceNumber": "string",
"StreamName": "string"
}
```
Para as ações `GetRecords` e `PutRecords`, expomos os métodos `GET` e `PUT`, respectivamente, em um recurso `/records` que está anexado a um recurso de fluxo nomeado (`/{stream-name}`). Da mesma forma, expomos a ação `PutRecord` como um método `PUT` em um recurso `/record`.
Como a ação `GetRecords` usa como entrada um valor `ShardIterator`, que é obtido ao chamar a ação auxiliar `GetShardIterator`, expomos um método auxiliar `GET` em um recurso `ShardIterator` (`/sharditerator`).
**Como criar os recursos /record, /records e /sharditerator**
1. Selecione o recurso **/\$1stream-name\$1** e **Criar recurso**.
1. Mantenha **Recurso proxy** desativado.
1. Em **Caminho do recurso**, selecione `/{stream-name}`.
1. Em **Resource Name (Nome do recurso)**, insira **record**.
1. Mantenha **CORS (Compartilhamento de recursos de origem cruzada)** desativado.
1. Selecione **Criar recurso**.
1. Repita as etapas anteriores para criar um recurso **/records** e um **/sharditerator.** A API final deve ter a seguinte aparência:
![\[Crie o método Records:GET|PUT|PUT|GET para a API.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/api-gateway-kinesis-proxy-setup-streams-stream-record-method-new-console.png)
Os quatro procedimentos a seguir descrevem como configurar cada um dos métodos, como mapear dados de solicitações de método para solicitações de integração e como testar os métodos.
**Como configurar e testar o método `PUT /streams/{stream-name}/record` para invocar `PutRecord` no Kinesis:**
1. Selecione o recurso **/record** e **Criar método**.
1. Em **Tipo de método**, selecione **PUT**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **PutRecord**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione os seguintes **parâmetros de cabeçalhos de solicitação de URL**:
```
Content-Type: 'x-amz-json-1.1'
```
A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método `GET /streams`.
1. Adicione o seguinte modelo de mapeamento de corpo para mapear dados na solicitação do método `PUT /streams/{stream-name}/record` à solicitação de integração correspondente de `POST /?Action=PutRecord`:
```
{
"StreamName": "$input.params('stream-name')",
"Data": "$util.base64Encode($input.json('$.Data'))",
"PartitionKey": "$input.path('$.PartitionKey')"
}
```
Esse modelo de mapeamento pressupõe que a carga da solicitação de método seja do seguinte formato:
```
{
"Data": "some data",
"PartitionKey": "some key"
}
```
Esses dados podem ser modelados pelo seguinte esquema JSON:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PutRecord proxy single-record payload",
"type": "object",
"properties": {
"Data": { "type": "string" },
"PartitionKey": { "type": "string" }
}
}
```
Você pode criar um modelo para incluir esse esquema e usar o modelo para facilitar a geração do modelo de mapeamento. No entanto, pode gerar um modelo de mapeamento sem usar qualquer modelo.
1. Para testar o método `PUT /streams/{stream-name}/record`, defina a variável de caminho `stream-name` como o nome de um fluxo existente, forneça uma carga do formato necessário e, em seguida, envie a solicitação de método. O resultado bem-sucedido é uma resposta `200 OK `com uma carga no seguinte formato:
```
{
"SequenceNumber": "49559409944537880850133345460169886593573102115167928386",
"ShardId": "shardId-000000000004"
}
```
**Como configurar e testar o método `PUT /streams/{stream-name}/records` para invocar `PutRecords` no Kinesis**
1. Selecione o recurso **/records** e **Criar método**.
1. Em **Tipo de método**, selecione **PUT**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **PutRecords**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione os seguintes **parâmetros de cabeçalhos de solicitação de URL**:
```
Content-Type: 'x-amz-json-1.1'
```
A tarefa segue o mesmo procedimento para configurar o mapeamento do parâmetro de solicitação para o método `GET /streams`.
1. Adicione o seguinte modelo de mapeamento para associar dados na solicitação do método `PUT /streams/{stream-name}/records` à solicitação de integração correspondente de `POST /?Action=PutRecords`:
```
{
"StreamName": "$input.params('stream-name')",
"Records": [
#foreach($elem in $input.path('$.records'))
{
"Data": "$util.base64Encode($elem.data)",
"PartitionKey": "$elem.partition-key"
}#if($foreach.hasNext),#end
#end
]
}
```
Esse modelo de mapeamento pressupõe que a carga da solicitação do método pode ser modelada pelo seguinte esquema JSON:
```
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "PutRecords proxy payload data",
"type": "object",
"properties": {
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"data": { "type": "string" },
"partition-key": { "type": "string" }
}
}
}
}
}
```
Você pode criar um modelo para incluir esse esquema e usar o modelo para facilitar a geração do modelo de mapeamento. No entanto, pode gerar um modelo de mapeamento sem usar qualquer modelo.
Neste tutorial, usamos dois formatos de carga um pouco diferentes para ilustrar que um desenvolvedor de API pode optar por expor o formato de dados de backend ao cliente ou ocultá-lo do cliente. Um formato é para o método `PUT /streams/{stream-name}/records` (acima). O outro formato é usado para o método `PUT /streams/{stream-name}/record` (no procedimento anterior). Em um ambiente de produção, você deve manter os dois formatos consistentes.
1.
Para testar o método `PUT /streams/{stream-name}/records`, defina a variável de caminho `stream-name` como um fluxo existente, forneça a carga a seguir e envie a solicitação de método.
```
{
"records": [
{
"data": "some data",
"partition-key": "some key"
},
{
"data": "some other data",
"partition-key": "some key"
}
]
}
```
O resultado bem-sucedido é uma resposta 200 OK com uma carga semelhante à saída a seguir:
```
{
"FailedRecordCount": 0,
"Records": [
{
"SequenceNumber": "49559409944537880850133345460167468741933742152373764162",
"ShardId": "shardId-000000000004"
},
{
"SequenceNumber": "49559409944537880850133345460168677667753356781548470338",
"ShardId": "shardId-000000000004"
}
]
}
```
**Como configurar e testar o método `GET /streams/{stream-name}/sharditerator`, invoque `GetShardIterator` no Kinesis**
O método `GET /streams/{stream-name}/sharditerator` é um método auxiliar para adquirir um iterador de fragmentos necessário antes de chamar o método `GET /streams/{stream-name}/records`.
1. Selecione o recurso **/sharditerator** e **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **GetShardIterator**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Selecione **Parâmetros de string de consulta de URL**.
A ação `GetShardIterator` requer uma entrada de um valor ShardId. Para transmitir um valor `ShardId` fornecido pelo cliente, adicionamos um parâmetro de consulta `shard-id` à solicitação de método, conforme mostrado na etapa a seguir.
1. Escolha **Add query string** (Adicionar string de consulta).
1. Em **Nome**, digite **shard-id**.
1. Mantenha **Obrigatório** e **Armazenamento em cache** desativados.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione o modelo de mapeamento a seguir para gerar a entrada necessária (`ShardId` e `StreamName`) à ação `GetShardIterator` dos parâmetros `shard-id` e `stream-name` da solicitação de método. Além disso, o modelo de mapeamento também define `ShardIteratorType` como `TRIM_HORIZON` como um padrão.
```
{
"ShardId": "$input.params('shard-id')",
"ShardIteratorType": "TRIM_HORIZON",
"StreamName": "$input.params('stream-name')"
}
```
1. Usando a opção **Test (Testar)** no console do API Gateway, insira um nome de stream existente como o valor da variável `stream-name` **Path (Caminho)**, defina `shard-id` **Query string (String de consulta)** como um valor `ShardId` existente (por exemplo, `shard-000000000004`), e escolha **Test (Testar)**.
A carga da resposta bem-sucedida é semelhante à saída a seguir:
```
{
"ShardIterator": "AAAAAAAAAAFYVN3VlFy..."
}
```
Anote o valor de `ShardIterator`. Você precisa dela para obter registros de um fluxo.
**Como configurar e testar o método `GET /streams/{stream-name}/records` para invocar a ação `GetRecords` no Kinesis**
1. Selecione o recurso **/records** e **Criar método**.
1. Em **Tipo de método**, selecione **GET**.
1. Em **Tipo de integração**, selecione **Serviço da AWS**.
1. Em **Região da AWS**, selecione a Região da AWS onde você criou o fluxo do Kinesis.
1. Em **AWS service (Serviço da AWS)**, selecione **Kinesis**.
1. Mantenha o **subdomínio da AWS** em branco.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Tipo de ação**, selecione **Usar nome da ação**.
1. Em **Nome da ação**, insira **GetRecords**.
1. Em **Perfil de execução**, digite o ARN para o perfil de execução.
1. Deixe o padrão de **Passagem** para **Manuseio de conteúdo**.
1. Escolha **Cabeçalhos de solicitação HTTP**.
A ação `GetRecords` requer uma entrada de um valor `ShardIterator`. Para transmitir um valor `ShardIterator` fornecido pelo cliente, adicionamos um parâmetro de cabeçalho `Shard-Iterator` à solicitação de método.
1. Escolha **Add header** (Adicionar cabeçalho).
1. Em **Nome**, digite **Shard-Iterator**.
1. Mantenha **Obrigatório** e **Armazenamento em cache** desativados.
1. Escolha **Criar método**.
1. Na seção **Solicitação de integração**, adicione o modelo de mapeamento do corpo a seguir para associar o valor do parâmetro de cabeçalho `Shard-Iterator` ao valor da propriedade `ShardIterator` da carga útil de JSON para a ação `GetRecords` no Kinesis.
```
{
"ShardIterator": "$input.params('Shard-Iterator')"
}
```
1. Usando a opção **Testar** no console do API Gateway, digite um nome de fluxo existente como o valor da variável **Caminho** de `stream-name`, defina o **Cabeçalho** de `Shard-Iterator` como o valor `ShardIterator` obtido da execução de teste do método `GET /streams/{stream-name}/sharditerator` (acima) e selecione **Testar**.
A carga da resposta bem-sucedida é semelhante à saída a seguir:
```
{
"MillisBehindLatest": 0,
"NextShardIterator": "AAAAAAAAAAF...",
"Records": [ ... ]
}
```
# Definições do OpenAPI de uma API demonstrativa como um proxy do Kinesis
Veja a seguir as definições do OpenAPI para a API demonstrativa como um proxy do Kinesis usado neste tutorial.
------
#### [ OpenAPI 3.0 ]
```
{
"openapi": "3.0.0",
"info": {
"title": "KinesisProxy",
"version": "2016-03-31T18:25:32Z"
},
"paths": {
"/streams/{stream-name}/sharditerator": {
"get": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "shard-id",
"in": "query",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetShardIterator",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardId\": \"$input.params('shard-id')\",\n \"ShardIteratorType\": \"TRIM_HORIZON\",\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/records": {
"get": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Shard-Iterator",
"in": "header",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardIterator\": \"$input.params('Shard-Iterator')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"put": {
"parameters": [
{
"name": "Content-Type",
"in": "header",
"schema": {
"type": "string"
}
},
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PutRecordsMethodRequestPayload"
}
},
"application/x-amz-json-1.1": {
"schema": {
"$ref": "#/components/schemas/PutRecordsMethodRequestPayload"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\",\n \"Records\": [\n {\n \"Data\": \"$util.base64Encode($elem.data)\",\n \"PartitionKey\": \"$elem.partition-key\"\n }#if($foreach.hasNext),#end\n ]\n}",
"application/x-amz-json-1.1": "{\n \"StreamName\": \"$input.params('stream-name')\",\n \"records\" : [\n {\n \"Data\" : \"$elem.data\",\n \"PartitionKey\" : \"$elem.partition-key\"\n }#if($foreach.hasNext),#end\n ]\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}": {
"get": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DescribeStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"post": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/CreateStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardCount\": 5,\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"delete": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
},
"400": {
"description": "400 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {}
},
"500": {
"description": "500 response",
"headers": {
"Content-Type": {
"schema": {
"type": "string"
}
}
},
"content": {}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DeleteStream",
"responses": {
"4\\d{2}": {
"statusCode": "400",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
},
"5\\d{2}": {
"statusCode": "500",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/record": {
"put": {
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecord",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\",\n \"Data\": \"$util.base64Encode($input.json('$.Data'))\",\n \"PartitionKey\": \"$input.path('$.PartitionKey')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams": {
"get": {
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Empty"
}
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/ListStreams",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
}
},
"components": {
"schemas": {
"Empty": {
"type": "object"
},
"PutRecordsMethodRequestPayload": {
"type": "object",
"properties": {
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"data": {
"type": "string"
},
"partition-key": {
"type": "string"
}
}
}
}
}
}
}
}
}
```
------
#### [ OpenAPI 2.0 ]
```
{
"swagger": "2.0",
"info": {
"version": "2016-03-31T18:25:32Z",
"title": "KinesisProxy"
},
"basePath": "/test",
"schemes": [
"https"
],
"paths": {
"/streams": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/ListStreams",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DescribeStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"post": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/CreateStream",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardCount\": 5,\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"delete": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
},
"headers": {
"Content-Type": {
"type": "string"
}
}
},
"400": {
"description": "400 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
},
"500": {
"description": "500 response",
"headers": {
"Content-Type": {
"type": "string"
}
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/DeleteStream",
"responses": {
"4\\d{2}": {
"statusCode": "400",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
},
"default": {
"statusCode": "200",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
},
"5\\d{2}": {
"statusCode": "500",
"responseParameters": {
"method.response.header.Content-Type": "integration.response.header.Content-Type"
}
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/record": {
"put": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecord",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\",\n \"Data\": \"$util.base64Encode($input.json('$.Data'))\",\n \"PartitionKey\": \"$input.path('$.PartitionKey')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/records": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "Shard-Iterator",
"in": "header",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardIterator\": \"$input.params('Shard-Iterator')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
},
"put": {
"consumes": [
"application/json",
"application/x-amz-json-1.1"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "Content-Type",
"in": "header",
"required": false,
"type": "string"
},
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
},
{
"in": "body",
"name": "PutRecordsMethodRequestPayload",
"required": true,
"schema": {
"$ref": "#/definitions/PutRecordsMethodRequestPayload"
}
},
{
"in": "body",
"name": "PutRecordsMethodRequestPayload",
"required": true,
"schema": {
"$ref": "#/definitions/PutRecordsMethodRequestPayload"
}
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/PutRecords",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"StreamName\": \"$input.params('stream-name')\",\n \"Records\": [\n {\n \"Data\": \"$util.base64Encode($elem.data)\",\n \"PartitionKey\": \"$elem.partition-key\"\n }#if($foreach.hasNext),#end\n ]\n}",
"application/x-amz-json-1.1": "{\n \"StreamName\": \"$input.params('stream-name')\",\n \"records\" : [\n {\n \"Data\" : \"$elem.data\",\n \"PartitionKey\" : \"$elem.partition-key\"\n }#if($foreach.hasNext),#end\n ]\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
},
"/streams/{stream-name}/sharditerator": {
"get": {
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"parameters": [
{
"name": "stream-name",
"in": "path",
"required": true,
"type": "string"
},
{
"name": "shard-id",
"in": "query",
"required": false,
"type": "string"
}
],
"responses": {
"200": {
"description": "200 response",
"schema": {
"$ref": "#/definitions/Empty"
}
}
},
"x-amazon-apigateway-integration": {
"type": "aws",
"credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole",
"uri": "arn:aws:apigateway:us-east-1:kinesis:action/GetShardIterator",
"responses": {
"default": {
"statusCode": "200"
}
},
"requestParameters": {
"integration.request.header.Content-Type": "'application/x-amz-json-1.1'"
},
"requestTemplates": {
"application/json": "{\n \"ShardId\": \"$input.params('shard-id')\",\n \"ShardIteratorType\": \"TRIM_HORIZON\",\n \"StreamName\": \"$input.params('stream-name')\"\n}"
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST"
}
}
}
},
"definitions": {
"Empty": {
"type": "object"
},
"PutRecordsMethodRequestPayload": {
"type": "object",
"properties": {
"records": {
"type": "array",
"items": {
"type": "object",
"properties": {
"data": {
"type": "string"
},
"partition-key": {
"type": "string"
}
}
}
}
}
}
}
}
```
------
# Tutorial: como criar uma API REST usando SDKs da AWS ou a AWS CLI
Use o tutorial a seguir para criar uma API PetStore compatível com os métodos `GET /pets` e `GET /pets/{petId}`. Os dois métodos são integrados ao endpoint HTTP. É possível seguir este tutorial usando o AWS SDK para JavaScript, o SDK para Python (Boto3) ou a AWS CLI. Use as seguintes funções ou comandos para configurar sua API:
------
#### [ JavaScript v3 ]
+ [ CreateRestApiCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/CreateRestApiCommand/)
+ [ CreateResourceCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/CreateResourceCommand/)
+ [ PutMethodCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/PutMethodCommand/)
+ [ PutMethodResponseCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/PutMethodResponseCommand/)
+ [ PutIntegrationCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/PutIntegrationCommand/)
+ [ PutIntegrationResponseCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/PutIntegrationResponseCommand/)
+ [ CreateDeploymentCommand](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/api-gateway/command/CreateDeploymentCommand/)
------
#### [ Python ]
+ [ create\$1rest\$1api](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/create_rest_api.html)
+ [ create\$1resource](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/create_resource.html)
+ [ put\$1method](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/put_method.html)
+ [ put\$1method\$1response](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/put_method_response.html)
+ [ put\$1integration](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/put_integration.html)
+ [ put\$1integration\$1response](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/put_integration_response.html)
+ [ create\$1deployment](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/apigateway/client/create_deployment.html)
------
#### [ AWS CLI ]
+ [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)
+ [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html)
+ [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html)
+ [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)
+ [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html)
+ [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)
+ [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html)
------
Para saber mais sobre o AWS SDK para JavaScript v3, consulte [What's the AWS SDK for JavaScript?](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/welcome.html). Para saber mais sobre o SDK for Python (Boto3), consulte [AWS SDK para Python (Boto3)](https://docs.aws.amazon.com/pythonsdk). Para obter mais informações sobre a AWS CLI, consulte [O que é a AWS CLI?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).
## Configurar uma API PetStore otimizada para bordas
Neste tutorial, os exemplos de comandos usam valores de espaço reservado para IDs de valor, como ID de API e ID de recurso. Durante a conclusão do tutorial, substitua os valores de exemplo por seus próprios valores.
**Como configurar uma API PetStore otimizada para bordas usando AWS SDKs**
1. Use o seguinte exemplo para criar uma entidade `RestApi`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, CreateRestApiCommand} from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new CreateRestApiCommand({
name: "Simple PetStore (JavaScript v3 SDK)",
description: "Demo API created using the AWS SDK for JavaScript v3",
version: "0.00.001",
binaryMediaTypes: [
'*']
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.error(Couldn't create API:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna o ID da API e o ID do recurso-raiz da API em uma saída como a seguinte:
```
{
id: 'abc1234',
name: 'PetStore (JavaScript v3 SDK)',
description: 'Demo API created using the AWS SDK for node.js',
createdDate: 2017-09-05T19:32:35.000Z,
version: '0.00.001',
rootResourceId: 'efg567'
binaryMediaTypes: [ '*' ]
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.create_rest_api(
name='Simple PetStore (Python SDK)',
description='Demo API created using the AWS SDK for Python',
version='0.00.001',
binaryMediaTypes=[
'*'
]
)
except botocore.exceptions.ClientError as error:
logger.exception("Couldn't create REST API %s.", error)
raise
attribute=["id","name","description","createdDate","version","binaryMediaTypes","apiKeySource","endpointConfiguration","disableExecuteApiEndpoint","rootResourceId"]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna o ID da API e o ID do recurso-raiz da API em uma saída como a seguinte:
```
{'id': 'abc1234', 'name': 'Simple PetStore (Python SDK)', 'description': 'Demo API created using the AWS SDK for Python', 'createdDate': datetime.datetime(2024, 4, 3, 14, 31, 39, tzinfo=tzlocal()), 'version': '0.00.001', 'binaryMediaTypes': ['*'], 'apiKeySource': 'HEADER', 'endpointConfiguration': {'types': ['EDGE']}, 'disableExecuteApiEndpoint': False, 'rootResourceId': 'efg567'}
```
------
#### [ AWS CLI ]
```
aws apigateway create-rest-api --name 'Simple PetStore (AWS CLI)' --region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"id": "abcd1234",
"name": "Simple PetStore (AWS CLI)",
"createdDate": "2022-12-15T08:07:04-08:00",
"apiKeySource": "HEADER",
"endpointConfiguration": {
"types": [
"EDGE"
]
},
"disableExecuteApiEndpoint": false,
"rootResourceId": "efg567"
}
```
------
A API criada tem um ID de API `abcd1234` e um ID de recurso-raiz de `efg567`. Você usa esses valores na configuração da sua API.
1. Depois, anexe um recurso filho sob a raiz e especifique o `RootResourceId` como o valor da propriedade `parentId`. Use o seguinte exemplo para criar um recurso `/pets` para a API:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, CreateResourceCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new CreateResourceCommand({
restApiId: 'abcd1234',
parentId: 'efg567',
pathPart: 'pets'
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The '/pets' resource setup failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna informações sobre seu recurso em uma saída como a seguinte:
```
{
"path": "/pets",
"pathPart": "pets",
"id": "aaa111",
"parentId": "efg567'"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.create_resource(
restApiId='abcd1234',
parentId='efg567',
pathPart='pets'
)
except botocore.exceptions.ClientError as error:
logger.exception("The '/pets' resource setup failed: %s.", error)
raise
attribute=["id","parentId", "pathPart", "path",]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna informações sobre seu recurso em uma saída como a seguinte:
```
{'id': 'aaa111', 'parentId': 'efg567', 'pathPart': 'pets', 'path': '/pets'}
```
------
#### [ AWS CLI ]
```
aws apigateway create-resource --rest-api-id abcd1234 \
--region us-west-2 \
--parent-id efg567 \
--path-part pets
```
Veja a seguir a saída desse comando:
```
{
"id": "aaa111",
"parentId": "efg567",
"pathPart": "pets",
"path": "/pets"
}
```
------
O recurso `/pets` criado tem o ID de recurso de `aaa111`. Você usa esse valor na configuração da sua API.
1. Depois, anexe um recurso filho sobre o recurso `/pets`. Esse recurso `/{petId}` tem um parâmetro de caminho para `{petId}`. Para incluir um caminho em um parâmetro de caminho, coloque-o entre chaves, `{ }`. Use o seguinte exemplo para criar um recurso `/pets/{petId}` para a API:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, CreateResourceCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new CreateResourceCommand({
restApiId: 'abcd1234',
parentId: 'aaa111',
pathPart: '{petId}'
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The '/pets/{petId}' resource setup failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna informações sobre seu recurso em uma saída como a seguinte:
```
{
"path": "/pets/{petId}",
"pathPart": "{petId}",
"id": "bbb222",
"parentId": "aaa111'"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.create_resource(
restApiId='abcd1234',
parentId='aaa111',
pathPart='{petId}'
)
except botocore.exceptions.ClientError as error:
logger.exception("The '/pets/{petId}' resource setup failed: %s.", error)
raise
attribute=["id","parentId", "pathPart", "path",]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna informações sobre seu recurso em uma saída como a seguinte:
```
{'id': 'bbb222', 'parentId': 'aaa111', 'pathPart': '{petId}', 'path': '/pets/{petId}'}
```
------
#### [ AWS CLI ]
```
aws apigateway create-resource --rest-api-id abcd1234 \
--region us-west-2 \
--parent-id aaa111 \
--path-part '{petId}'
```
Veja a seguir a saída desse comando:
```
{
"id": "bbb222",
"parentId": "aaa111",
"path": "/pets/{petId}",
"pathPart": "{petId}"
}
```
------
O recurso `/pets/{petId}` criado tem o ID de recurso de `bbb222`. Você usa esse valor na configuração da sua API.
1. Nas duas etapas a seguir, adicione métodos HTTP aos recursos. Neste tutorial, você definirá os métodos para ter acesso aberto, configurando `authorization-type` como `NONE`. Para permitir que somente usuários autenticados chamem o método, você pode usar as funções e políticas do IAM, um autorizador do Lambda (anteriormente conhecido como autorizador personalizado) ou um grupo de usuários do Amazon Cognito. Para ter mais informações, consulte [Controlar e gerenciar o acesso a APIs REST no API Gateway](apigateway-control-access-to-api.md).
Use o seguinte exemplo para adicionar o método HTTP `GET` ao recurso `/pets`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutMethodCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutMethodCommand({
restApiId: 'abcd1234',
resourceId: 'aaa111',
httpMethod: 'GET',
authorizationType: 'NONE'
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The 'GET /pets' method setup failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_method(
restApiId='abcd1234',
resourceId='aaa111',
httpMethod='GET',
authorizationType='NONE'
)
except botocore.exceptions.ClientError as error:
logger.exception("The 'GET /pets' method setup failed: %s", error)
raise
attribute=["httpMethod","authorizationType","apiKeyRequired"]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'httpMethod': 'GET', 'authorizationType': 'NONE', 'apiKeyRequired': False}
```
------
#### [ AWS CLI ]
```
aws apigateway put-method --rest-api-id abcd1234 \
--resource-id aaa111 \
--http-method GET \
--authorization-type "NONE" \
--region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"httpMethod": "GET",
"authorizationType": "NONE",
"apiKeyRequired": false
}
```
------
1. Use o seguinte exemplo para adicionar o método HTTP `GET` ao recurso `/pets/{petId}`, definir a propriedade `requestParameters` e passar o valor `petId` fornecido pelo cliente para o backend:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutMethodCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutMethodCommand({
restApiId: 'abcd1234',
resourceId: 'bbb222',
httpMethod: 'GET',
authorizationType: 'NONE'
requestParameters: {
"method.request.path.petId" : true
}
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The 'GET /pets/{petId}' method setup failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"apiKeyRequired": false,
"httpMethod": "GET",
"authorizationType": "NONE",
"requestParameters": {
"method.request.path.petId": true
}
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_method(
restApiId='abcd1234',
resourceId='bbb222',
httpMethod='GET',
authorizationType='NONE',
requestParameters={
"method.request.path.petId": True
}
)
except botocore.exceptions.ClientError as error:
logger.exception("The 'GET /pets/{petId}' method setup failed: %s", error)
raise
attribute=["httpMethod","authorizationType","apiKeyRequired", "requestParameters" ]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'httpMethod': 'GET', 'authorizationType': 'NONE', 'apiKeyRequired': False, 'requestParameters': {'method.request.path.petId': True}}
```
------
#### [ AWS CLI ]
```
aws apigateway put-method --rest-api-id abcd1234 \
--resource-id bbb222 --http-method GET \
--authorization-type "NONE" \
--region us-west-2 \
--request-parameters method.request.path.petId=true
```
Veja a seguir a saída desse comando:
```
{
"httpMethod": "GET",
"authorizationType": "NONE",
"apiKeyRequired": false,
"requestParameters": {
"method.request.path.petId": true
}
}
```
------
1. Use o seguinte exemplo para adicionar a resposta de método 200 OK para o método `GET /pets`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutMethodResponseCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutMethodResponseCommand({
restApiId: 'abcd1234',
resourceId: 'aaa111',
httpMethod: 'GET',
statusCode: '200'
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("Set up the 200 OK response for the 'GET /pets' method failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"statusCode": "200"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_method_response(
restApiId='abcd1234',
resourceId='aaa111',
httpMethod='GET',
statusCode='200'
)
except botocore.exceptions.ClientError as error:
logger.exception("Set up the 200 OK response for the 'GET /pets' method failed %s.", error)
raise
attribute=["statusCode"]
filtered_result ={key:result[key] for key in attribute}
logger.info(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'statusCode': '200'}
```
------
#### [ AWS CLI ]
```
aws apigateway put-method-response --rest-api-id abcd1234 \
--resource-id aaa111 --http-method GET \
--status-code 200 --region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"statusCode": "200"
}
```
------
1. Use o seguinte exemplo para adicionar a resposta de método 200 OK para o método `GET /pets/{petId}`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutMethodResponseCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutMethodResponseCommand({
restApiId: 'abcd1234',
resourceId: 'bbb222',
httpMethod: 'GET',
statusCode: '200'
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("Set up the 200 OK response for the 'GET /pets/{petId}' method failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"statusCode": "200"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_method_response(
restApiId='abcd1234',
resourceId='bbb222',
httpMethod='GET',
statusCode='200'
)
except botocore.exceptions.ClientError as error:
logger.exception("Set up the 200 OK response for the 'GET /pets/{petId}' method failed %s.", error)
raise
attribute=["statusCode"]
filtered_result ={key:result[key] for key in attribute}
logger.info(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'statusCode': '200'}
```
------
#### [ AWS CLI ]
```
aws apigateway put-method-response --rest-api-id abcd1234 \
--resource-id bbb222 --http-method GET \
--status-code 200 --region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"statusCode": "200"
}
```
------
1. Use o exemplo a seguir para configurar uma integração para o método `GET /pets` com um endpoint HTTP. O endpoint HTTPS é `http://petstore-demo-endpoint.execute-api.com/petstore/pets`.
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutIntegrationCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutIntegrationCommand({
restApiId: 'abcd1234',
resourceId: 'aaa111',
httpMethod: 'GET',
type: 'HTTP',
integrationHttpMethod: 'GET',
uri: 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("Set up the integration of the 'GET /pets' method of the API failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"httpMethod": "GET",
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"type": "HTTP",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"cacheNamespace": "ccc333"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_integration(
restApiId='abcd1234',
resourceId='aaa111',
httpMethod='GET',
type='HTTP',
integrationHttpMethod='GET',
uri='http://petstore-demo-endpoint.execute-api.com/petstore/pets'
)
except botocore.exceptions.ClientError as error:
logger.exception("Set up the integration of the 'GET /' method of the API failed %s.", error)
raise
attribute=["httpMethod","passthroughBehavior","cacheKeyParameters", "type", "uri", "cacheNamespace"]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'httpMethod': 'GET', 'passthroughBehavior': 'WHEN_NO_MATCH', 'cacheKeyParameters': [], 'type': 'HTTP', 'uri': 'http://petstore-demo-endpoint.execute-api.com/petstore/pets', 'cacheNamespace': 'ccc333'}
```
------
#### [ AWS CLI ]
```
aws apigateway put-integration --rest-api-id abcd1234 \
--resource-id aaa111 --http-method GET --type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' \
--region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"type": "HTTP",
"httpMethod": "GET",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"connectionType": "INTERNET",
"passthroughBehavior": "WHEN_NO_MATCH",
"timeoutInMillis": 29000,
"cacheNamespace": "6sxz2j",
"cacheKeyParameters": []
}
```
------
1. Use o exemplo a seguir para configurar uma integração para o método `GET /pets/{petId}` com um endpoint HTTP. O endpoint HTTPS é `http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}`. Nesta etapa, associe o parâmetro de caminho `petId` ao parâmetro de caminho no endpoint de integração de `id`.
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutIntegrationCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutIntegrationCommand({
restApiId: 'abcd1234',
resourceId: 'bbb222',
httpMethod: 'GET',
type: 'HTTP',
integrationHttpMethod: 'GET',
uri: 'http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}'
requestParameters: {
"integration.request.path.id": "method.request.path.petId"
}
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("Set up the integration of the 'GET /pets/{petId}' method of the API failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"httpMethod": "GET",
"passthroughBehavior": "WHEN_NO_MATCH",
"cacheKeyParameters": [],
"type": "HTTP",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}",
"cacheNamespace": "ddd444",
"requestParameters": {
"integration.request.path.id": "method.request.path.petId"
}
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_integration(
restApiId='ieps9b05sf',
resourceId='t8zeb4',
httpMethod='GET',
type='HTTP',
integrationHttpMethod='GET',
uri='http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}',
requestParameters={
"integration.request.path.id": "method.request.path.petId"
}
)
except botocore.exceptions.ClientError as error:
logger.exception("Set up the integration of the 'GET /pets/{petId}' method of the API failed %s.", error)
raise
attribute=["httpMethod","passthroughBehavior","cacheKeyParameters", "type", "uri", "cacheNamespace", "requestParameters"]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'httpMethod': 'GET', 'passthroughBehavior': 'WHEN_NO_MATCH', 'cacheKeyParameters': [], 'type': 'HTTP', 'uri': 'http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}', 'cacheNamespace': 'ddd444', 'requestParameters': {'integration.request.path.id': 'method.request.path.petId'}}}
```
------
#### [ AWS CLI ]
```
aws apigateway put-integration --rest-api-id abcd1234 \
--resource-id bbb222 --http-method GET --type HTTP \
--integration-http-method GET \
--uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}' \
--request-parameters '{"integration.request.path.id":"method.request.path.petId"}' \
--region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"type": "HTTP",
"httpMethod": "GET",
"uri": "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}",
"connectionType": "INTERNET",
"requestParameters": {
"integration.request.path.id": "method.request.path.petId"
},
"passthroughBehavior": "WHEN_NO_MATCH",
"timeoutInMillis": 29000,
"cacheNamespace": "rjkmth",
"cacheKeyParameters": []
}
```
------
1. Use o seguinte exemplo para adicionar a resposta da integração para a integração `GET /pets`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutIntegrationResponseCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutIntegrationResponseCommand({
restApiId: 'abcd1234',
resourceId: 'aaa111',
httpMethod: 'GET',
statusCode: '200',
selectionPattern: ''
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The 'GET /pets' method integration response setup failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_integration_response(
restApiId='abcd1234',
resourceId='aaa111',
httpMethod='GET',
statusCode='200',
selectionPattern='',
)
except botocore.exceptions.ClientError as error:
logger.exception("Set up the integration response of the 'GET /pets' method of the API failed: %s", error)
raise
attribute=["selectionPattern","statusCode"]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'selectionPattern': "", 'statusCode': '200'}
```
------
#### [ AWS CLI ]
```
aws apigateway put-integration-response --rest-api-id abcd1234 \
--resource-id aaa111 --http-method GET \
--status-code 200 --selection-pattern "" \
--region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"statusCode": "200",
"selectionPattern": ""
}
```
------
1. Use o seguinte exemplo para adicionar a resposta da integração para a integração `GET /pets/{petId}`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, PutIntegrationResponseCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new PutIntegrationResponseCommand({
restApiId: 'abcd1234',
resourceId: 'bbb222',
httpMethod: 'GET',
statusCode: '200',
selectionPattern: ''
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The 'GET /pets/{petId}' method integration response setup failed:\n", err)
}
})();
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{
"selectionPattern": "",
"statusCode": "200"
}
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.put_integration_response(
restApiId='abcd1234',
resourceId='bbb222',
httpMethod='GET',
statusCode='200',
selectionPattern='',
)
except botocore.exceptions.ClientError as error:
logger.exception("Set up the integration response of the 'GET /pets/{petId}' method of the API failed: %s", error)
raise
attribute=["selectionPattern","statusCode"]
filtered_result ={key:result[key] for key in attribute}
print(filtered_result)
```
Uma chamada bem-sucedida retorna a seguinte saída:
```
{'selectionPattern': "", 'statusCode': '200'}
```
------
#### [ AWS CLI ]
```
aws apigateway put-integration-response --rest-api-id abcd1234 \
--resource-id bbb222 --http-method GET
--status-code 200 --selection-pattern ""
--region us-west-2
```
Veja a seguir a saída desse comando:
```
{
"statusCode": "200",
"selectionPattern": ""
}
```
------
Depois que você criar a resposta de integração, sua API poderá consultar os animais de estimação disponíveis no site da PetStore e visualizar um animal de estimação individual de um identificador especificado. Antes que sua API possa ser chamada pelos clientes, você deve implantá-la. Recomendamos que você teste a API antes de implantá-la.
1. Use o seguinte exemplo para testar o método `GET /pets`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, TestInvokeMethodCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new TestInvokeMethodCommand({
restApiId: 'abcd1234',
resourceId: 'aaa111',
httpMethod: 'GET',
pathWithQueryString: '/',
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The test on 'GET /pets' method failed:\n", err)
}
})();
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.test_invoke_method(
restApiId='abcd1234',
resourceId='aaa111',
httpMethod='GET',
pathWithQueryString='/',
)
except botocore.exceptions.ClientError as error:
logger.exception("Test invoke method on 'GET /pets' failed: %s", error)
raise
print(result)
```
------
#### [ AWS CLI ]
```
aws apigateway test-invoke-method --rest-api-id abcd1234 /
--resource-id aaa111 /
--http-method GET /
--path-with-query-string '/'
```
------
1. Use o seguinte exemplo para testar o método `GET /pets/{petId}` usando 3 como `petId`:
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, TestInvokeMethodCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new TestInvokeMethodCommand({
restApiId: 'abcd1234',
resourceId: 'bbb222',
httpMethod: 'GET',
pathWithQueryString: '/pets/3',
});
try {
const results = await apig.send(command)
console.log(results)
} catch (err) {
console.log("The test on 'GET /pets/{petId}' method failed:\n", err)
}
})();
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.test_invoke_method(
restApiId='abcd1234',
resourceId='bbb222',
httpMethod='GET',
pathWithQueryString='/pets/3',
)
except botocore.exceptions.ClientError as error:
logger.exception("Test invoke method on 'GET /pets/{petId}' failed: %s", error)
raise
print(result)
```
------
#### [ AWS CLI ]
```
aws apigateway test-invoke-method --rest-api-id abcd1234 /
--resource-id bbb222 /
--http-method GET /
--path-with-query-string '/pets/3'
```
------
Depois de testar a API com sucesso, implante-a em um estágio.
1. Use o exemplo a seguir para implantar a API em um estágio chamado `test`. Quando você implanta a API em um estágio, os chamadores da API podem invocá-la.
------
#### [ JavaScript v3 ]
```
import {APIGatewayClient, CreateDeploymentCommand } from "@aws-sdk/client-api-gateway";
(async function (){
const apig = new APIGatewayClient({region:"us-east-1"});
const command = new CreateDeploymentCommand({
restApiId: 'abcd1234',
stageName: 'test',
stageDescription: 'test deployment'
});
try {
const results = await apig.send(command)
console.log("Deploying API succeeded\n", results)
} catch (err) {
console.log("Deploying API failed:\n", err)
}
})();
```
------
#### [ Python ]
```
import botocore
import boto3
import logging
logger = logging.getLogger()
apig = boto3.client('apigateway')
try:
result = apig.create_deployment(
restApiId='ieps9b05sf',
stageName='test',
stageDescription='my test stage',
)
except botocore.exceptions.ClientError as error:
logger.exception("Error deploying stage %s.", error)
raise
print('Deploying API succeeded')
print(result)
```
------
#### [ AWS CLI ]
```
aws apigateway create-deployment --rest-api-id abcd1234 \
--region us-west-2 \
--stage-name test \
--stage-description 'Test stage' \
--description 'First deployment'
```
Veja a seguir a saída desse comando:
```
{
"id": "ab1c1d",
"description": "First deployment",
"createdDate": "2022-12-15T08:44:13-08:00"
}
```
------
Sua API agora pode ser chamada pelos clientes. Você pode testar essa API inserindo o URL `https://abcd1234.execute-api.us-west-2.amazonaws.com/test/pets` em um navegador e substituindo `abcd1234` pelo identificador da sua API.
Para ver mais exemplos de como criar ou atualizar uma API usando AWS SDKs ou a AWS CLI, consulte [Actions for API Gateway using AWS SDKs](https://docs.aws.amazon.com/code-library/latest/ug/api-gateway_code_examples_actions.html).
## Automatizar a configuração da API
Em vez de criar a API passo a passo, você pode automatizar a criação e a limpeza de recursos da AWS usando a OpenAPI, o CloudFormation ou o Terraform para criar a API.
### Definição da OpenAPI 3.0
Você pode importar uma definição da OpenAPI para o API Gateway. Para ter mais informações, consulte [Desenvolver APIs REST usando OpenAPI no API Gateway](api-gateway-import-api.md).
```
{
"openapi" : "3.0.1",
"info" : {
"title" : "Simple PetStore (OpenAPI)",
"description" : "Demo API created using OpenAPI",
"version" : "2024-05-24T20:39:34Z"
},
"servers" : [ {
"url" : "{basePath}",
"variables" : {
"basePath" : {
"default" : "Prod"
}
}
} ],
"paths" : {
"/pets" : {
"get" : {
"responses" : {
"200" : {
"description" : "200 response",
"content" : { }
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"passthroughBehavior" : "when_no_match",
"timeoutInMillis" : 29000
}
}
},
"/pets/{petId}" : {
"get" : {
"parameters" : [ {
"name" : "petId",
"in" : "path",
"required" : true,
"schema" : {
"type" : "string"
}
} ],
"responses" : {
"200" : {
"description" : "200 response",
"content" : { }
}
},
"x-amazon-apigateway-integration" : {
"type" : "http",
"httpMethod" : "GET",
"uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}",
"responses" : {
"default" : {
"statusCode" : "200"
}
},
"requestParameters" : {
"integration.request.path.id" : "method.request.path.petId"
},
"passthroughBehavior" : "when_no_match",
"timeoutInMillis" : 29000
}
}
}
},
"components" : { }
}
```
### Modelo AWS CloudFormation
Para implantar um modelo do CloudFormation, consulte [Criar uma pilha no console do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html).
```
AWSTemplateFormatVersion: 2010-09-09
Resources:
Api:
Type: 'AWS::ApiGateway::RestApi'
Properties:
Name: Simple PetStore (AWS CloudFormation)
PetsResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !GetAtt Api.RootResourceId
PathPart: 'pets'
PetIdResource:
Type: 'AWS::ApiGateway::Resource'
Properties:
RestApiId: !Ref Api
ParentId: !Ref PetsResource
PathPart: '{petId}'
PetsMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetsResource
HttpMethod: GET
AuthorizationType: NONE
Integration:
Type: HTTP
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/
IntegrationResponses:
- StatusCode: '200'
MethodResponses:
- StatusCode: '200'
PetIdMethodGet:
Type: 'AWS::ApiGateway::Method'
Properties:
RestApiId: !Ref Api
ResourceId: !Ref PetIdResource
HttpMethod: GET
AuthorizationType: NONE
RequestParameters:
method.request.path.petId: true
Integration:
Type: HTTP
IntegrationHttpMethod: GET
Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}
RequestParameters:
integration.request.path.id: method.request.path.petId
IntegrationResponses:
- StatusCode: '200'
MethodResponses:
- StatusCode: '200'
ApiDeployment:
Type: 'AWS::ApiGateway::Deployment'
DependsOn:
- PetsMethodGet
Properties:
RestApiId: !Ref Api
StageName: Prod
Outputs:
ApiRootUrl:
Description: Root Url of the API
Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/Prod'
```
### Configuração do Terraform
Para obter mais informações sobre o Terraform, consulte [Terraform](https://developer.hashicorp.com/terraform/intro).
```
provider "aws" {
region = "us-east-1" # Update with your desired region
}
resource "aws_api_gateway_rest_api" "Api" {
name = "Simple PetStore (Terraform)"
description = "Demo API created using Terraform"
}
resource "aws_api_gateway_resource" "petsResource"{
rest_api_id = aws_api_gateway_rest_api.Api.id
parent_id = aws_api_gateway_rest_api.Api.root_resource_id
path_part = "pets"
}
resource "aws_api_gateway_resource" "petIdResource"{
rest_api_id = aws_api_gateway_rest_api.Api.id
parent_id = aws_api_gateway_resource.petsResource.id
path_part = "{petId}"
}
resource "aws_api_gateway_method" "petsMethodGet" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petsResource.id
http_method = "GET"
authorization = "NONE"
}
resource "aws_api_gateway_method_response" "petsMethodResponseGet" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petsResource.id
http_method = aws_api_gateway_method.petsMethodGet.http_method
status_code ="200"
}
resource "aws_api_gateway_integration" "petsIntegration" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petsResource.id
http_method = aws_api_gateway_method.petsMethodGet.http_method
type = "HTTP"
uri = "http://petstore-demo-endpoint.execute-api.com/petstore/pets"
integration_http_method = "GET"
depends_on = [aws_api_gateway_method.petsMethodGet]
}
resource "aws_api_gateway_integration_response" "petsIntegrationResponse" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petsResource.id
http_method = aws_api_gateway_method.petsMethodGet.http_method
status_code = aws_api_gateway_method_response.petsMethodResponseGet.status_code
}
resource "aws_api_gateway_method" "petIdMethodGet" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petIdResource.id
http_method = "GET"
authorization = "NONE"
request_parameters = {"method.request.path.petId" = true}
}
resource "aws_api_gateway_method_response" "petIdMethodResponseGet" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petIdResource.id
http_method = aws_api_gateway_method.petIdMethodGet.http_method
status_code ="200"
}
resource "aws_api_gateway_integration" "petIdIntegration" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petIdResource.id
http_method = aws_api_gateway_method.petIdMethodGet.http_method
type = "HTTP"
uri = "http://petstore-demo-endpoint.execute-api.com/petstore/pets/{id}"
integration_http_method = "GET"
request_parameters = {"integration.request.path.id" = "method.request.path.petId"}
depends_on = [aws_api_gateway_method.petIdMethodGet]
}
resource "aws_api_gateway_integration_response" "petIdIntegrationResponse" {
rest_api_id = aws_api_gateway_rest_api.Api.id
resource_id = aws_api_gateway_resource.petIdResource.id
http_method = aws_api_gateway_method.petIdMethodGet.http_method
status_code = aws_api_gateway_method_response.petIdMethodResponseGet.status_code
}
resource "aws_api_gateway_deployment" "Deployment" {
rest_api_id = aws_api_gateway_rest_api.Api.id
depends_on = [aws_api_gateway_integration.petsIntegration,aws_api_gateway_integration.petIdIntegration ]
}
resource "aws_api_gateway_stage" "Stage" {
stage_name = "Prod"
rest_api_id = aws_api_gateway_rest_api.Api.id
deployment_id = aws_api_gateway_deployment.Deployment.id
}
```
# Tutorial: Crie uma API REST privada
Neste tutorial, você cria uma API REST privada. Os clientes podem acessar a API somente de dentro de sua Amazon VPC. A API é isolada da internet pública, que é um requisito de segurança comum.
Este tutorial leva aproximadamente 30 minutos para ser concluído. Primeiro, você usa um modelo do CloudFormation para criar uma Amazon VPC, um endpoint da VPC, uma função do AWS Lambda e executar uma instância do Amazon EC2 que você usará para testar sua API. Em seguida, use o Console de gerenciamento da AWS para criar uma API privada e anexar uma política de recursos que permita o acesso somente a partir do endpoint da VPC. Por fim, você testa a sua API.
![\[Visão geral da API privada que você cria neste tutorial.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/private-api-tutorial-diagram.png)
Para concluir esse tutorial, você precisa de uma conta da AWS e de um usuário do AWS Identity and Access Management com acesso ao console. Para obter mais informações, consulte [Configurar para usar o API Gateway](setting-up.md).
Neste tutorial, você usará o Console de gerenciamento da AWS. Para obter um modelo do CloudFormation que cria essa API e todos os recursos relacionados, consulte [template.yaml](samples/private-api-full-template.zip).
**Topics**
+ [Etapa 1: Criar dependências](#private-api-tutorial-create-dependencies)
+ [Etapa 2: Crie uma API privada](#private-api-tutorial-create-api)
+ [Etapa 3: Crie um método e integração](#private-api-tutorial-create-method)
+ [Etapa 4: Anexe uma política de recursos](#private-api-tutorial-attach-resource-policy)
+ [Etapa 5: Implante sua API](#private-api-tutorial-deploy-api)
+ [Etapa 6: Verifique se sua API não está acessível publicamente](#private-api-tutorial-test-private-api)
+ [Etapa 7: Conecte-se a uma instância em sua VPC e invoque sua API](#private-api-tutorial-connect-to-instance)
+ [Etapa 8: Limpar](#private-api-tutorial-cleanup)
+ [Próximas etapas: Automatize com CloudFormation](#private-api-tutorial-next-steps)
## Etapa 1: Criar dependências
Baixe e descompacte [este modelo do CloudFormation](samples/private-api-starter-template.zip). Você usa o modelo para criar todas as dependências para sua API privada, incluindo uma Amazon VPC, um endpoint da VPC e uma função do Lambda que serve como backend de sua API. Você cria a API privada mais tarde.
**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 **private-api-tutorial** 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 provisiona as dependências da sua API, o que pode levar alguns minutos. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, escolha **Outputs** (Saídas). Observe o ID de endpoint da VPC. Você precisa dele para as etapas posteriores neste tutorial.
## Etapa 2: Crie uma API privada
Crie uma API privada para permitir que somente clientes dentro de sua VPC a acessem.
**Para criar uma API privada**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Criar API**e, em seguida, para **API REST**, escolha **Criar**.
1. Em **API name (Nome da API)**, insira **private-api-tutorial**.
1. Em **Tipo de endpoint de API**, escolha **Privado**.
1. Em **IDs de endpoint da VPC**, insira o ID de endpoint da VPC em **Saídas** da pilha do CloudFormation.
1. Em **Tipo de endereço IP**, escolha **Dualstack**.
1. Selecione **Criar API**.
## Etapa 3: Crie um método e integração
Crie um método `GET` e uma integração do Lambda para lidar com solicitações `GET` para sua API. Quando um cliente invoca sua API, o API Gateway envia a solicitação para a função do Lambda criada na Etapa 1 e, em seguida, retorna uma resposta ao cliente.
**Para criar um método e 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 a API.
1. Escolha **Criar método**.
1. Em **Tipo de método**, selecione `GET`.
1. Em **Tipo de integração**, selecione **Função do Lambda**.
1. Ative **Integração de proxy do Lambda**. Com uma integração de proxy do Lambda, o API Gateway envia um evento para o Lambda com uma estrutura definida e transforma a resposta da função do Lambda em uma resposta HTTP.
1. Para **Lambda function** (Função do Lambda), escolha a função que criou com o modelo do CloudFormation na Etapa 1. O nome da função começa com **private-api-tutorial**.
1. Escolha **Criar método**.
## Etapa 4: Anexe uma política de recursos
Anexe uma [política de recursos](apigateway-resource-policies.md) à sua API, que permite que os clientes invoquem sua API somente por meio do endpoint da VPC. Para restringir ainda mais o acesso à sua API, você também pode configurar uma [ política de endpoint da VPC](apigateway-vpc-endpoint-policies.md) para o endpoint da VPC, mas isso não é necessário para este tutorial.
**Para anexar uma política de recursos**
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 a API.
1. Selecione **Política de recursos** e **Criar política**.
1. Insira a seguinte política. Substitua o *vpceID* pelo seu ID de endpoint da VPC em **Outputs** (Saídas) da sua pilha do CloudFormation.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/*",
"Condition": {
"StringNotEquals": {
"aws:sourceVpce": "vpce-abcd1234"
}
}
},
{
"Effect": "Allow",
"Principal": "*",
"Action": "execute-api:Invoke",
"Resource": "execute-api:/*"
}
]
}
```
------
1. Escolha **Salvar alterações**.
## Etapa 5: Implante sua API
Em seguida, implante sua API para torná-la disponível para clientes em sua Amazon VPC.
**Para implantar uma API**
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 a API.
1. Escolha **Implantar API**.
1. Em **Estágio**, selecione **Novo estágio**.
1. Em **Stage name (Nome do estágio)**, insira **test**.
1. (Opcional) Em **Description (Descrição)**, insira uma descrição.
1. Escolha **Deploy** (Implantar).
Agora você está pronto para testar sua API.
## Etapa 6: Verifique se sua API não está acessível publicamente
Use `curl` para verificar se você não pode invocar sua API fora da Amazon VPC.
**Para testar sua API**
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 a API.
1. No painel de navegação principal, selecione **Estágios** e escolha o estágio **testar**.
1. Em **Detalhes do estágio**, escolha o ícone de cópia para copiar o URL de invocação da API. O URL se parece com `https://abcdef123.execute-api.us-west-2.amazonaws.com/test`. O endpoint da VPC que foi criado na Etapa 1 tem o DNS privado ativado, portanto, você pode usar o URL fornecido para chamar sua API.
1. Use curl para tentar invocar sua API fora da VPC.
```
curl https://abcdef123.execute-api.us-west-2.amazonaws.com/test
```
O curl indica que o endpoint da sua API não pode ser resolvido. Se você receber uma resposta diferente, volte para a Etapa 2 e certifique-se de escolher **Privado** para o tipo de endpoint da API.
```
curl: (6) Could not resolve host: abcdef123.execute-api.us-west-2.amazonaws.com/test
```
Em seguida, conecte-se a uma instância do Amazon EC2 em sua VPC para chamar sua API.
## Etapa 7: Conecte-se a uma instância em sua VPC e invoque sua API
Em seguida, teste sua API de dentro da Amazon VPC. Para acessar sua API privada, conexte-se a uma instância do Amazon EC2 em sua VPC e, em seguida, use curl para chamar sua API. Use o Gerenciador de sessões do Systems Manager para se conectar à instância no navegador.
**Para testar sua API**
1. Abra o console do Amazon EC2 em [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/).
1. Selecione **Instances (Instâncias)**.
1. Escolha a instância chamada **private-api-tutorial** que você criou com o modelo do CloudFormation na Etapa 1.
1. Escolha **Conectar** e escolha **Session Manager**.
1. Escolha **Conectar** para executar uma sessão baseada em navegador na instância.
1. Na sessão do Session Manager, use curl para invocar sua API. Invoque sua API porque está usando uma instância na sua Amazon VPC.
```
curl https://abcdef123.execute-api.us-west-2.amazonaws.com/test
```
Verifique se você obtém a resposta `Hello from Lambda!`.
![\[Você usa o Session Manager para invocar sua API de dentro da Amazon VPC.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/private-api-tutorial-invoke.png)
Você criou com sucesso uma API que é acessível apenas a partir de sua Amazon VPC e, em seguida, verificou se ela funciona.
## Etapa 8: Limpar
Para evitar custos desnecessários, exclua os recursos que você criou como parte desse tutorial. As etapas a seguir excluem sua API REST e sua pilha do CloudFormation.
**Para excluir uma API REST**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Na página **APIs** , selecione uma API. Selecione **Ações da API**, **Excluir API** e, depois, confirme a escolha.
**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.
## Próximas etapas: Automatize com CloudFormation
Você pode automatizar a criação e a limpeza de todos os recursos da AWS envolvidos neste tutorial. Para obter um modelo do CloudFormation de exemplo completo, consulte [template.yaml](samples/private-api-full-template.zip).
# Tutoriais da API HTTP do Amazon API Gateway
Os tutoriais a seguir fornecem exercícios práticos para ajudar você a saber mais sobre as APIs HTTP do Amazon API Gateway.
**Topics**
+ [Tutorial: Crie uma API HTTP CRUD com o Lambda e o DynamoDB](http-api-dynamo-db.md)
+ [Tutorial: Crie uma API HTTP com uma integração privada a um serviço do Amazon ECS](http-api-private-integration.md)
# Tutorial: Crie uma API HTTP CRUD com o Lambda e o DynamoDB
Neste tutorial, você cria uma API sem servidor que cria, lê, atualiza e exclui itens de uma tabela do DynamoDB. O DynamoDB é um serviço de banco de dados NoSQL totalmente gerenciado que proporciona uma performance rápida e previsível com escalabilidade contínua. Este tutorial leva aproximadamente 30 minutos para ser concluído, e você pode fazê-lo no [nível gratuito da AWS](https://aws.amazon.com/free/).
Primeiro, você cria uma tabela do [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) usando o console do DynamoDB. Em seguida, você cria uma função do [Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) usando o console do AWS Lambda. Em seguida, crie uma API HTTP usando o console do API Gateway. Por fim, você testa a sua API.
Quando você invoca sua API HTTP, o API Gateway encaminha a solicitação para sua função do Lambda. A função do Lambda interage com o DynamoDB e retorna uma resposta ao API Gateway. O API Gateway retorna uma resposta para você.
![\[Visão geral da API HTTP que você cria neste tutorial.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ddb-crud.png)
Para concluir esse exercício, você precisa de uma conta da AWS e de um usuário do AWS Identity and Access Management com acesso ao console. Para obter mais informações, consulte [Configurar para usar o API Gateway](setting-up.md).
Neste tutorial, você usará o Console de gerenciamento da AWS. Para obter um modelo AWS SAM que cria essa API e todos os recursos relacionados, consulte [samples/http-dynamo-tutorial.zip](samples/http-dynamo-tutorial.zip).
**Topics**
+ [Etapa 1: Crie uma tabela do DynamoDB](#http-api-dynamo-db-create-table)
+ [Etapa 2: Criar uma função do Lambda](#http-api-dynamo-db-create-function)
+ [Etapa 3: Crie uma API HTTP](#http-api-dynamo-db-create-api)
+ [Etapa 4: Crie rotas](#http-api-dynamo-db-create-routes)
+ [Etapa 5: Crie uma integração](#http-api-dynamo-db-create-integration)
+ [Etapa 6: Anexe a sua integração às rotas](#http-api-dynamo-db-attach-integrations)
+ [Etapa 7: Teste a sua API](#http-api-dynamo-db-invoke-api)
+ [Etapa 8: Limpar](#http-api-dynamo-db-cleanup)
+ [Próximas etapas: Automatizar com AWS SAM ou CloudFormation](#http-api-dynamo-db-next-steps)
## Etapa 1: Crie uma tabela do DynamoDB
Você usa uma tabela do [DynamoDB](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html) para armazenar dados para a sua API.
Cada item tem um ID exclusivo, que usamos como [partition key](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.PrimaryKey) (chave de partição) para a tabela.
**Como criar uma tabela do DynamoDB**
1. Abra o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. Escolha **Create table**.
1. Em **Table name** (Nome da tabela), insira **http-crud-tutorial-items**.
1. Em **Partition key**, (Chave de partição), insira **id**.
1. Escolha **Create table**.
## Etapa 2: Criar uma função do Lambda
Você cria uma função do [Lambda](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) para o backend da sua API. Essa função do Lambda cria, lê, atualiza e exclui itens do DynamoDB. A função usa [ events from API Gateway](http-api-develop-integrations-lambda.md#http-api-develop-integrations-lambda.proxy-format) (eventos do API Gateway) para definir como interagir com o DynamoDB. Para fins de simplicidade, este tutorial usa uma única função do Lambda. Como prática recomendada, você deve criar funções separadas para cada rota. Para obter mais informações, consulte [The Lambda monolith](https://serverlessland.com/content/service/lambda/guides/aws-lambda-operator-guide/monolith) (A aplicação monolítica do Lambda).
**Criar uma função do Lambda**
1. Abra o console do Lambda em [https://console.aws.amazon.com/lambda](https://console.aws.amazon.com/lambda)
1. Escolha **Create function** (Criar função).
1. Em **Function name** (Nome da função), insira **http-crud-tutorial-function**.
1. Em **Tempo de execução**, escolha o último runtime **Node.js** ou **Python** compatível.
1. Em **Permissions** (Permissões), escolha **Change default execution role** (Alterar a função de execução padrão).
1. Selecione **Criar uma nova função a partir de modelos de política da AWS**.
1. Em **Role name** (Nome da função), insira **http-crud-tutorial-role**.
1. Em **Policy templates** (Modelos de políticas), escolha **Simple microservice permissions**. Esta política concede à função do Lambda permissão para interagir com o DynamoDB.
**nota**
Este tutorial usa uma política gerenciada em prol da simplicidade. Como prática recomendada, você deve criar sua própria política do IAM para conceder as permissões mínimas necessárias.
1. Escolha **Create function** (Criar função).
1. Abra a função do Lambda no editor de código do console e substitua seu conteúdo pelo código a seguir. Escolha **Deploy** (Implantar) para atualizar a sua função.
------
#### [ Node.js ]
```
import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
DynamoDBDocumentClient,
ScanCommand,
PutCommand,
GetCommand,
DeleteCommand,
} from "@aws-sdk/lib-dynamodb";
const client = new DynamoDBClient({});
const dynamo = DynamoDBDocumentClient.from(client);
const tableName = "http-crud-tutorial-items";
export const handler = async (event, context) => {
let body;
let statusCode = 200;
const headers = {
"Content-Type": "application/json",
};
try {
switch (event.routeKey) {
case "DELETE /items/{id}":
await dynamo.send(
new DeleteCommand({
TableName: tableName,
Key: {
id: event.pathParameters.id,
},
})
);
body = `Deleted item ${event.pathParameters.id}`;
break;
case "GET /items/{id}":
body = await dynamo.send(
new GetCommand({
TableName: tableName,
Key: {
id: event.pathParameters.id,
},
})
);
body = body.Item;
break;
case "GET /items":
body = await dynamo.send(
new ScanCommand({ TableName: tableName })
);
body = body.Items;
break;
case "PUT /items":
let requestJSON = JSON.parse(event.body);
await dynamo.send(
new PutCommand({
TableName: tableName,
Item: {
id: requestJSON.id,
price: requestJSON.price,
name: requestJSON.name,
},
})
);
body = `Put item ${requestJSON.id}`;
break;
default:
throw new Error(`Unsupported route: "${event.routeKey}"`);
}
} catch (err) {
statusCode = 400;
body = err.message;
} finally {
body = JSON.stringify(body);
}
return {
statusCode,
body,
headers,
};
};
```
------
#### [ Python ]
```
import json
import boto3
from decimal import Decimal
client = boto3.client('dynamodb')
dynamodb = boto3.resource("dynamodb")
table = dynamodb.Table('http-crud-tutorial-items')
tableName = 'http-crud-tutorial-items'
def lambda_handler(event, context):
print(event)
body = {}
statusCode = 200
headers = {
"Content-Type": "application/json"
}
try:
if event['routeKey'] == "DELETE /items/{id}":
table.delete_item(
Key={'id': event['pathParameters']['id']})
body = 'Deleted item ' + event['pathParameters']['id']
elif event['routeKey'] == "GET /items/{id}":
body = table.get_item(
Key={'id': event['pathParameters']['id']})
body = body["Item"]
responseBody = [
{'price': float(body['price']), 'id': body['id'], 'name': body['name']}]
body = responseBody
elif event['routeKey'] == "GET /items":
body = table.scan()
body = body["Items"]
print("ITEMS----")
print(body)
responseBody = []
for items in body:
responseItems = [
{'price': float(items['price']), 'id': items['id'], 'name': items['name']}]
responseBody.append(responseItems)
body = responseBody
elif event['routeKey'] == "PUT /items":
requestJSON = json.loads(event['body'])
table.put_item(
Item={
'id': requestJSON['id'],
'price': Decimal(str(requestJSON['price'])),
'name': requestJSON['name']
})
body = 'Put item ' + requestJSON['id']
except KeyError:
statusCode = 400
body = 'Unsupported route: ' + event['routeKey']
body = json.dumps(body)
res = {
"statusCode": statusCode,
"headers": {
"Content-Type": "application/json"
},
"body": body
}
return res
```
------
## Etapa 3: Crie uma API HTTP
A API HTTP fornece um endpoint de HTTP para sua função do Lambda. Nesta etapa, você cria uma API vazia. Nas etapas a seguir, você configura rotas e integrações para conectar a sua API e sua função do Lambda.
**Para criar uma API HTTP**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Create API** (Criar API) e, em seguida, em **API HTTP** (API HTTP), escolha **Build** (Criar).
1. Em **API name (Nome da API)**, insira **http-crud-tutorial-api**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Escolha **Próximo**.
1. Em **Configure routes** (Configurar rotas), escolha **Next** (Próximo) para ignorar a criação da rota. Você cria rotas mais tarde.
1. Analise o estágio que o API Gateway cria para você e escolha **Next** (Avançar).
1. Escolha **Create** (Criar).
## Etapa 4: Crie rotas
As rotas são uma forma de enviar as solicitações de API recebidas a recursos de backend. As rotas consistem em duas partes: um método HTTP e um caminho de recurso, por exemplo, `GET /items`. Para esta API de exemplo, criamos quatro rotas:
+ `GET /items/{id}`
+ `GET /items`
+ `PUT /items`
+ `DELETE /items/{id}`
**Para criar rotas**
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 a API.
1. Selecione **Routes (Rotas)**.
1. Escolha **Create** (Criar).
1. Em **Método**, escolha **GET**.
1. Para o caminho, insira **/items/\$1id\$1**. O `{id}` no final do caminho é um parâmetro de caminho que o API Gateway recupera do caminho de solicitação quando um cliente faz uma solicitação.
1. Escolha **Create** (Criar).
1. Repita as etapas quatro a sete para `GET /items``DELETE /items/{id}` e `PUT /items`.
![\[A sua API tem rotas para GET /items, GET /items/{id}, DELETE /items/{id} e PUT /items.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ddb-create-routes.png)
## Etapa 5: Crie uma integração
Você cria uma integração para conectar uma rota aos recursos de backend. Para este exemplo de API, você cria uma integração do Lambda que usa para todas as rotas.
**Para criar uma 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 a API.
1. Escolha **Integrations** (Integrações).
1. Escolha **Manage integrations** (Gerenciar integrações) e, em seguida, escolha **Create** (Criar).
1. Pule **Attach this integration to a route** (Anexar esta integração a uma rota). Você conclui isso em uma etapa posterior.
1. Em **Integration type** (Tipo de integração), escolha **Lambda function** (Função do Lambda).
1. Em **Lambda function** (Função do Lambda), insira **http-crud-tutorial-function**.
1. Escolha **Create** (Criar).
## Etapa 6: Anexe a sua integração às rotas
Para este exemplo de API, você usa a mesma integração do Lambda para todas as rotas. Depois de anexar a integração a todas as rotas da API, sua função do Lambda é invocada quando um cliente chama qualquer uma de suas rotas.
**Para anexar integrações a rotas**
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 a API.
1. Escolha **Integrations** (Integrações).
1. Escolha uma rota.
1. Em **Choose an existing integration** (Escolher uma integração existente), escolha **http-crud-tutorial-function**.
1. Escolha **Attach integration** (Anexar integração).
1. Repita as etapas quatro a seis para todas as rotas.
Todas as rotas mostram que há uma integração com o AWS Lambda anexada.
![\[O console mostra o AWS Lambda em todas as rotas para indicar que sua integração está anexada.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ddb-attach-integrations.png)
Agora que você tem uma API HTTP com rotas e integrações, já pode testar a sua API.
## Etapa 7: Teste a sua API
Para ter certeza de que a sua API está funcionando, use [curl](https://curl.se).
**Para obter a URL para invocar a sua API**
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 a API.
1. Observe o URL de invocação da sua API. Ela aparece em **Invoke URL** (Invocar URL) na página **Details** (Detalhes).
![\[Depois de criar a API, o console mostra o URL de chamada da API.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ddb-invoke-url.png)
1. Copie a URL de invocação da sua API.
A URL completa se assemelha a `https://abcdef123.execute-api.us-west-2.amazonaws.com`.
**Para criar ou atualizar um item**
+ Use o comando a seguir para criar ou atualizar um item. O comando inclui um corpo de solicitação com o ID, o preço e o nome do item.
```
curl -X "PUT" -H "Content-Type: application/json" -d "{\"id\": \"123\", \"price\": 12345, \"name\": \"myitem\"}" https://abcdef123.execute-api.us-west-2.amazonaws.com/items
```
**Para obter todos os itens**
+ Use o comando a seguir para listar todos os itens.
```
curl https://abcdef123.execute-api.us-west-2.amazonaws.com/items
```
**Para obter um item**
+ Use o comando a seguir para obter um item pelo seu ID.
```
curl https://abcdef123.execute-api.us-west-2.amazonaws.com/items/123
```
**Para excluir um item**
1. Use o comando a seguir para excluir um item.
```
curl -X "DELETE" https://abcdef123.execute-api.us-west-2.amazonaws.com/items/123
```
1. Obtenha todos os itens para verificar se o item foi excluído.
```
curl https://abcdef123.execute-api.us-west-2.amazonaws.com/items
```
## Etapa 8: Limpar
Para evitar custos desnecessários, exclua os recursos que você criou como parte desse exercício de conceitos básicos. As etapas a seguir excluem sua API HTTP, sua função do Lambda e recursos associados.
**Como excluir uma tabela do DynamoDB**
1. Abra o console do DynamoDB em [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/).
1. Selecionar a sua tabela.
1. Selecione **Delete table (Excluir tabela)**.
1. Confirme a sua decisão e escolha **Delete** (Excluir).
**Para excluir uma API HTTP**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Na página **APIs** , selecione uma API. Escolha **Actions (Ações)** e, depois, escolha **Delete (Excluir)**.
1. Escolha **Delete** (Excluir).
**Para excluir uma função do Lambda**
1. Abra o console do Lambda em [https://console.aws.amazon.com/lambda](https://console.aws.amazon.com/lambda)
1. Na página **Functions**(Funções), selecione uma função. Escolha **Actions (Ações)** e, depois, escolha **Delete (Excluir)**.
1. Escolha **Delete** (Excluir).
**Para excluir um grupo de logs de uma função do Lambda**
1. No console do Amazon CloudWatch, abra a [página Log groups](https://console.aws.amazon.com/cloudwatch/home#logs:) (Grupos de log).
1. Na página **Log groups** (Grupos de log), selecione o grupo de log da função (`/aws/lambda/http-crud-tutorial-function`). Escolha **Actions** (Ações) e selecione **Delete log group** (Excluir grupo de log).
1. Escolha **Delete** (Excluir).
**Para excluir a função de execução de uma função do Lambda**
1. No console do AWS Identity and Access Management, abra a página [Roles](https://console.aws.amazon.com/iam/home?#/roles) (Funções).
1. Selecione a atribuição da função, por exemplo, `http-crud-tutorial-role`.
1. Selecione **Delete role (Excluir função)**.
1. Escolha **Sim, excluir**.
## Próximas etapas: Automatizar com AWS SAM ou CloudFormation
Você pode automatizar a criação e a limpeza dos recursos da AWS usando o CloudFormation ou o AWS SAM. Para obter um exemplo de modelo do AWS SAM para este tutorial, consulte [samples/http-dynamo-tutorial.zip](samples/http-dynamo-tutorial.zip).
Para ver modelos de exemplo do CloudFormation, consulte [modelos de exemplo do CloudFormation](https://github.com/awsdocs/amazon-api-gateway-developer-guide/tree/main/cloudformation-templates).
# Tutorial: Crie uma API HTTP com uma integração privada a um serviço do Amazon ECS
Neste tutorial, você cria uma API sem servidor que se conecta a um serviço do Amazon ECS executado em uma Amazon VPC. Clientes fora da sua Amazon VPC podem usar a API para acessar seu serviço do Amazon ECS.
Este tutorial leva aproximadamente uma hora para ser concluído. Primeiro, você usa um modelo do CloudFormation para criar um serviço da Amazon VPC e do Amazon ECS. Em seguida, você usa o console do API Gateway para criar um link da VPC. O link da VPC permite que o API Gateway acesse o serviço do Amazon ECS executado em sua Amazon VPC. Em seguida, você cria uma API HTTP que usa o link VPC para se conectar ao seu serviço do Amazon ECS. Por fim, você testa a sua API.
Quando você invoca sua API HTTP, o API Gateway encaminha a solicitação para o serviço do Amazon ECS por meio do link da VPC e, em seguida, retorna a resposta do serviço.
![\[Visão geral da API HTTP que você cria neste tutorial.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/private-integration.png)
Para concluir esse tutorial, você precisa de uma conta da AWS e de um usuário do AWS Identity and Access Management com acesso ao console. Para obter mais informações, consulte [Configurar para usar o API Gateway](setting-up.md).
Neste tutorial, você usará o Console de gerenciamento da AWS. Para obter um modelo do CloudFormation que cria essa API e todos os recursos relacionados, consulte [template.yaml](samples/private-integration-full-template.zip).
**Topics**
+ [Etapa 1: Crie um serviço do Amazon ECS](#http-api-private-integration-create-ecs-service)
+ [Etapa 2: Crie um link da VPC](#http-api-private-integration-vpc-link)
+ [Etapa 3: Crie uma API HTTP](#http-api-private-integration-create-api)
+ [Etapa 4: Crie uma rota](#http-api-private-integration-create-routes)
+ [Etapa 5: Crie uma integração](#http-api-private-integration-create-integration)
+ [Etapa 6: Teste a sua API](#http-api-private-integration-invoke-api)
+ [Etapa 7: limpar](#http-api-private-integration-cleanup)
+ [Próximas etapas: Automatize com CloudFormation](#http-api-private-integration-next-steps)
## Etapa 1: Crie um serviço do Amazon ECS
O Amazon ECS é um serviço de gerenciamento de contêineres que facilita a execução, a interrupção e o gerenciamento de contêineres do Docker em um cluster. Neste tutorial, você executa seu cluster em uma infraestrutura sem servidor gerenciada pelo Amazon ECS.
Baixe e descompacte [este modelo do CloudFormation](samples/private-integration-cfn.zip) que cria todas as dependências do serviço, incluindo uma Amazon VPC. Use o modelo para criar um serviço do Amazon ECS que usa um Application Load Balancer.
**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 **http-api-private-integrations-tutorial** 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**.
CloudFormation provisiona o serviço ECS, que pode levar alguns minutos. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, você estará pronto para passar para a próxima etapa.
## Etapa 2: Crie um link da VPC
Um link da VPC permite que o API Gateway acesse recursos privados em uma Amazon VPC. Você usa um link da VPC para permitir que os clientes acessem seu serviço do Amazon ECS por meio de sua API HTTP.
**Para criar um link da VPC**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. No painel de navegação principal, escolha **Links da VPC** e selecione **Criar**.
Escolha o ícone do menu para se for necessário abrir o painel de navegação principal.
1. Em **Escolher uma versão de link VPC**, selecione **Link da VPC para APIs HTTP**.
1. Em **Name (Nome)**, insira **private-integrations-tutorial**.
1. Em **VPC**, escolha a VPC criada na etapa 1. O nome deve começar com **PrivateIntegrationsStack**.
1. Para **Sub-redes**, selecione as duas sub-redes privadas em sua VPC. Os nomes delas terminam com `PrivateSubnet`.
1. Em **Grupos de segurança**, selecione o ID do grupo que começa com `private-integrations-tutorial` e tem a descrição de `PrivateIntegrationsStack/PrivateIntegrationsTutorialService/Service/SecurityGroup`.
1. Escolha **Criar**.
Depois de criar seu link VPC, o API Gateway provisiona as interfaces de rede elásticas para acessar sua VPC. O processo pode levar alguns minutos. Enquanto isso, você pode criar sua API.
## Etapa 3: Crie uma API HTTP
A API HTTP fornece um endpoint HTTP para o seu serviço do Amazon ECS. Nesta etapa, você cria uma API vazia. Nas etapas 4 e 5, você configura uma rota e uma integração para conectar sua API e seu serviço do Amazon ECS.
**Para criar uma API HTTP**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Create API** (Criar API) e, em seguida, em **API HTTP** (API HTTP), escolha **Build** (Criar).
1. Em **API name (Nome da API)**, insira **http-private-integrations-tutorial**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Escolha **Next (Próximo)**.
1. Em **Configure routes** (Configurar rotas), escolha **Next** (Próximo) para ignorar a criação da rota. Você cria rotas mais tarde.
1. Revise o estágio criado pelo API Gateway para você. O API Gateway cria um estágio `$default` com implantações automáticas ativadas, que é a melhor escolha para este tutorial. Escolha **Next (Próximo)**.
1. Escolha **Criar**.
## Etapa 4: Crie uma rota
As rotas são uma forma de enviar as solicitações de API recebidas a recursos de backend. As rotas consistem em duas partes: um método HTTP e um caminho de recurso, por exemplo, `GET /items`. Para esta API de exemplo, criamos uma rota.
**Para criar uma rota**
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 a API.
1. Selecione **Routes (Rotas)**.
1. Escolha **Criar**.
1. Em **Método**, escolha **ANY**.
1. Para o caminho, insira **/\$1proxy\$1\$1**. O `{proxy+}` no final do caminho é uma variável de caminho ganancioso. O API Gateway envia todas as solicitações para sua API para essa rota.
1. Escolha **Criar**.
## Etapa 5: Crie uma integração
Você cria uma integração para conectar uma rota aos recursos de backend.
**Para criar uma 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 a API.
1. Escolha **Integrations** (Integrações).
1. Escolha **Manage integrations** (Gerenciar integrações) e, em seguida, escolha **Create** (Criar).
1. Em **Anexar esta integração a uma rota**, selecione a rota **ANY/\$1proxy\$1\$1** que você criou anteriormente.
1. Em **Tipo de integração**, escolha **Recurso privado**.
1. Em **Detalhes de integração**, escolha **Selecionar manualmente**.
1. Em **Serviço de destino**, escolha **ALB/NLB**.
1. Em **Load balancer** (Balanceador de carga), escolha o balanceador de carga criado com o modelo do CloudFormation na Etapa 1. Seu nome deve começar com **http-Priva**.
1. Em **Ouvinte**, escolha **HTTP 80**.
1. Em **Link da VPC**, escolha o link da VPC que você criou na Etapa 2. O nome deve ser `private-integrations-tutorial`.
1. Escolha **Criar**.
Para verificar se sua rota e integração estão configuradas corretamente, selecione **Anexar integrações às rotas**. O console mostra que você tem uma rota `ANY /{proxy+}` com uma integração a um Load Balancer da VPC.
![\[O console mostra que você tem uma rota /{proxy+} com uma integração ao Load Balancer em uma VPC.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/private-integration-tutorial-route.png)
Agora você está pronto para testar sua API.
## Etapa 6: Teste a sua API
Em seguida, você testa sua API para se certificar de que ela está funcionando. Para simplificar, use um navegador da Web para invocar sua API.
**Para testar sua API**
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 a API.
1. Observe o URL de invocação da sua API.
![\[Depois de criar a API, o console mostra o URL de chamada da API.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/getting-started-invoke-url.png)
1. Em um navegador da Web, acesse o URL de invocação da sua API.
O URL deve ser semelhante a `https://abcdef123.execute-api.us-east-2.amazonaws.com`.
Seu navegador envia uma solicitação `GET` à API.
1. Verifique se a resposta da sua API é uma mensagem de boas-vindas que informa que seu aplicativo está sendo executado no Amazon ECS.
Se você vir a mensagem de boas-vindas, você criou com sucesso um serviço do Amazon ECS executado em uma Amazon VPC e usou uma API HTTP do API Gateway com um link VPC para acessar o serviço do Amazon ECS.
## Etapa 7: limpar
Para evitar custos desnecessários, exclua os recursos que você criou como parte desse tutorial. As etapas a seguir excluem o link da VPC, a pilha do CloudFormation e a API HTTP.
**Para excluir uma API HTTP**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Na página **APIs** , selecione uma API. Escolha **Ações**, escolha **Excluir** e, em seguida, confirme sua escolha.
**Para excluir um link da VPC**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Link da VPC**.
1. Selecione seu link da VPC, escolha **Excluir**e confirme sua escolha.
**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.
## Próximas etapas: Automatize com CloudFormation
Você pode automatizar a criação e a limpeza de todos os recursos da AWS envolvidos neste tutorial. Para obter um modelo do CloudFormation de exemplo completo, consulte [template.yaml](samples/private-integration-full-template.zip).
# Tutoriais da API WebSocket do Amazon API Gateway
Os tutoriais a seguir fornecem exercícios práticos para ajudar você a saber mais sobre as APIs de WebSocket do API Gateway.
**Topics**
+ [Tutorial: Crie uma aplicação de bate-papo de WebSocket com uma API de WebSocket, o Lambda e o DynamoDB](websocket-api-chat-app.md)
+ [Tutorial: Crie uma API de WebSocket com uma integração da AWS](websocket-api-step-functions-tutorial.md)
# Tutorial: Crie uma aplicação de bate-papo de WebSocket com uma API de WebSocket, o Lambda e o DynamoDB
Neste tutorial, você criará uma aplicação de bate-papo sem servidor com uma API WebSocket. Com uma API WebSocket, você pode oferecer suporte à comunicação bidirecional entre clientes. Os clientes podem receber mensagens sem precisar pesquisar atualizações.
Este tutorial leva aproximadamente 30 minutos para ser concluído. Primeiro, você usará um modelo de CloudFormation para criar funções do Lambda que lidarão com solicitações de API, bem como uma tabela do DynamoDB que armazena suas IDs de cliente. Depois, você usará o console do API Gateway para criar uma API WebSocket que se integrará às suas funções do Lambda. Por fim, você testará sua API para verificar se as mensagens foram enviadas e recebidas.
![\[Visão geral da arquitetura da API que você cria neste tutorial.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ws-chat-app.png)
Para concluir esse tutorial, você precisa de uma conta da AWS e de um usuário do AWS Identity and Access Management com acesso ao console. Para obter mais informações, consulte [Configurar para usar o API Gateway](setting-up.md).
Você também precisa que o `wscat` se conecte à sua API. Para obter mais informações, consulte [Use `wscat` para se conectar a uma API do WebSocket e enviar mensagens a ela](apigateway-how-to-call-websocket-api-wscat.md).
**Topics**
+ [Etapa 1: Criar funções do Lambda e uma tabela do DynamoDB](#websocket-api-chat-app-create-dependencies)
+ [Etapa 2: Criar uma API WebSocket](#websocket-api-chat-app-create-api)
+ [Etapa 3: testar sua API](#websocket-api-chat-app-invoke-api)
+ [Etapa 4: limpar](#websocket-api-chat-app-cleanup)
+ [Próximas etapas: Automatize com CloudFormation](#websocket-api-chat-app-next-steps)
## Etapa 1: Criar funções do Lambda e uma tabela do DynamoDB
Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/ws-chat-app-starter.zip). Você usará esse modelo para criar uma tabela do Amazon DynamoDB para armazenar as IDs de cliente do aplicativo. Cada cliente conectado tem uma ID exclusiva que usaremos como chave de partição da tabela. Este modelo também cria funções do Lambda que atualizam suas conexões de cliente no DynamoDB e lidam com o envio de mensagens para clientes conectados.
**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 **websocket-api-chat-app-tutorial** 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.
## Etapa 2: Criar uma API WebSocket
Você criará uma API WebSocket para lidar com conexões de clientes e rotear solicitações para as funções do Lambda que criou na Etapa 1.
**Como criar uma API WebSocket**
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 **Criar API**. Depois, em **WebSocket API** (API WebSocket), escolha **Build** (Criar).
1. Em **API name (Nome da API)**, insira **websocket-chat-app-tutorial**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Em **Route selection expression** (Expressão de seleção de rota), insira **request.body.action**. A expressão de seleção de rota determina qual rota o API Gateway invoca quando um cliente envia uma mensagem.
1. Escolha **Next (Próximo)**.
1. Em **Predefined routes** (Rotas predefinidas), escolha **Add \$1connect** (Adicionar \$1connect), **Add \$1disconnect** (Adicionar \$1disconnect) e **Add \$1default** (Adicionar \$1default). As rotas **\$1connect** e **\$1disconnect** são rotas especiais que o API Gateway invoca automaticamente quando um cliente se conecta ou se desconecta de uma API. O API Gateway invoca a rota `$default` quando nenhuma outra rota corresponde a uma solicitação.
1. Em **Custom routes** (Rotas personalizadas), escolha **Add custom route** (Adicionar rota personalizada). Em **Route key** (Chave de rota), insira **sendmessage**. Essa rota personalizada lida com mensagens enviadas para clientes conectados.
1. Escolha **Next (Próximo)**.
1. Em **Attach integrations** (Anexar integrações), para cada rota e **Integration type** (Tipo de integração), escolha Lambda.
Em **Lambda**, escolha a função do Lambda correspondente que você criou com o CloudFormation na Etapa 1. O nome de cada função corresponde a uma rota. Por exemplo, para a rota **\$1connect**, escolha a função chamada **websocket-chat-app-tutorial-ConnectHandler**.
1. Revise o estágio criado pelo API Gateway para você. Por padrão, o API Gateway cria um nome de estágio `production` e implanta automaticamente sua API nesse estágio. Escolha **Next (Próximo)**.
1. Selecione **Create and deploy** (Criar e implantar).
## Etapa 3: testar sua API
Depois, você testará sua API para verificar se ela está funcionando corretamente. Use o comando `wscat` para se conectar à API.
**Como obter a URL para invocar a sua API**
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 a API.
1. Escolha **Stages** (Estágios) e, depois, **production** (produção).
1. Observe o **URL WebSocket** da API. O URL deve ser semelhante a `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`.
**Como se conectar à sua API**
1. Use o comando a seguir para se conectar à sua API. Quando você se conecta à API, o API Gateway invoca a rota `$connect`. Quando essa rota é invocada, ela chama uma função do Lambda que armazena seu ID de conexão no DynamoDB.
```
wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production
```
```
Connected (press CTRL+C to quit)
```
1. Abra um novo terminal e execute o comando **wscat** novamente com os parâmetros a seguir.
```
wscat -c wss://abcdef123.execute-api.us-west-2.amazonaws.com/production
```
```
Connected (press CTRL+C to quit)
```
Isso fornece dois clientes conectados que podem trocar mensagens.
**Para enviar uma mensagem**
+ O API Gateway determina qual rota invocar com base na expressão de seleção de rotas da API. A expressão de seleção de rotas da sua API é `$request.body.action`. Como resultado, o API Gateway invoca a rota `sendmessage` quando você envia a seguinte mensagem:
```
{"action": "sendmessage", "message": "hello, everyone!"}
```
A função do Lambda associada à rota invocada coleta os IDs do cliente do DynamoDB. Depois, a função chama a API de gerenciamento do API Gateway e envia a mensagem para esses clientes. Todos os clientes conectados recebem a seguinte mensagem:
```
< hello, everyone!
```
**Como invocar a rota \$1default da API**
+ O API Gateway invocará a rota padrão da API quando um cliente envia uma mensagem que não corresponde às rotas definidas. A função do Lambda associada à rota `$default` usa a API de gerenciamento do API Gateway para enviar informações do cliente sobre sua conexão.
```
test
```
```
Use the sendmessage route to send a message. Your info: {"ConnectedAt":"2022-01-25T18:50:04.673Z","Identity":{"SourceIp":"192.0.2.1","UserAgent":null},"LastActiveAt":"2022-01-25T18:50:07.642Z","connectionID":"Mg_ugfpqPHcCIVA="}
```
**Para se desconectar de sua API**
+ Pressione **CTRL\$1C** para se desconectar de sua API. Quando um cliente se desconecta da sua API, o API Gateway invoca a rota `$disconnect` de sua API. A integração do Lambda para a rota `$disconnect` de sua API remove o ID da conexão do DynamoDB.
## Etapa 4: limpar
Para evitar custos desnecessários, exclua os recursos que você criou como parte desse tutorial. As etapas a seguir excluem a API WebSocket e sua pilha do CloudFormation.
**Como excluir uma API WebSocket**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Na página **APIs**, selecione sua API do `websocket-chat-app-tutorial`. Escolha **Ações**, escolha **Excluir** e, em seguida, confirme sua escolha.
**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.
## Próximas etapas: Automatize com CloudFormation
Você pode automatizar a criação e a limpeza de todos os recursos da AWS envolvidos neste tutorial. Para ver um modelo do CloudFormation que crie essa API e todos os recursos relacionados, consulte [ws-chat-app.yaml](samples/ws-chat-app.zip).
# Tutorial: Crie uma API de WebSocket com uma integração da AWS
Neste tutorial, você criará uma aplicação de transmissão com tecnologia sem servidor com uma API de WebSocket. Os clientes podem receber mensagens sem precisar pesquisar atualizações.
Este tutorial mostra como transmitir mensagens para clientes conectados e inclui um exemplo de um autorizador do Lambda, uma integração simulada e uma integração sem proxy com o Step Functions.
![\[Visão geral da arquitetura da API que você cria neste tutorial.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ws-sfn-app.png)
Depois de criar seus recursos usando um modelo do CloudFormation, você usará o console do API Gateway para criar uma API de WebSocket que se integrará aos seus recursos da AWS. Você anexará um autorizador do Lambda à sua API e criará uma integração de serviços da AWS com o Step Functions para iniciar a execução de uma máquina de estado. A máquina de estado do Step Functions invocará uma função do Lambda que envia uma mensagem para todos os clientes conectados.
Depois de criar sua API, você testará sua conexão com a API e verificará se as mensagens foram enviadas e recebidas. Este tutorial leva aproximadamente 45 minutos para ser concluído.
**Topics**
+ [Pré-requisitos](#websocket-api-step-functions-prerequisites)
+ [Etapa 1: Criar recursos](#websocket-api-step-functions-create-dependencies)
+ [Etapa 2: Criar uma API WebSocket](#websocket-api-step-functions-create-api)
+ [Etapa 3: Criar um autorizador do Lambda](#websocket-api-step-functions-create-authorizer)
+ [Etapa 4: Criar uma integração bidirecional simulada](#websocket-api-step-functions-create-mock-integration)
+ [Etapa 5: Criar uma integração sem proxy com o Step Functions](#websocket-api-step-functions-create-step-function-integration)
+ [Etapa 6: Teste a sua API](#websocket-api-step-functions-test-api)
+ [Etapa 7: limpar](#websocket-api-step-functions-cleanup)
+ [Próximas etapas](#websocket-api-step-functions-next-steps)
## Pré-requisitos
Você precisa dos seguintes pré-requisitos:
+ Uma conta da AWS e um usuário do AWS Identity and Access Management com acesso ao console. Para obter mais informações, consulte [Configurar para usar o API Gateway](setting-up.md).
+ `wscat` para se conectar à sua API. Para obter mais informações, consulte [Use `wscat` para se conectar a uma API do WebSocket e enviar mensagens a ela](apigateway-how-to-call-websocket-api-wscat.md).
Recomendamos que você conclua o tutorial de aplicação de bate-papo do WebSocket antes de iniciar este tutorial. Para concluir o tutorial de aplicação de bate-papo do WebSocket, consulte [Tutorial: Crie uma aplicação de bate-papo de WebSocket com uma API de WebSocket, o Lambda e o DynamoDB](websocket-api-chat-app.md).
## Etapa 1: Criar recursos
Baixe e descompacte [o modelo de criação de aplicativos para CloudFormation](samples/ws-sfn-starter.zip). Você usará este modelo para criar o seguinte:
+ Funções do Lambda que lidam com solicitações de API e autorizam o acesso à sua API.
+ Uma tabela do DynamoDB para armazenar IDs de clientes e a identificação do usuário da entidade principal retornada pelo autorizador do Lambda.
+ Uma máquina de estado do Step Functions para enviar mensagens para clientes conectados.
**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 **websocket-step-functions-tutorial** 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. Escolha a guia **Saídas** para ver os recursos criados e seus ARNs. Quando o status da sua pilha do CloudFormation for **CREATE\$1COMPLETE**, você estará pronto para passar para a próxima etapa.
## Etapa 2: Criar uma API WebSocket
Você criará uma API de WebSocket para lidar com conexões de clientes e rotear solicitações para os recursos criados na Etapa 1.
**Como criar uma API WebSocket**
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 **Criar API**. Depois, em **WebSocket API** (API WebSocket), escolha **Build** (Criar).
1. Em **API name (Nome da API)**, insira **websocket-step-functions-tutorial**.
1. Em **Tipo de endereço IP**, selecione **IPv4**.
1. Em **Route selection expression** (Expressão de seleção de rota), insira **request.body.action**.
A expressão de seleção de rota determina qual rota o API Gateway invoca quando um cliente envia uma mensagem.
1. Escolha **Next (Próximo)**.
1. Em **Rotas predefinidas**, escolha **Adicionar \$1connect**, **Adicionar \$1disconnect** e **Adicionar \$1default**.
As rotas **\$1connect** e **\$1disconnect** são rotas especiais que o API Gateway invoca automaticamente quando um cliente se conecta ou se desconecta de uma API. O API Gateway invoca a rota **\$1default** quando nenhuma outra rota corresponde a uma solicitação. Você criará uma rota personalizada para se conectar ao Step Functions depois de criar sua API.
1. Escolha **Next (Próximo)**.
1. Para **Integração para \$1connect**, faça o seguinte:
1. Em **Tipo de integração**, escolha **Lambda**.
1. Em **Função do Lambda**, escolha a função do Lambda **\$1connect** correspondente que você criou com o CloudFormation na Etapa 1. O nome da função do Lambda deve começar com **websocket-step**.
1. Para **Integração para \$1disconnect**, faça o seguinte:
1. Em **Tipo de integração**, escolha **Lambda**.
1. Em **Função do Lambda**, escolha a função do Lambda **\$1disconnect** correspondente que você criou com o CloudFormation na Etapa 1. O nome da função do Lambda deve começar com **websocket-step**.
1. Em **Integração para \$1default**, escolha **mock**.
Em uma integração simulada, o API Gateway gerencia a resposta da rota sem um back-end de integração.
1. Escolha **Next (Próximo)**.
1. Revise o estágio criado pelo API Gateway para você. Por padrão, o API Gateway cria um estágio nomeado **production** e implanta automaticamente sua API nesse estágio. Escolha **Next (Próximo)**.
1. Selecione **Create and deploy** (Criar e implantar).
## Etapa 3: Criar um autorizador do Lambda
Para controlar o acesso à sua API de WebSocket, você cria um autorizador do Lambda. O modelo do CloudFormation criou a função de autorizador do Lambda para você. Você pode criar a função do Lambda no console do Lambda. O nome deve começar com **websocket-step-functions-tutorial-AuthorizerHandler**. Essa função do Lambda nega todas as chamadas para a API de WebSocket, a menos que o cabeçalho `Authorization` seja `Allow`. A função do Lambda também transmite a variável `$context.authorizer.principalId` para sua API, que é usada posteriormente na tabela do DynamoDB para identificar os chamadores da API.
Nesta etapa, você configura a rota **\$1connect** para usar o autorizador do Lambda.
**Para criar um autorizador do Lambda**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. No painel de navegação principal, selecione **Autorizadores**.
1. Selecione **Criar um autorizador**.
1. Em **Nome do autorizador**, insira **LambdaAuthorizer**.
1. Em **ARN do autorizador**, insira o nome do autorizador criado pelo modelo CloudFormation. O nome deve começar com **websocket-step-functions-tutorial-AuthorizerHandler**.
**nota**
Recomendamos que você não use este exemplo de autorizador para suas APIs de produção.
1. Em **Identificar tipo de origem**, escolha **Cabeçalho**. Em **Chave**, digite **Authorization**.
1. Selecione **Criar autorizador**.
Depois de criar o autorizador, você deve anexá-lo à rota **\$1connect** da sua API.
**Para anexar um autorizador à rota \$1connect**
1. No painel de navegação principal, selecione **Rotas**.
1. Escolha a rota **\$1connect**.
1. Na seção **Configurações de solicitação de rota**, selecione **Editar**.
1. Em **Autorização**, escolha o menu suspenso e selecione o autorizador da solicitação.
1. Escolha **Salvar alterações**.
## Etapa 4: Criar uma integração bidirecional simulada
Em seguida, crie a integração simulada bidirecional para a rota **\$1default**. Uma integração simulada permite que você envie uma resposta ao cliente sem usar um back-end. Ao criar uma integração para a rota **\$1default**, você pode mostrar aos clientes como interagir com sua API.
Você configura a rota **\$1default** a fim de informar os clientes para que usem a rota **sendmessage**.
**Para criar uma integração simulada**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha a rota **\$1default** e a guia **Solicitação de integração**.
1. Em **Modelos de solicitação**, escolha **Editar**.
1. Em **Expressão de seleção de modelo**, insira **200** e escolha **Editar**.
1. Na guia **Solicitação de integração**, em **Modelos de solicitação**, escolha **Criar modelo**.
1. Em **Chave do modelo**, insira **200**.
1. Em **Gerar modelo**, insira o seguinte modelo de mapeamento:
```
{"statusCode": 200}
```
Selecione **Criar modelo**.
O resultado deve ser algo semelhante a:
![\[Configuração da solicitação de integração para integração simulada para a rota $default.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ws-sfn-mock-integration-request.png)
1. No painel **rota \$1default**, escolha **Habilitar comunicação bidirecional**.
1. Escolha a guia **Resposta de integração** e **Criar resposta de integração**.
1. Em **Chave de resposta**, insira **\$1default**.
1. Em **Expressão de seleção de modelos**, insira **200**.
1. Selecione **Criar resposta**.
1. Em **Modelos de resposta**, selecione **Criar modelo**.
1. Em **Chave do modelo**, insira **200**.
1. Em **Modelo de resposta**, insira o seguinte modelo de mapeamento:
```
{"Use the sendmessage route to send a message. Connection ID: $context.connectionId"}
```
1. Selecione **Criar modelo**.
O resultado deve ser algo semelhante a:
![\[Configuração de resposta de integração para integração simulada para a rota $default.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ws-sfn-mock-integration-response.png)
## Etapa 5: Criar uma integração sem proxy com o Step Functions
Em seguida, crie uma rota **sendmessage**. Os clientes podem invocar a rota **sendmessage** para transmitir uma mensagem para todos os clientes conectados. A rota **sendmessage** tem uma integração de serviço da AWS sem proxy com o AWS Step Functions. A integração invoca o comando [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) para a máquina de estado do Step Functions que o modelo do CloudFormation criou para você.
**Para criar uma integração sem proxy**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Create route (Criar rota)**.
1. Em **Route key** (Chave de rota), insira **sendmessage**.
1. Em **Tipo de integração**, selecione **Serviço da AWS **.
1. Em **Região da AWS**, insira a região em que você implantou seu modelo do CloudFormation.
1. Em **Serviço da AWS**, escolha **Step Functions**.
1. Em **Método HTTP**, escolha **POST**.
1. Em **Nome da ação**, insira **StartExecution**.
1. Em **Perfil de execução**, insira o perfil de execução criado pelo modelo do CloudFormation. O nome deve ser **WebsocketTutorialApiRole**.
1. Escolha **Create route (Criar rota)**.
Em seguida, crie um modelo de mapeamento para enviar parâmetros de solicitação para a máquina de estado do Step Functions.
**Como criar um modelo de mapeamento**
1. Escolha a rota **sendmessage** e a guia **Solicitação de integração**.
1. Na seção **Modelos de solicitação**, selecione **Editar**.
1. Em **Expressão de seleção de modelos**, insira **\$1\$1default**.
1. Escolha **Editar**.
1. Na seção **Modelos de solicitação**, selecione **Criar modelo**.
1. Em **Chave do modelo**, insira **\$1\$1default**.
1. Em **Gerar modelo**, insira o seguinte modelo de mapeamento:
```
#set($domain = "$context.domainName")
#set($stage = "$context.stage")
#set($body = $input.json('$'))
#set($getMessage = $util.parseJson($body))
#set($mymessage = $getMessage.message)
{
"input": "{\"domain\": \"$domain\", \"stage\": \"$stage\", \"message\": \"$mymessage\"}",
"stateMachineArn": "arn:aws:states:us-east-2:123456789012:stateMachine:WebSocket-Tutorial-StateMachine"
}
```
Substitua *stateMachineArn* pelo ARN da máquina de estado criado pelo CloudFormation.
O modelo de mapeamento faz o seguinte:
+ Cria a variável `$domain` usando a variável de contexto `domainName`.
+ Cria a variável `$stage` usando a variável de contexto `stage`.
As variáveis `$domain` e `$stage` são necessárias para criar um URL de retorno de chamada.
+ Recebe a mensagem JSON `sendmessage` recebida e extrai a propriedade `message`.
+ Cria a entrada para a máquina de estado. A entrada é o domínio e o estágio da API de WebSocket e a mensagem da rota `sendmessage`.
1. Selecione **Criar modelo**.
![\[Configuração da rota sendmessage.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/ws-sfn-integration-request.png)
Você pode criar uma integração sem proxy nas rotas **\$1connect** ou **\$1disconnect** para adicionar ou remover diretamente um ID de conexão da tabela do DynamoDB, sem invocar uma função do Lambda.
## Etapa 6: Teste a sua API
Em seguida, implante e teste sua API para verificar se ela está funcionando corretamente. Você usará o comando `wscat` para se conectar à API e usará um comando de barra para enviar uma estrutura ping para verificar a conexão com a API de WebSocket.
**Para implantar sua API**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. No painel de navegação principal, selecione **Rotas**.
1. Escolha **Implantar API**.
1. Em **Estágio**, escolha **production**.
1. (Opcional) Em **Descrição da implantação**, insira uma descrição.
1. Escolha **Implantar**.
Depois de implantar sua API, você pode invocá-la. Use o URL de invocação para chamar sua API.
**Para obter o URL de invocação da sua API**
1. Selecione a API.
1. Escolha **Stages** (Estágios) e, depois, **production** (produção).
1. Observe o **URL WebSocket** da API. O URL deve ser semelhante a `wss://abcdef123.execute-api.us-east-2.amazonaws.com/production`.
Agora que você tem o URL de invocação, já pode testar a conexão com a API de WebSocket.
**Para testar a conexão com sua API**
1. Use o comando a seguir para se conectar à sua API. Primeiro, teste a conexão invocando o caminho `/ping`.
```
wscat -c wss://abcdef123.execute-api.us-east-2.amazonaws.com/production -H "Authorization: Allow" --slash -P
```
```
Connected (press CTRL+C to quit)
```
1. Insira o comando a seguir para fazer ping do frame do controle. Você pode usar uma estrutura de controle para fins de manutenção de atividade do lado do cliente.
```
/ping
```
O resultado deve ser algo semelhante a:
```
< Received pong (data: "")
```
Agora que já testou a conexão, pode testar se a sua API funciona corretamente. Nesta etapa, abra uma nova janela de terminal para que a API de WebSocket possa enviar uma mensagem para todos os clientes conectados.
**Para testar sua API**
1. Abra um novo terminal e execute o comando `wscat` novamente com os parâmetros a seguir.
```
wscat -c wss://abcdef123.execute-api.us-east-2.amazonaws.com/production -H "Authorization: Allow"
```
```
Connected (press CTRL+C to quit)
```
1. O API Gateway determina qual rota invocar com base na expressão de seleção da solicitação de rotas da API. A expressão de seleção de rotas da sua API é `$request.body.action`. Como resultado, o API Gateway invoca a rota `sendmessage` quando você envia a seguinte mensagem:
```
{"action": "sendmessage", "message": "hello, from Step Functions!"}
```
A máquina de estado do Step Functions associada à rota invoca uma função do Lambda com a mensagem e o URL de retorno de chamada. Depois, a função do Lambda chama a API de gerenciamento do API Gateway e envia a mensagem para todos os clientes conectados. Todos os clientes conectados recebem a seguinte mensagem:
```
< hello, from Step Functions!
```
Agora que você testou sua API de WebSocket, pode se desconectar da sua API.
**Para se desconectar de sua API**
+ Pressione `CTRL+C` para se desconectar de sua API.
Quando um cliente se desconecta da sua API, o API Gateway invoca a rota **\$1disconnect** da sua API. A integração do Lambda para a rota **\$1disconnect** da sua API remove o ID da conexão do DynamoDB.
## Etapa 7: limpar
Para evitar custos desnecessários, exclua os recursos que você criou como parte desse tutorial. As etapas a seguir excluem a API WebSocket e sua pilha do CloudFormation.
**Como excluir uma API WebSocket**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Na página **APIs**, selecione **websocket-api**.
1. Escolha **Ações**, escolha **Excluir** e, em seguida, confirme sua escolha.
**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.
## Próximas etapas
Você pode automatizar a criação e a limpeza de todos os recursos da AWS envolvidos neste tutorial. Para ver um exemplo de um modelo do CloudFormation que automatiza essas ações neste tutorial, consulte [ws-sfn.zip](samples/ws-sfn-complete.zip).