Configurar a validação básica de solicitações no API Gateway - Amazon API Gateway

Configurar a validação básica de solicitações no API Gateway

Esta seção mostra como configurar a validação de solicitações para o API Gateway usando o console, a AWS CLI e uma definição de OpenAPI.

Configurar a validação de solicitação usando o console do API Gateway

Você pode usar o console do API Gateway para validar uma solicitação selecionando um dos três validadores para uma solicitação de API:

  • Validar o corpo.

  • Valide parâmetros e cabeçalhos da string de consulta.

  • Validar o corpo, parâmetros da string de consulta e cabeçalhos

Ao aplicar um dos validadores em um método de API, o console do API Gateway adiciona o validador ao mapa RequestValidators da API.

Para seguir esse tutorial, você usará um modelo AWS CloudFormation para criar uma API incompleta do API Gateway. Essa API tem um recurso /validator com os métodos GET e POST. Os dois métodos são integrados ao endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Você vai configurar dois tipos de validação de solicitação:

  • No método GET, você vai configurar a validação da solicitação para os parâmetros da string de consulta de URL.

  • No método POST, você vai configurar a validação da solicitação para o corpo da solicitação.

Isso vai possibilitar que somente determinadas chamadas de API sejam transmitidas à API.

Baixe e descompacte o modelo de criação de aplicativos para AWS CloudFormation. Você usará esse modelo para criar uma API incompleta. Você concluirá o restante das etapas no console do API Gateway.

Como criar uma pilha do AWS CloudFormation
  1. Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

  2. Selecione Create stack (Criar pilha) e With new resources (standard) (Com novos recursos (padrão)).

  3. Em Specify template (Especificar modelo), escolha Upload a template file (Fazer upload de um arquivo de modelo).

  4. Selecione o modelo que você baixou.

  5. Escolha Next (Próximo).

  6. Em Nome da pilha, insira request-validation-tutorial-console e escolha Avançar.

  7. Para Configurar opções de pilha, escolha Avançar.

  8. Para Capabilities (Recursos), reconheça que AWS CloudFormation pode criar recursos do IAM em sua conta.

  9. Selecione Enviar.

O AWS CloudFormation fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Quando o status da sua pilha do AWS CloudFormation for CREATE_COMPLETE, você estará pronto para passar para a próxima etapa.

Como selecionar sua API recém-criada
  1. Selecione a pilha request-validation-tutorial-console recém-criada.

  2. Escolha atributos.

  3. Em ID físico, escolha sua API. Esse link direcionará você para o console do API Gateway.

Antes de modificar os métodos GETPOST, é necessário criar um modelo.

