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