Configurar uma solicitação de método no API Gateway

A configuração de uma solicitação de método envolve a execução das seguintes tarefas, depois de criar um RestApirecurso:

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:

• Console do API Gateway

• AWS CLI comandos (create-resource e put-method)

• AWS Funções do SDK (por exemplo, em Node.js, createResource e putMethod)

• API REST do API Gateway (resource:create e method:put).

Para ver exemplos de uso dessas ferramentas, consulte Inicializar a configuração da API REST no API Gateway.

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 PetStore de amostra, o recurso raiz (/) expõe a loja de animais. 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 AWS CLI, você pode chamar o get-resources comando 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 nossa API de PetStore amostra, essa lista tem a seguinte aparência:

{
    "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 adicionar ração para animais de estimação à venda no PetStore site, adicione um food recurso à raiz (/) configurando path-part como food e parent-id parasvzr2028x8. 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

Conforme a empresa cresce, o PetStore proprietário pode decidir adicionar alimentos, brinquedos e outros itens relacionados a animais de estimação à 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 o AWS CLI, você chama o comando a seguir para configurar um recurso de proxy sob o root (/{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 to-be-added)/food/{type}/{item}, como/toys/{type}/{item},, etc./food/{type}/{subtype}/{item}, ou/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 seguintes recursos de proxy são permitidos dentro de uma API.

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

Configurar o 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 valores-chave do "<media-type>":"<model-name>" formato ao requestModels mapa ao chamar o AWS CLI put-method comando.

Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique $default como a chave.

Por exemplo, para definir um modelo na carga JSON da solicitação de POST /pets método da API de PetStore exemplo, você pode chamar o seguinte comando: AWS CLI

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 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. Usuários de outros países só Conta da AWS podem chamar os métodos da API se tiverem permissão para assumir uma função dentro do proprietário da API Conta da AWS com as permissões necessárias para chamar a execute-api:Invoke ação. Para obter informações sobre as permissões entre contas, consulte Uso de funções do IAM.

Você pode usar AWS CLI um AWS SDK ou um cliente de API REST, como o Postman, que implementa o Signature Version 4 Signing.

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 uma API REST usando um grupo 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}'.