Como criar um modelo
  1. É necessário um modelo para usar a validação da solicitação no corpo de uma solicitação recebida. Para criar um modelo, no painel de navegação principal, selecione Modelos.

  2. Escolha Criar modelo.

  3. Em Nome, digite PetStoreModel.

  4. Em Tipo de conteúdo, insira application/json. Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, insira $default.

  5. Em Descrição, insira My PetStore Model como descrição do modelo.

  6. Em Esquema do modelo, cole o modelo a seguir no editor de código e escolha Criar.

    { "type" : "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } }

Para obter mais informações sobre o modelo, consulte Noções básicas dos modelos de dados.

Como configurar a validação da solicitação para um método GET
  1. No painel de navegação, selecione Recursos e, depois, selecione o método GET.

  2. Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.

  3. Em Validador de solicitação, selecione Validar parâmetros de string de consulta e cabeçalhos.

  4. Em Parâmetros de string de consulta de URL, faça o seguinte:

    1. Escolha Add query string (Adicionar string de consulta).

    2. Em Nome, digite petType.

    3. Ative a opção Obrigatório.

    4. Mantenha Armazenamento em cache desativado.

  5. Escolha Salvar.

  6. Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.

  7. Em Parâmetros de string de consulta de URL, faça o seguinte:

    1. Escolha Add query string (Adicionar string de consulta).

    2. Em Nome, digite petType.

    3. Em Mapeado de, insira method.request.querystring.petType. Isso associa o petType ao tipo do animal de estimação.

      Para ter mais informações sobre mapeamento de dados, consulte  o tutorial de mapeamento de dados.

    4. Mantenha Armazenamento em cache desativado.

  8. Escolha Salvar.

Como testar a validação da solicitação para o método GET
  1. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

  2. Em Strings de consulta, insira petType=dog e escolha Testar.

  3. O teste de método vai gerar 200 OK e uma lista de cães.

    Para ter informações sobre como transformar esses dados de saída, consulte o tutorial de mapeamento de dados.

  4. Remova petType=dog e escolha Testar.

  5. O teste de método vai gerar um erro 400 com a seguinte mensagem de erro:

    { "message": "Missing required request parameters: [petType]" }
Como configurar a validação da solicitação para o método POST
  1. No painel de navegação principal, selecione Recursos e, depois, selecione o método POST.

  2. Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.

  3. Em Validador de solicitação, selecione Validar corpo.

  4. Em Corpo da solicitação, escolha Adicionar modelo.

  5. Em Tipo de conteúdo, insira application/json e, em Modelo, selecione PetStoreModel.

  6. Escolha Salvar.

Como testar a validação da solicitação para um método POST
  1. Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.

  2. Em Corpo da solicitação, cole o seguinte no editor de código:

    { "id": 2, "name": "Bella", "type": "dog", "price": 400 }

    Escolha Testar.

  3. O teste de método vai gerar 200 OK e uma mensagem de êxito.

  4. Em Corpo da solicitação, cole o seguinte no editor de código:

    { "id": 2, "name": "Bella", "type": "dog", "price": 4000 }

    Escolha Testar.

  5. O teste de método vai gerar um erro 400 com a seguinte mensagem de erro:

    { "message": "Invalid request body" }

    Na parte inferior dos logs de teste, o motivo do corpo de solicitação inválido será exibido. Nesse caso, o preço do animal de estimação estava fora do máximo especificado no modelo.

Para excluir uma pilha do AWS CloudFormation
  1. Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation.

  2. Selecione sua pilha do AWS CloudFormation.

  3. Escolha Excluir e, em seguida, confirme sua escolha.

Próximas etapas

Configurar a validação básica de solicitações usando a AWS CLI

Você pode criar um validador para configurar a validação da solicitação usando a AWS CLI. Para seguir esse tutorial, você usará um modelo AWS CloudFormation para criar uma API incompleta do API Gateway.

nota

Esse não é o mesmo modelo AWS CloudFormation do tutorial do console.

Usando um recurso /validator pré-exposto, você criará os métodos GET e POST. Os dois métodos serão integrados ao endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Você vai configurar as duas validações de solicitação a seguir:

  • No método GET, você criará um validador params-only para validar os parâmetros da string de consulta de URL.

  • No método POST, você criará um validador body-only para validar o corpo da solicitação.

Isso vai possibilitar que somente determinadas chamadas de API sejam transmitidas à API.

Como criar uma pilha do AWS CloudFormation

Baixe e descompacte o modelo de criação de aplicativos para AWS CloudFormation.

Para concluir o tutorial a seguir, é necessária a AWS Command Line Interface (AWS CLI) versão 2.

Para comandos longos, um caractere de escape (\) é usado para dividir um comando em várias linhas.

nota

No Windows, alguns comandos da CLI do Bash que você costuma usar (como zip) não são compatíveis com os terminais integrados do sistema operacional. Para obter uma versão do Ubuntu com o Bash integrada no Windows, instale o Subsistema do Windows para Linux. Os exemplos de comandos da CLI neste guia usam a formatação Linux. Os comandos que incluem documentos JSON em linha deverão ser reformatados se você estiver usando a CLI do Windows.

  1. Use o comando a seguir para criar a pilha de AWS CloudFormation.

    aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM
  2. O AWS CloudFormation fornece os recursos especificados no modelo. Pode demorar alguns minutos para concluir o provisionamento de seus recursos. Use o comando a seguir para ver o status de sua pilha de AWS CloudFormation.

    aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
  3. Quando o status da sua pilha de AWS CloudFormation for StackStatus: "CREATE_COMPLETE", use o comando a seguir para recuperar valores de saída relevantes para etapas futuras.

    aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}"

    Os valores de saída são os seguintes:

    • ApiId, que é o ID da API. Para este tutorial, o ID da API é abc123.

    • ResourceId, que é a ID do recurso validador em que os métodos GET e POST são expostos. Para este tutorial, o ID do recurso é efg456.

