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.
Tópicos
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
Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation
. -
Selecione Create stack (Criar pilha) e With new resources (standard) (Com novos recursos (padrão)).
-
Em Specify template (Especificar modelo), escolha Upload a template file (Fazer upload de um arquivo de modelo).
-
Selecione o modelo que você baixou.
-
Escolha Next (Próximo).
-
Em Nome da pilha, insira
request-validation-tutorial-console
e escolha Avançar. -
Para Configurar opções de pilha, escolha Avançar.
-
Para Capabilities (Recursos), reconheça que AWS CloudFormation pode criar recursos do IAM em sua conta.
-
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
Selecione a pilha
request-validation-tutorial-console
recém-criada.Escolha atributos.
Em ID físico, escolha sua API. Esse link direcionará você para o console do API Gateway.
Antes de modificar os métodos GET
e POST
, é necessário criar um modelo.
Como criar um modelo
-
É 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.
-
Escolha Criar modelo.
-
Em Nome, digite
PetStoreModel
. -
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
. -
Em Descrição, insira
My PetStore Model
como descrição do modelo. -
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 Modelos de dados para APIs REST.
Como configurar a validação da solicitação para um método GET
-
No painel de navegação, selecione Recursos e, depois, selecione o método GET.
-
Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.
-
Em Validador de solicitação, selecione Validar parâmetros de string de consulta e cabeçalhos.
Em Parâmetros de string de consulta de URL, faça o seguinte:
Escolha Add query string (Adicionar string de consulta).
Em Nome, digite
petType
.Ative a opção Obrigatório.
Mantenha Armazenamento em cache desativado.
-
Escolha Salvar.
-
Na guia Solicitação de integração, em Configurações de solicitação de integração, selecione Editar.
Em Parâmetros de string de consulta de URL, faça o seguinte:
Escolha Add query string (Adicionar string de consulta).
Em Nome, digite
petType
.Em Mapeado de, insira
method.request.querystring.petType
. Isso associa opetType
ao tipo do animal de estimação.Para ter mais informações sobre mapeamento de dados, consulte o tutorial de mapeamento de dados.
Mantenha Armazenamento em cache desativado.
Escolha Salvar.
Como testar a validação da solicitação para o método GET
-
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
-
Em Strings de consulta, insira
petType=dog
e escolha Testar. -
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.
-
Remova
petType=dog
e escolha Testar. -
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
-
No painel de navegação principal, selecione Recursos e, depois, selecione o método POST.
-
Na guia Solicitação de método, em Configurações de solicitação de método, escolha Editar.
-
Em Validador de solicitação, selecione Validar corpo.
-
Em Corpo da solicitação, escolha Adicionar modelo.
-
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
.Em Modelo, selecione PetStoreModel.
Escolha Salvar.
Como testar a validação da solicitação para um método POST
-
Selecione a guia Testar. Talvez seja necessário selecionar o botão de seta para a direita para mostrar a guia.
-
Em Corpo da solicitação, cole o seguinte no editor de código:
{ "id": 2, "name": "Bella", "type": "dog", "price": 400 }
Escolha Testar.
-
O teste de método vai gerar
200 OK
e uma mensagem de êxito. -
Em Corpo da solicitação, cole o seguinte no editor de código:
{ "id": 2, "name": "Bella", "type": "dog", "price": 4000 }
Escolha Testar.
-
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
Abra o console do AWS CloudFormation em https://console.aws.amazon.com/cloudformation
. -
Selecione sua pilha do AWS CloudFormation.
-
Escolha Excluir e, em seguida, confirme sua escolha.
Próximas etapas
Para ter informações sobre como transformar os dados de saída e realizar o mapeamento de mais dados, consulte o tutorial de mapeamento de dados.
Siga o tutorial Configurar a validação básica da solicitação usando o AWS CLI, para realizar etapas semelhantes usando a AWS CLI.
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 validadorparams-only
para validar os parâmetros da string de consulta de URL. -
No método
POST
, você criará um validadorbody-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
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
-
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
-
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
ePOST
são expostos. Para este tutorial, o ID do recurso éefg456
.
Como criar os validadores de solicitação e importar um modelo
-
É 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-onlyAnote o ID do validador
params-only
. -
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-onlyAnote o ID do validador
body-only
. -
É 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
-
Use o comando a seguir para adicionar o método HTTP
GET
ao recurso/validate
. Esse comando cria o métodoGET
, adiciona o validadorparams-only
e define a string de consultapetType
conforme necessário.aws apigateway put-method --rest-api-id
abc123
\ --resource-idefg456
\ --http-method GET \ --authorization-type "NONE" \ --request-validator-idaaa111
\ --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étodoPOST
, adiciona o validadorbody-only
e anexa o modelo ao validador exclusivo do corpo.aws apigateway put-method --rest-api-id
abc123
\ --resource-idefg456
\ --http-method POST \ --authorization-type "NONE" \ --request-validator-idbbb222
\ --request-models 'application/json'=PetStoreModel -
Use o comando a seguir para configurar a reposta
200 OK
do método comoGET /validate
.aws apigateway put-method-response --rest-api-id
abc123
\ --resource-idefg456
\ --http-method GET \ --status-code 200Use o comando a seguir para configurar a reposta
200 OK
do método comoPOST /validate
.aws apigateway put-method-response --rest-api-id
abc123
\ --resource-idefg456
\ --http-method POST \ --status-code 200 -
Use o comando a seguir para configurar uma
Integration
com um endpoint HTTP especificado para o métodoGET /validation
.aws apigateway put-integration --rest-api-id
abc123
\ --resource-idefg456
\ --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étodoPOST /validation
.aws apigateway put-integration --rest-api-id
abc123
\ --resource-idefg456
\ --http-method POST \ --type HTTP \ --integration-http-method GET \ --uri 'http://petstore-demo-endpoint.execute-api.com/petstore/pets' -
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-idefg456
\ --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-idefg456
\ --http-method POST \ --status-code 200 \ --selection-pattern ""
Como testar a API
-
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-idefg456
\ --http-method GET \ --path-with-query-string '/validate?petType=dog'O resultado retornará
200 OK
e uma lista de cães. -
Use o comando a seguir para testar sem incluir a string de consulta
petType
.aws apigateway test-invoke-method --rest-api-id
abc123
\ --resource-idefg456
\ --http-method GETO resultado retornará um erro
400
. -
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-idefg456
\ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'O resultado retornará
200 OK
e uma mensagem de êxito. -
Use o comando a seguir para testar usando um corpo inválido.
aws apigateway test-invoke-method --rest-api-id
abc123
\ --resource-idefg456
\ --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 dadosRequestBodyModel
, e os parâmetros.O modelo de dados
RequestBodyModel
requer que o objeto JSON de entrada contenha as propriedadesname
,type
eprice
. A propriedadename
pode ser qualquer string,type
deve ser um dos campos de enumeração especificados (["dog", "cat", "fish"]
) eprice
deve variar entre 25 e 500. O parâmetroid
não é necessário.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.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 } } }