Configurar uma solicitação de método no API Gateway - Amazon API Gateway
Configurar recursos da APIConfigurar um método HTTPConfigurar parâmetros da solicitação de métodoConfigurar um modelo de solicitação de métodoConfigurar a autorização de solicitação de métodoConfigurar a validação da solicitação de método

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:

  1. A criação de uma nova API ou a escolha de uma entidade Recurso de API existente.

  2. A criação de um recurso Método 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:

Configurar recursos da API

Em uma API do API Gateway, você expõe recursos endereçáveis como uma árvore de entidades de Recursos 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 {api-id} 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) que você escolheu 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.

Para a API de exemplo PetStore, 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.

Com a AWS CLI, você pode chamar o comando get-resources para descobrir quais recursos de uma API estão disponíveis:

aws apigateway get-resources --rest-api-id <apiId> \
                             --region <region>

O resultado é uma lista dos recursos disponíveis da API no momento. Para o nosso exemplo de API da 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 o pai, chame o comando a seguir para adicionar um recurso filho. 

aws apigateway create-resource --rest-api-id <apiId> \
                             --region <region> \
                             --parent-id <parentId> \
                             --path-part <resourceName>

Por exemplo, para incluir alimento para animais de estimação no site PetStore, adicione um recurso food à raiz (/), definindo path-part como food e parent-id como svzr2028x8. O resultado parece o seguinte:

{
    "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 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/*. O nome de parâmetro de caminho voraz, proxy, pode ser substituído por outra string da mesma maneira que você trata um nome de parâmetro de caminho comum.

Usando a AWS CLI, chame o comando a seguir para configurar um recurso de proxy sob a raiz (/{proxy+}):

aws apigateway create-resource --rest-api-id <apiId> \
                             --region <region> \
                             --parent-id <rootResourceId> \
                             --path-part {proxy+}

O resultado é semelhante ao seguinte:

{
    "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.

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 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 da AWS CLI a seguir mostra como criar uma solicitação de método do verbo ANY em um recurso especificado (6sxz2j) usando as permissões do IAM para controlar o acesso. 

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method ANY \
       --authorization-type AWS_IAM \
       --region us-west-2

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.

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. Isto é ilustrado da seguinte forma:

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id rjkmth \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --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 breed, você pode declará-los usando o seguinte comando da CLI, supondo-se que o recurso /pets id seja 6sxz2j:

aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-parameters method.request.querystring.type=false,method.request.header.breed=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.breed":false}'

Com essa configuração, o cliente pode consultar animais de estimação por tipo: 

GET /pets?type=dog

Além disso, o cliente pode consultar cães da raça poodle da seguinte forma:

GET /pets?type=dog
breed:poodle

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.

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

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 put-method da AWS CLI.

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 chamar o comando da AWS CLI a seguir:

aws apigateway put-method \
       --rest-api-id vaz7da96z6 \
       --resource-id 6sxz2j \
       --http-method POST \
       --authorization-type "NONE" \
       --region us-west-2 \
       --request-models '{"application/json":"petModel"}'

Aqui, petModel é o valor de propriedade name de um recurso Model que descreve um animal de estimação. A definição de esquema JSON real é expressa como um valor de string JSON da propriedade 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 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_IAM. 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: 

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

Para ter mais informações, consulte Controlar o acesso a uma API REST com permissões do IAM.

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.

Você pode usar a AWS CLI, um AWS SDK ou um cliente de API REST, como o Postman, que implementa a assinatura do Signature Version 4 (SigV4).

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 authorizer-id como o valor da propriedade 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.

Para usar um grupo de usuários do Amazon Cognito para autorizar o acesso ao método da API, defina a propriedade de entrada authorization-type como COGNITO_USER_POOLS e defina a propriedade de entrada authorizer-id como o valor da propriedade id do autorizador do 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.

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:

aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters

Esse comando da CLI cria um validador de solicitação somente de corpo. O exemplo de saída é o seguinte:

{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}

Com esse validador de solicitação, você pode ativar a validação de solicitação como parte da configuração de solicitação de método: 

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl 
    --region us-west-2 
    --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 ser incluído na validação de solicitação, um parâmetro de solicitação deve ser declarado, conforme necessário. Se o parâmetro de string de consulta para a página for usado na validação de solicitação, o mapa request-parameters do exemplo anterior deverá ser especificado como '{"method.request.querystring.type": false, "method.request.querystring.page":true}'.