Como criar os validadores de solicitação e importar um modelo
  1. É necessário um validador para usar a validação da solicitação com o AWS CLI. Use o comando a seguir para criar um validador que valide somente os parâmetros da solicitação.

    aws apigateway create-request-validator --rest-api-id abc123 \ --no-validate-request-body \ --validate-request-parameters \ --name params-only

    Anote o ID do validador params-only.

  2. Use o comando a seguir para criar um validador que valide somente o corpo da solicitação.

    aws apigateway create-request-validator --rest-api-id abc123 \ --validate-request-body \ --no-validate-request-parameters \ --name body-only

    Anote o ID do validador body-only.

  3. É necessário um modelo para usar a validação da solicitação no corpo de uma solicitação recebida. Use o comando a seguir para importar um modelo.

    aws apigateway create-model --rest-api-id abc123 --name PetStoreModel --description 'My PetStore Model' --content-type 'application/json' --schema '{"type": "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : {"type" : "integer"},"type" : {"type" : "string", "enum" : [ "dog", "cat", "fish" ]},"name" : { "type" : "string"},"price" : {"type" : "number","minimum" : 25.0, "maximum" : 500.0}}}}'

    Se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique $default como a chave.

Como criar os métodos GET e POST
  1. Use o comando a seguir para adicionar o método HTTP GET ao recurso /validate. Esse comando cria o método GET, adiciona o validador params-only e define a string de consulta petType conforme necessário.

    aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --authorization-type "NONE" \ --request-validator-id aaa111 \ --request-parameters "method.request.querystring.petType=true"

    Use o comando a seguir para adicionar o método HTTP POST ao recurso /validate. Esse comando cria o método POST, adiciona o validador body-only e anexa o modelo ao validador exclusivo do corpo.

    aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ --request-validator-id bbb222 \ --request-models 'application/json'=PetStoreModel
  2. Use o comando a seguir para configurar a reposta 200 OK do método como GET /validate.

    aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200

    Use o comando a seguir para configurar a reposta 200 OK do método como POST /validate.

    aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200
  3. Use o comando a seguir para configurar uma Integration com um endpoint HTTP especificado para o método GET /validation.

    aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --type HTTP \ --integration-http-method GET \ --request-parameters '{"integration.request.querystring.type" : "method.request.querystring.petType"}' \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'

    Use o comando a seguir para configurar uma Integration com um endpoint HTTP especificado para o método POST /validation.

    aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type HTTP \ --integration-http-method GET \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets'
  4. Use o comando a seguir para configurar a resposta de integração do método GET /validation.

    aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456\ --http-method GET \ --status-code 200 \ --selection-pattern ""

    Use o comando a seguir para configurar a resposta de integração do método POST /validation.

    aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern ""
Como testar a API
  1. Para testar o método GET, que executará a validação da solicitação para as strings de consulta, use o seguinte comando:

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --path-with-query-string '/validate?petType=dog'

    O resultado retornará 200 OK e uma lista de cães.

  2. Use o comando a seguir para testar sem incluir a string de consulta petType.

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET

    O resultado retornará um erro 400.

  3. Para testar o método POST, que executará a validação da solicitação para o corpo da string, use o seguinte comando:

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'

    O resultado retornará 200 OK e uma mensagem de êxito.

  4. Use o comando a seguir para testar usando um corpo inválido.

    aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 1000 }'

    O resultado retornará um erro 400, pois o preço do cachorro está acima do preço máximo definido pelo modelo.

Para excluir uma pilha do AWS CloudFormation
  • Use o comando a seguir para excluir seus recursos de AWS CloudFormation.

    aws cloudformation delete-stack --stack-name request-validation-tutorial-cli

Configurar a validação básica de solicitações importando a definição de OpenAPI

Você pode declarar um validador de solicitação no nível da API especificando um conjunto de objetos Objeto x-amazon-apigateway-request-validators.requestValidator no mapa Objeto x-amazon-apigateway-request-validators para selecionar qual parte da solicitação será validada. No exemplo de definição de OpenAPI, há dois validadores:

  • O validador all que valida o corpo, usando o modelo de dados RequestBodyModel, e os parâmetros.

  • param-only que valida somente os parâmetros.

Para ativar um validador de solicitação em todos os métodos de uma API, especifique uma propriedade Propriedade x-amazon-apigateway-request-validator em nível de API da definição de OpenAPI. Na definição de OpenAPI de exemplo, o validador all é usado em todos os métodos de API, a menos que ele seja substituído de outra forma. Ao usar um modelo para validar o corpo, se nenhum tipo de conteúdo correspondente for encontrado, a validação da solicitação não será executada. Para usar o mesmo modelo, independentemente do tipo de conteúdo, especifique $default como a chave.

