# Métodos para APIs REST no API Gateway
No API Gateway, um método de API incorpora uma [solicitação de método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) e uma [resposta de método](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). Você pode configurar um método de API para definir o que um cliente deve fazer para enviar uma solicitação para acessar o serviço no backend e definir as respostas que o cliente recebe em troca. Para entrada, você pode escolher os parâmetros de solicitação de método ou uma carga útil aplicável para o cliente fornecer os dados obrigatórios ou opcionais em tempo de execução. Para a saída, você determina o código de status de resposta de método, os cabeçalhos e o corpo aplicável como destinos para mapear os dados de resposta de backend, antes de serem retornados para o cliente. Para ajudar o desenvolvedor do cliente a entender os comportamentos e os formatos de entrada e saída de sua API, você pode [documentar sua API](api-gateway-documenting-api.md) e [fornecer mensagens de erro adequadas](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) para [solicitações inválidas](api-gateway-method-request-validation.md).
Solicitação de método de API é uma solicitação HTTP. Para configurar a solicitação de método, configure um método HTTP (ou verbo), o caminho para um [recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API, cabeçalhos e parâmetros de string de consulta aplicáveis. Você também configura uma carga útil quando o método HTTP é `POST`, `PUT` ou `PATCH`. Por exemplo, para recuperar um animal de estimação usando a [API de exemplo PetStore](api-gateway-create-api-from-example.md), defina a solicitação de método de API de `GET /pets/{petId}`, em que `{petId}` é um parâmetro de caminho que pode obter um número em tempo de execução.
```
GET /pets/1
Host: apigateway.us-east-1.amazonaws.com
...
```
Se o cliente especificar um caminho incorreto, por exemplo, `/pet/1` ou `/pets/one` em vez de `/pets/1`, será lançada uma exceção.
Uma resposta de método de API é uma resposta HTTP com um código de status determinado. Para uma integração não proxy, você deve configurar respostas de método para especificar os destinos obrigatórios ou opcionais dos mapeamentos. Eles transformam os cabeçalhos de resposta de integração ou o corpo para os cabeçalhos de resposta de método associado ou o corpo. O mapeamento pode ser tão simples quanto uma [transformação de identidade](https://en.wikipedia.org/wiki/Identity_transform) que transmite os cabeçalhos ou o corpo pela integração no estado em que se encontra. Por exemplo, a resposta de método `200` a seguir mostra um exemplo de passagem de uma resposta de integração bem-sucedida no estado em que se encontra.
```
200 OK
Content-Type: application/json
...
{
"id": "1",
"type": "dog",
"price": "$249.99"
}
```
Em princípio, você pode definir uma resposta de método correspondente a uma resposta específica do backend. Normalmente, isso envolve qualquer resposta 2XX, 4XX e 5XX. No entanto, isso pode não ser prático, pois, muitas vezes, você pode não saber com antecedência todas as respostas que um backend pode retornar. Na prática, você pode designar uma resposta de método como padrão para lidar com respostas desconhecidas ou não mapeadas do backend. É uma boa prática designar a resposta 500 como padrão. Em qualquer caso, você deve configurar pelo menos uma resposta de método para integrações não proxy. Caso contrário, o API Gateway retorna uma resposta de erro 500 para o cliente, mesmo quando a solicitação for bem-sucedida no backend.
Para oferecer suporte a um SDK fortemente tipado, como um Java SDK, para sua API, você deve definir o modelo de dados para entrada para a solicitação de método e definir o modelo de dados para a saída da resposta de método.
## Pré-requisitos
Antes de configurar um método de API, verifique o seguinte:
+ Você deve ter o método disponível no API Gateway. Siga as instruções em [Tutorial: Crie uma API REST com uma integração de não proxy de HTTP](api-gateway-create-api-step-by-step.md).
+ Se você deseja que o método se comunique com uma função do Lambda, você já deve ter criado as funções de invocação e execução do Lambda no IAM. Você também deve ter criado a função do Lambda com a qual seu método se comunicará no AWS Lambda. Para criar as funções, use as instruções em [Criar uma função do Lambda para integração não proxy do Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) do [Escolher um tutorial de integração do AWS Lambda](getting-started-with-lambda-integration.md).
+ Se quiser que o método se comunique com uma integração HTTP ou de proxy HTTP, será necessário já ter criado a URL de endpoint HTTP com a qual o seu método se comunicará, além de ter acesso a ela.
+ Verifique se os certificados para os endpoints HTTP e de proxy HTTP têm suporte pelo API Gateway. Para obter mais detalhes, consulte [Autoridades de certificado compatíveis com o API Gateway para integrações HTTP e de proxy HTTP no API Gateway.](api-gateway-supported-certificate-authorities-for-http-endpoints.md).
**Topics**
+ [Pré-requisitos](#method-setting-prerequisites)
+ [Configurar uma solicitação de método no API Gateway](api-gateway-method-settings-method-request.md)
+ [Configurar uma resposta de método no API Gateway](api-gateway-method-settings-method-response.md)
+ [Configurar um método usando o console do API Gateway](how-to-set-up-method-using-console.md)
# Configurar uma solicitação de método no API Gateway
A configuração de uma solicitação de método envolve as seguintes tarefas, depois de criar um recurso [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html):
1. A criação de uma nova API ou a escolha de uma entidade [Recurso](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) de API existente.
1. A criação de um recurso [Método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) da API que seja um verbo HTTP específico no `Resource` de API novo ou escolhido. Essa tarefa pode ser dividida ainda mais nas seguintes tarefas secundárias:
+ Adição de um método HTTP à solicitação de método
+ Configuração de parâmetros de solicitação
+ Definição de um modelo para o corpo de solicitação
+ Adoção de um esquema de autorização
+ Ativação da validação de solicitação
Você pode executar essas tarefas usando os seguintes métodos:
+ [Console do API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console)
+ Comandos da AWS CLI ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) e [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html))
+ Funções do SDK da AWS (por exemplo, em Node.js, [createResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) e [putMethod](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property))
+ API REST do API Gateway ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) e [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)).
**Topics**
+ [Configurar recursos da API](#setup-method-resources)
+ [Configurar um método HTTP](#setup-method-add-http-method)
+ [Configurar parâmetros da solicitação de método](#setup-method-request-parameters)
+ [Configurar um modelo de solicitação de método](#setup-method-request-model)
+ [Configurar a autorização de solicitação de método](#setup-method-request-authorization)
+ [Configurar a validação da solicitação de método](#setup-method-request-validation)
## Configurar recursos da API
Em uma API do API Gateway, você expõe recursos endereçáveis como uma árvore de entidades de [Recursos](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) da API, com o recurso raiz (`/`) na parte superior da hierarquia. O recurso raiz é relativo à URL base da API, que é composta do endpoint de API e um nome de etapa. No console do API Gateway esse URI base é referido como o **URI de invocação** e é exibido no editor de etapas da API depois que a API é implantada.
O endpoint da API pode ser um nome de host padrão ou um nome de domínio personalizado. O nome de host padrão é do seguinte formato:
```
{api-id}.execute-api.{region}.amazonaws.com
```
Neste formato, o *\$1api-id\$1* representa o identificador de API que é gerado pelo API Gateway. A variável `{region}` representa a região da AWS (por exemplo, `us-east-1`) escolhida ao criar a API. Um nome de domínio personalizado é qualquer nome amigável em um domínio de internet válido. Por exemplo, se você tiver registrado um domínio da Internet de `example.com`, qualquer `*.example.com` é um nome de domínio personalizado válido. Para obter mais informações, consulte [criar um nome de domínio personalizado](how-to-custom-domains.md).
Para a [API de exemplo PetStore](api-gateway-create-api-from-example.md), o recurso raiz (`/`) expõe a loja de animais de estimação. O recurso `/pets` representa a coleção de animais de estimação disponíveis na loja. O `/pets/{petId}` expõe um animação de estimação individual de um determinado identificador (`petId`). O parâmetro de caminho de `{petId}` faz parte dos parâmetros da solicitação.
Para configurar um recurso de API, você escolhe um recurso existente como seu pai e, em seguida, cria os recursos filho abaixo desse recurso pai. Você começa com o recurso raiz como um pai, adiciona um recurso a esse pai, adiciona outro recurso a esse recurso filho como novo pai, e assim por diante, ao identificador pai. Em seguida, você adiciona o recurso indicado ao pai.
O comando [get-resources](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) indicado abaixo recupera todos os recursos de uma API:
```
aws apigateway get-resources --rest-api-id apiId
```
Para o exemplo de API PetStore, essa lista é semelhante à seguinte:
```
{
"items": [
{
"path": "/pets",
"resourceMethods": {
"GET": {}
},
"id": "6sxz2j",
"pathPart": "pets",
"parentId": "svzr2028x8"
},
{
"path": "/pets/{petId}",
"resourceMethods": {
"GET": {}
},
"id": "rjkmth",
"pathPart": "{petId}",
"parentId": "6sxz2j"
},
{
"path": "/",
"id": "svzr2028x8"
}
]
}
```
Cada item lista os identificadores do recurso (`id`) e, exceto para o recurso raiz, seu pai imediato (`parentId`), bem como o nome do recurso (`pathPart`). O recurso raiz é especial, pois não tem nenhum pai. Depois de escolher um recurso como primário, use o comando a seguir para adicionar um recurso secundário.
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id parentId \
--path-part resourceName
```
Por exemplo, para colocar rações para animais de estimação à venda no site PetStore, use o seguinte comando:
```
aws apigateway create-resource --rest-api-id a1b2c3 \
--parent-id svzr2028x8 \
--path-part food
```
A saída será exibida da seguinte forma:
```
{
"path": "/food",
"pathPart": "food",
"id": "xdsvhp",
"parentId": "svzr2028x8"
}
```
### Usar um recurso de proxy para simplificar a configuração de API
À medida que os negócios crescem, o proprietário da PetStore pode decidir adicionar alimentos, brinquedos e outros itens relacionados a animais de estimação para venda. Para oferecer suporte a isso, você pode adicionar `/food`, `/toys` e outros recursos ao recurso raiz. Em cada categoria de venda, você também pode adicionar mais recursos, como `/food/{type}/{item}`, `/toys/{type}/{item}`, etc. Isso pode ser entediante. Se você decidir adicionar uma camada intermediária `{subtype}` aos caminhos de recursos para alterar a hierarquia de caminhos em `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc., as alterações romperão a configuração da API existente. Para evitar isso, você pode usar um [recurso de proxy](api-gateway-set-up-simple-proxy.md) do API Gateway para expor um conjunto de recursos da API simultaneamente.
O API Gateway define um recurso de proxy como um espaço reservado para um recurso a ser especificado quando a solicitação é enviada. Um recurso de proxy é expresso por um parâmetro de caminho especial `{proxy+}`, geralmente conhecido como um parâmetro de caminho voraz. O sinal `+` indica os recursos filho que estão anexados a ele. O espaço reservado `/parent/{proxy+}` representa qualquer recurso que corresponda ao padrão de caminho de `/parent/*`. Você pode usar qualquer string para o nome do parâmetro de caminho voraz.
O comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) indicado abaixo cria um recurso de proxy sob a raiz (`/{proxy+}`):
```
aws apigateway create-resource --rest-api-id apiId \
--parent-id rootResourceId \
--path-part {proxy+}
```
A saída será exibida da seguinte forma:
```
{
"path": "/{proxy+}",
"pathPart": "{proxy+}",
"id": "234jdr",
"parentId": "svzr2028x8"
}
```
Para o exemplo de API `PetStore`, você pode usar `/{proxy+}` para representar o `/pets` e o `/pets/{petId}`. Esse recurso de proxy também pode fazer referência a qualquer outro recurso (existente ou a ser adicionado), como `/food/{type}/{item}`, `/toys/{type}/{item}`, etc., ou `/food/{type}/{subtype}/{item}`, `/toys/{type}/{subtype}/{item}`, etc. O desenvolvedor de backend determina a hierarquia de recursos, e o desenvolvedor do cliente é responsável por entendê-la. O API Gateway simplesmente transfere o que o cliente enviou ao backend.
Uma API pode ter mais de um recurso de proxy. Por exemplo, os recursos de proxy a seguir são permitidos em uma API, pressupondo-se que `/parent/{proxy+}` não seja o mesmo proxy principal que `/parent/{child}/{proxy+}`.
```
/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}
```
Quando um recurso de proxy tem irmãos não proxy, os recursos irmãos são excluídos da representação do recurso de proxy. Para os exemplos anteriores, `/{proxy+}` refere-se a todos os recursos sob o recurso raiz, exceto os recursos `/parent[/*]`. Ou seja, uma solicitação de método em um recurso específico tem precedência sobre uma solicitação de método em um recurso genérico no mesmo nível da hierarquia de recursos.
A tabela abaixo mostra como o API Gateway encaminha solicitações aos recursos a seguir para o estágio `prod` de uma API.
```
ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog
```
| Solicitação | Rota selecionada | Explicação |
| --- | --- | --- |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | A solicitação corresponde totalmente a esse recurso. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | A variável de caminho voraz `/pets/{proxy+}` captura essa solicitação. |
| `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | A variável de caminho voraz `/{proxy+}` captura essa solicitação. |
Um recurso de proxy não pode ter nenhum recurso filho. Qualquer recurso de API após `{proxy+}` é redundante e ambíguo. Os seguintes recursos de proxy não são permitidos dentro de uma API.
```
/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}
```
## Configurar um método HTTP
Uma solicitação de método de API é encapsulada pelo recurso [Método](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) do API Gateway. Para configurar a solicitação de método, você deve primeiro instanciar o recurso `Method`, definindo pelo menos um método HTTP e um tipo de autorização no método.
Intimamente associado ao recurso de proxy, o API Gateway oferece suporte a um método HTTP de `ANY`. Esse método `ANY` representa qualquer método HTTP que deve ser fornecido em tempo de execução. Ele permite usar uma única configuração de método de API para todos os métodos HTTP com suporte de `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`.
Você também pode configurar o método `ANY` em um recurso de proxy. Combinando o método `ANY` com um recurso de proxy, você obtém uma única configuração de método de API para todos os métodos HTTP com suporte em qualquer recurso de uma API. Além disso, o backend pode evoluir sem romper a configuração da API existente.
Antes de definir um método de API, considere quem pode chamar o método. Defina o tipo de autorização de acordo com seu plano. Para acesso aberto, defina-o como `NONE`. Para usar permissões do IAM, defina o tipo de autorização como `AWS_IAM`. Para usar uma função de autorizador do Lambda, defina essa propriedade como `CUSTOM`. Para usar um grupo de usuários do Amazon Cognito, defina o tipo de autorização como `COGNITO_USER_POOLS`.
O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) a seguir cria uma solicitação de método para o verbo `ANY` usando permissões do IAM para controlar o respectivo acesso.
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method ANY \
--authorization-type AWS_IAM
```
Para criar uma solicitação de método de API com um tipo de autorização diferente, consulte [Configurar a autorização de solicitação de método](#setup-method-request-authorization).
## Configurar parâmetros da solicitação de método
Os parâmetros da solicitação de método são uma forma de um cliente fornecer dados de entrada ou o contexto de execução necessário para concluir a solicitação de método. Um parâmetro de método pode ser um parâmetro de caminho, um cabeçalho ou um parâmetro de string de consulta. Como parte da configuração de solicitação de método, você deve declarar os parâmetros de solicitação necessários para disponibilizá-los para o cliente. Para a integração não proxy, você pode converter esses parâmetros de solicitação em um formulário que seja compatível com o requisito de backend.
Por exemplo, para a solicitação de método `GET /pets/{petId}`, a variável de caminho `{petId}` é um parâmetro de solicitação necessário. Você pode declarar esse parâmetro de caminho ao chamar o comando `put-method` da AWS CLI. O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria um método com um parâmetro de caminho necessário:
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id rjkmth \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.path.petId=true
```
Se um parâmetro não for necessário, você poderá configurá-lo como `false` em `request-parameters`. Por exemplo, se o método `GET /pets` usar um parâmetro de string de consulta opcional de `type` e um parâmetro de cabeçalho opcional de `age`, você pode declará-los usando o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo:
```
aws apigateway put-method --rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--authorization-type "NONE" \
--request-parameters method.request.querystring.type=false,method.request.header.age=false
```
Em vez desse formulário resumido, você pode usar uma string JSON para definir o valor `request-parameters`:
```
'{"method.request.querystring.type":false,"method.request.header.age":false}'
```
Com essa configuração, o cliente pode consultar animais de estimação por tipo:
```
GET /pets?type=dog
```
E pode realizar uma consulta de filhotes caninos da seguinte forma:
```
GET /pets?type=dog
age:puppy
```
Para obter informações sobre como mapear parâmetros da solicitação de método para parâmetros de solicitação de integração, consulte [Integrações para APIs REST no API Gateway](how-to-integration-settings.md).
## Configurar um modelo de solicitação de método
Para um método de API que possa levar dados de entrada em uma carga útil, você pode usar um modelo. Um modelo é expresso em um [esquema JSON rascunho 4](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) e descreve a estrutura de dados do corpo da solicitação. Com um modelo, um cliente pode determinar como construir uma carga útil de solicitação de método como entrada. Mais importante, o API Gateway usa o modelo para [validar uma solicitação](api-gateway-method-request-validation.md), [gerar um SDK](how-to-generate-sdk.md) e inicializar um modelo de mapeamento para configurar a integração no console do API Gateway. Para ter informações sobre como criar um [modelo](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), consulte [Noções básicas dos modelos de dados](models-mappings-models.md).
Dependendo dos tipos de conteúdo, uma carga útil de método pode ter diferentes formatos. Um modelo é indexado no tipo de mídia da carga útil aplicada. O API Gateway usa o cabeçalho `Content-Type` da solicitação para determinar o tipo de conteúdo. Para configurar modelos de solicitação de método, adicione pares de chave-valor no formato `"media-type":"model-name"` ao mapa `requestModels` ao chamar o comando AWS CLI da `put-method`.
Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique `$default` como a chave.
Por exemplo, para definir um modelo na carga útil JSON da solicitação de método `POST /pets` da API de exemplo PetStore, você pode usar o comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo:
```
aws apigateway put-method \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method POST \
--authorization-type "NONE" \
--request-models '{"application/json":"petModel"}'
```
Aqui, `petModel` é o valor de propriedade `name` de um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) que descreve um animal de estimação. A definição de esquema JSON real é expressa como um valor de string JSON da propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema) do recurso `Model`.
Em um Java ou outro SDK fortemente tipado, da API, os dados de entrada são emitidos como a classe `petModel` derivada da definição de esquema. Com o modelo de solicitação, os dados de entrada no SDK gerado são convertidos na classe `Empty`, que é derivada do modelo `Empty` padrão. Nesse caso, o cliente não pode instanciar a classe de dados correta para fornecer a entrada necessária.
## Configurar a autorização de solicitação de método
Para controlar quem pode chamar o método de API, você pode configurar o [tipo de autorização](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) no método. Você pode usar esse tipo para adotar um dos autorizadores com suporte, incluindo funções e políticas do IAM (`AWS_IAM`), um grupo de usuários do Amazon Cognito (`COGNITO_USER_POOLS`) ou um autorizador do Lambda (`CUSTOM`).
Para usar permissões do IAM para autorizar o acesso ao método de API, defina a propriedade de entrada `authorization-type` como **AWS\$1IAM**. Ao definir essa opção, o API Gateway verifica a assinatura do autor da chamada na solicitação, com base nas credenciais do autor da chamada. Se o usuário verificado tiver permissão para chamar o método, ela será aceita. Caso contrário, a solicitação será rejeitada, e o autor da chamada receberá uma resposta de erro não autorizada. A chamada para o método não é bem-sucedida, a menos que o autor da chamada tenha permissão para invocar o método da API. A seguinte política do IAM concede permissão ao autor da chamada para chamar qualquer método de API criado na mesma Conta da AWS:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": "arn:aws:execute-api:*:*:*"
}
]
}
```
------
Para obter mais informações, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md).
Atualmente, você só pode conceder essa política aos usuários, grupos e funções na Conta da AWS do proprietário da API. Os usuários de outra Conta da AWS poderão chamar os métodos de API somente se eles tiverem permissão para assumir uma função na Conta da AWS do proprietário da API com as permissões necessárias para chamar a ação `execute-api:Invoke`. Para obter informações sobre as permissões entre contas, consulte [Uso de funções do IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html).
Você pode usar a AWS CLI, um AWS SDK ou um cliente de API REST, como o [Postman](https://www.postman.com/), que implementa a [assinatura do Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html).
Para usar um autorizador do Lambda para autorizar o acesso ao método de API, defina a propriedade de entrada `authorization-type` como `CUSTOM` e defina a propriedade de entrada [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) como o valor da propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) de um autorizador do Lambda que já existe. O autorizador do Lambda referenciado pode ser do tipo `TOKEN` ou `REQUEST`. Para obter mais informações sobre como criar um autorizador do Lambda, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md).
Para usar um grupo de usuários do Amazon Cognito para autorizar o acesso ao método de API, defina a propriedade de entrada `authorization-type` como `COGNITO_USER_POOLS` e defina a propriedade de entrada [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) como o valor da propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) do autorizador `COGNITO_USER_POOLS` que já foi criado. Para obter informações sobre como criar um autorizador do grupo de usuários do Amazon Cognito, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md).
## Configurar a validação da solicitação de método
Você pode habilitar a validação de solicitação ao configurar uma solicitação de método de API. Primeiro, é necessário criar um [validador de solicitação](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html). O comando [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html) a seguir cria um validador somente do corpo da solicitação.
```
aws apigateway create-request-validator \
--rest-api-id 7zw9uyk9kl \
--name bodyOnlyValidator \
--validate-request-body \
--no-validate-request-parameters
```
A saída será exibida da seguinte forma:
```
{
"validateRequestParameters": false,
"validateRequestBody": true,
"id": "jgpyy6",
"name": "bodyOnlyValidator"
}
```
Você pode usar esse validador de solicitação para utilizar a validação de solicitação como parte da configuração de solicitação de método: O comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) indicado abaixo cria uma solicitação de método que exige que o corpo da solicitação de entrada corresponda ao `PetModel` e tem dois parâmetros de solicitação que não são obrigatórios:
```
aws apigateway put-method \
--rest-api-id 7zw9uyk9kl \
--resource-id xdsvhp \
--http-method PUT \
--authorization-type "NONE" \
--request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \
--request-models '{"application/json":"petModel"}' \
--request-validator-id jgpyy6
```
Para incluir um parâmetro de solicitação na respectiva validação, você deve definir `validateRequestParameters` como `true` para o validador da solicitação e definir o parâmetro específico da solicitação como `true` no comando `put-method`.
# Configurar uma resposta de método no API Gateway
Uma resposta de método de API encapsula a saída de uma solicitação de método de API que será recebida pelo cliente. Os dados de saída incluem um código de status HTTP, alguns cabeçalhos e possivelmente um corpo.
Com integrações não proxy, os parâmetros de resposta especificados e o corpo podem ser mapeados dos dados de resposta de integração associados ou podem receber certos valores estáticos de acordo com os mapeamentos. Esses mapeamentos são especificados na resposta de integração. O mapeamento pode ser uma transformação idêntica que passe pela resposta de integração no estado em que se encontra.
Com uma integração de proxy, o API Gateway passa a resposta de backend para a resposta de método automaticamente. Não há necessidade de configurar a resposta de método de API. No entanto, com a integração do proxy do Lambda, a função do Lambda deve retornar um resultado [desse formato de saída](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) para o API Gateway mapear com êxito a resposta de integração a uma resposta de método.
Programaticamente, a configuração da resposta de método equivale à criação de um recurso [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) do API Gateway e à definição das propriedades de [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) e [responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels).
Ao definir os códigos de status de um método de API, você deve escolher um como o padrão para lidar com qualquer resposta de integração de um código de status imprevisto. É razoável definir `500` como padrão, pois isso equivale à geração de respostas não mapeadas de outra forma como um erro no servidor. Por motivos educacionais, o console do API Gateway define a resposta `200` como padrão. No entanto, você pode redefini-la como a resposta `500`.
Para configurar uma resposta de método, você deve ter criado a solicitação de método.
## Configurar o código de status de resposta de método
O código de status de uma resposta de método define um tipo de resposta. Por exemplo, as respostas 200, 400 e 500 indicam respostas bem-sucedidas de erros no servidor e no cliente, respectivamente.
Para configurar um código de status de resposta de método, defina a propriedade [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) como um código de status HTTP. O comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) a seguir cria uma resposta de método `200`.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200
```
## Configurar parâmetros da resposta de método
Os parâmetros da resposta de método definem quais cabeçalhos o cliente recebe em resposta à solicitação de método associada. Os parâmetros de resposta também especificam um destino para o qual o API Gateway mapeia um parâmetro de resposta de integração de acordo com os mapeamentos prescritos na resposta de integração do método de API.
Para configurar os parâmetros de resposta de método, adicione ao mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) de pares de chave-valor `MethodResponse` do formato `"{parameter-name}":"{boolean}"`. O comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) a seguir define o cabeçalho `my-header`.
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false
```
## Configurar modelos de resposta de método
Um modelo de resposta de método define um formato do corpo de resposta de método. A configuração de um modelo de resposta de método é necessária quando você gera um SDK fortemente tipado para a API. Ela garante que a saída seja gerada em uma classe apropriada em Java ou Objective-C. Em outros casos, a definição de um modelo é opcional.
Antes de configurar o modelo de resposta, você deve primeiro criar o modelo no API Gateway. Para fazer isso, você pode chamar o comando `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)`. O comando [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) a seguir cria o modelo `PetStorePet` para descrever o corpo da resposta à solicitação do método `GET /pets/{petId}`.
```
aws apigateway create-model \
--rest-api-id vaz7da96z6 \
--content-type application/json \
--name PetStorePet \
--schema '{ \
"$schema": "http://json-schema.org/draft-04/schema#", \
"title": "PetStorePet", \
"type": "object", \
"properties": { \
"id": { "type": "number" }, \
"type": { "type": "string" }, \
"price": { "type": "number" } \
} \
}'
```
O resultado é criado como um recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) do API Gateway.
Para configurar os modelos de resposta de método a fim de definir o formato de carga útil, adicione o par de chave-valor "application/json":"PetStorePet" ao mapa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) do recurso [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). O comando [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html) indicado abaixo cria uma resposta de método que usa um modelo de resposta para definir o formato da carga útil:
```
aws apigateway put-method-response \
--rest-api-id vaz7da96z6 \
--resource-id 6sxz2j \
--http-method GET \
--status-code 200 \
--response-parameters method.response.header.my-header=false \
--response-models '{"application/json":"PetStorePet"}'
```
# Configurar um método usando o console do API Gateway
Ao criar um método usando o console da API REST, você configura a solicitação de integração e a solicitação de método. Por padrão, o API Gateway cria a resposta do método `200` para seu método.
As instruções a seguir mostram como editar as configurações de solicitação de método e como criar respostas de método adicionais para seu método.
**Topics**
+ [Editar uma solicitação de método do API Gateway no console do API Gateway](#how-to-method-settings-callers-console)
+ [Configurar uma resposta do método API Gateway usando o console do API Gateway](#how-to-method-response-settings-console)
## Editar uma solicitação de método do API Gateway no console do API Gateway
Estas instruções supõem que você já criou sua solicitação de método. Para saber mais sobre como criar um método, consulte [Configurar uma solicitação de integração de API usando o console do API Gateway](how-to-method-settings-console.md).
1. No painel **Recursos**, escolha o método e selecione a guia **Solicitação de método**.
1. Na seção **Configurações de solicitação de método**, selecione **Editar**.
1. Em **Autorização**, selecione um autorizador disponível.
1. Para habilitar o acesso aberto ao método para qualquer usuário, selecione **Nenhum**. Essa etapa poderá ser ignorada se a configuração padrão não tiver sido alterada.
1. Para usar permissões do IAM para controlar o acesso do cliente ao método, selecione `AWS_IAM`. Com essa opção, somente os usuários das funções do IAM com a política do IAM correta anexada terão permissão para chamar esse método.
Para criar a função do IAM, especifique uma política de acesso com um formato semelhante ao seguinte:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/"
]
}
]
}
```
------
Nesta política de acesso, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` é o ARN do seu método. Você pode encontrar o ARN do seu método selecionando o método na página **Recursos**. Para obter mais informações sobre como definir as permissões do IAM, consulte [Controlar o acesso a uma API REST com permissões do IAM](permissions.md).
Para criar um perfil do IAM, é possível adaptar as instruções no seguinte tutorial: [Criar uma função do Lambda para integração não proxy do Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda).
1. Para usar um autorizador do Lambda, selecione um autorizador de solicitação ou token. Crie um autorizador do Lambda para que essa opção seja exibida no menu suspenso. Para obter informações sobre como criar um autorizador do Lambda, consulte [Usar os autorizadores do API Gateway Lambda](apigateway-use-lambda-authorizer.md).
1. Para usar um grupo de usuários do Amazon Cognito, escolha um grupo de usuários disponíveis em **Cognito user pool authorizers (Autorizadores do grupo de usuários do Cognito)**. Crie um grupo de usuários no Amazon Cognito e um autorizador do grupo de usuários do Amazon Cognito no API Gateway para que essa opção seja exibida no menu suspenso. Para obter informações sobre como criar um autorizador do grupo de usuários do Amazon Cognito, consulte [Controlar o acesso a APIs REST usando grupos de usuários do Amazon Cognito como autorizador](apigateway-integrate-with-cognito.md).
1. Para especificar a validação da solicitação, selecione um valor no menu suspenso **Validador de solicitação**. Para desativar a validação da solicitação, selecione **Nenhuma**. Para obter mais informações sobre cada opção, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md).
1. Selecione **Chave de API obrigatória** para exigir uma chave de API. Quando ativadas, as chaves de APIs são usadas em [planos de uso](api-gateway-api-usage-plans.md) para controlar o tráfego do cliente.
1. (Opcional) Para atribuir um nome da operação em um SDK do Java dessa API, gerada pelo API Gateway, em **Nome da operação**, digite um nome. Por exemplo, para a solicitação de método de `GET /pets/{petId}`, o nome da operação de Java SDK correspondente é, por padrão,`GetPetsPetId`. Esse nome é construído a partir do verbo HTTP do método (`GET`) e os nomes de variáveis de caminho de recurso (`Pets` e `PetId`). Se você definir o nome da operação como `getPetById`, o nome da operação de SDK se tornará `GetPetById`.
1. Para adicionar um parâmetro de string de consulta ao método, faça o seguinte:
1. Selecione **Parâmetros de string de consulta de URL** e escolha **Adicionar string de consulta**.
1. Em **Nome**, digite o nome do parâmetro de string de consulta.
1. Selecione **Obrigatório** se o parâmetro de string de consulta recém-criado precisar ser usado para a validação de solicitação. Para obter mais informações sobre a validação de solicitação, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md).
1. Selecione **Armazenamento em cache** se o parâmetro de string de consulta recém-criado precisar ser usado como parte de uma chave de armazenamento em cache. Para obter mais informações sobre armazenamento em cache, consulte [Usar parâmetros de método ou integração como chaves de cache para indexar respostas em cache](api-gateway-caching.md#enable-api-gateway-cache-keys).
Para remover o parâmetro de string de consulta, selecione **Remover**.
1. Para adicionar um parâmetro de cabeçalho ao método, faça o seguinte:
1. Selecione **Cabeçalhos de solicitação HTTP** e, depois, **Adicionar cabeçalho**.
1. Em **Nome**, insira o nome do cabeçalho.
1. Selecione **Obrigatório** se o cabeçalho recém-criado precisar ser usado para a validação de solicitação. Para obter mais informações sobre a validação de solicitação, consulte [Solicitar validação para APIs REST no API Gateway](api-gateway-method-request-validation.md).
1. Selecione **Armazenamento em cache** se o cabeçalho recém-criado precisar ser usado como parte de uma chave de armazenamento em cache. Para obter mais informações sobre armazenamento em cache, consulte [Usar parâmetros de método ou integração como chaves de cache para indexar respostas em cache](api-gateway-caching.md#enable-api-gateway-cache-keys).
Para remover o cabeçalho, selecione **Remover**.
1. Para declarar o formato de carga útil de uma solicitação de método com o verbo HTTP `POST`, `PUT` ou `PATCH`, expanda **Corpo da solicitação** e faça o seguinte:
1. Escolha **Add model** (Adicionar modelo).
1. Em **Tipo de conteúdo**, insira um tipo MIME (por exemplo, `application/json`).
1. Em **Modelo**, selecione um modelo no menu suspenso. Os modelos atualmente disponíveis para a API incluem os modelos padrão `Empty` e `Error`, bem como quaisquer modelos que você tenha criado e adicionado à coleção de [Modelos](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) da API. Para obter mais informações sobre a criação de um modelo, consulte [Modelos de dados para APIs REST](models-mappings-models.md).
**nota**
O modelo é útil para informar ao cliente o formato de dados esperado de uma carga útil. Ele é útil para gerar um modelo de mapeamento de esqueleto. É importante gerar um SDK altamente tipado da API em linguagens como Java, C \$1, Objective-C e Swift. Ele só será necessário se a validação de solicitação estiver ativada para a carga útil.
1. Escolha **Salvar**.
## Configurar uma resposta do método API Gateway usando o console do API Gateway
Um método de API pode ter uma ou mais respostas. Cada resposta é indexada por seu código de status HTTP. Por padrão, o console do API Gateway adiciona a resposta `200` às respostas de método. Você pode modificá-la, por exemplo, para que o método retorne `201` em vez disso. Você pode adicionar outras respostas, por exemplo, `409` para negação de acesso e `500` para variáveis de estágio não inicializadas utilizadas.
Para usar o console do API Gateway para modificar, excluir ou adicionar uma resposta a um método de API, siga estas instruções.
1. No painel **Recursos**, escolha o método e selecione a guia **Resposta do método**. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
1. Na seção **Configurações de resposta do método**, selecione **Criar resposta**.
1. Em **Código de status HTTP**, insira um código de status HTTP, como `200`, `400` ou `500`.
Quando uma resposta retornada pelo backend não tiver uma resposta de método correspondente definida, o API Gateway não retornará a resposta para o cliente. Em vez disso, ele retornará uma resposta de erro `500 Internal server error`.
1. Escolha **Add header** (Adicionar cabeçalho).
1. Em **Nome de cabeçalho**, insira um nome.
Para retornar um cabeçalho do back-end para o cliente, adicione o cabeçalho à resposta do método.
1. Selecione **Adicionar modelo** para definir um formato do corpo de resposta de método.
Digite o tipo de mídia da carga útil de resposta para **Tipo de conteúdo** e selecione um modelo no menu suspenso **Modelos**.
1. Escolha **Salvar**.
Para modificar uma resposta existente, acesse a resposta do método e selecione **Editar**. Para alterar o **Código de status HTTP**, selecione **Excluir** e crie uma resposta de método.
Para cada resposta retornada do backend, você deve ter uma resposta compatível configurada como a resposta de método. No entanto, a configuração de cabeçalhos de resposta de método e o modelo de carga útil são opcionais, a menos que você mapeie o resultado do backend para a resposta de método antes de retornar para o cliente. Além disso, um modelo de carga útil de resposta de método é importante se você pretende gerar um SDK fortemente tipado para sua API.