Para ativar um validador de solicitação em um método individual, especifique a propriedade x-amazon-apigateway-request-validator no nível do método. No exemplo, definição de OpenAPI, o validador param-only sobrescreve o validador all no método GET.

Para importar o exemplo de OpenAPI para o API Gateway, consulte as instruções a seguir para Importar uma API regional para o API Gateway ou Importar uma API otimizada para bordas para o API Gateway.

OpenAPI 3.0
{ "openapi" : "3.0.1", "info" : { "title" : "ReqValidators Sample", "version" : "1.0.0" }, "servers" : [ { "url" : "/{basePath}", "variables" : { "basePath" : { "default" : "/v1" } } } ], "paths" : { "/validation" : { "get" : { "parameters" : [ { "name" : "q1", "in" : "query", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response", "headers" : { "test-method-response-header" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArrayOfError" } } } } }, "x-amazon-apigateway-request-validator" : "params-only", "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.type" : "method.request.querystring.q1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } }, "post" : { "parameters" : [ { "name" : "h1", "in" : "header", "required" : true, "schema" : { "type" : "string" } } ], "requestBody" : { "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/RequestBodyModel" } } }, "required" : true }, "responses" : { "200" : { "description" : "200 response", "headers" : { "test-method-response-header" : { "schema" : { "type" : "string" } } }, "content" : { "application/json" : { "schema" : { "$ref" : "#/components/schemas/ArrayOfError" } } } } }, "x-amazon-apigateway-request-validator" : "all", "x-amazon-apigateway-integration" : { "httpMethod" : "POST", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.custom_h1" : "method.request.header.h1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "components" : { "schemas" : { "RequestBodyModel" : { "required" : [ "name", "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "maximum" : 500.0, "minimum" : 25.0, "type" : "number" } } }, "ArrayOfError" : { "type" : "array", "items" : { "$ref" : "#/components/schemas/Error" } }, "Error" : { "type" : "object" } } }, "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestParameters" : true, "validateRequestBody" : true }, "params-only" : { "validateRequestParameters" : true, "validateRequestBody" : false } } }
OpenAPI 2.0
{ "swagger" : "2.0", "info" : { "version" : "1.0.0", "title" : "ReqValidators Sample" }, "basePath" : "/v1", "schemes" : [ "https" ], "paths" : { "/validation" : { "get" : { "produces" : [ "application/json", "application/xml" ], "parameters" : [ { "name" : "q1", "in" : "query", "required" : true, "type" : "string" } ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/ArrayOfError" }, "headers" : { "test-method-response-header" : { "type" : "string" } } } }, "x-amazon-apigateway-request-validator" : "params-only", "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.type" : "method.request.querystring.q1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } }, "post" : { "consumes" : [ "application/json" ], "produces" : [ "application/json", "application/xml" ], "parameters" : [ { "name" : "h1", "in" : "header", "required" : true, "type" : "string" }, { "in" : "body", "name" : "RequestBodyModel", "required" : true, "schema" : { "$ref" : "#/definitions/RequestBodyModel" } } ], "responses" : { "200" : { "description" : "200 response", "schema" : { "$ref" : "#/definitions/ArrayOfError" }, "headers" : { "test-method-response-header" : { "type" : "string" } } } }, "x-amazon-apigateway-request-validator" : "all", "x-amazon-apigateway-integration" : { "httpMethod" : "POST", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "400", "responseParameters" : { "method.response.header.test-method-response-header" : "'static value'" }, "responseTemplates" : { "application/xml" : "xml 400 response template", "application/json" : "json 400 response template" } }, "2\\d{2}" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.custom_h1" : "method.request.header.h1" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "definitions" : { "RequestBodyModel" : { "type" : "object", "required" : [ "name", "price", "type" ], "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "name" : { "type" : "string" }, "price" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } }, "ArrayOfError" : { "type" : "array", "items" : { "$ref" : "#/definitions/Error" } }, "Error" : { "type" : "object" } }, "x-amazon-apigateway-request-validators" : { "all" : { "validateRequestParameters" : true, "validateRequestBody" : true }, "params-only" : { "validateRequestParameters" : true, "validateRequestBody" : false } } }