Configurazione della convalida di base delle richieste in API Gateway - Amazon API Gateway

Configurazione della convalida di base delle richieste in API Gateway

Questa sezione mostra come configurare la convalida delle richieste per Gateway Amazon API utilizzando la console, AWS CLI e una definizione OpenAPI.

Configurazione della convalida delle richieste tramite la console Gateway Amazon API

È possibile utilizzare la console Gateway Amazon API per convalidare una richiesta selezionando uno dei tre validatori per una richiesta API:

  • Convalida del corpo.

  • Convalida dei parametri e delle intestazioni delle stringhe di query.

  • Convalida del corpo, dei parametri delle stringhe di query e delle intestazioni.

Quando si applica uno dei validatori in un metodo API, la console Gateway Amazon API aggiunge il validatore alla mappa RequestValidators dell'API.

Per seguire questo tutorial, utilizzare un modello AWS CloudFormation per creare un'API Gateway Amazon API incompleta. Questa API ha una risorsa /validator con i metodi GETPOST. Entrambi i metodi sono integrati con l'endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Configurare due tipi di convalida delle richieste:

  • Nel metodo GET, verrà configurata la convalida delle richieste per i parametri della stringa di query URL.

  • Nel metodo POST, verrà configurata la convalida delle richieste per il corpo della richiesta.

Ciò consentirà solo a determinate chiamate API di eseguire il transito all'API.

Scarica e decomprimi il modello di creazione dell'applicazione app per AWS CloudFormation. Verrà utilizzato questo modello per creare un'API incompleta. Il resto della procedura verrà completato nella console Gateway Amazon API.

Creazione di uno stack AWS CloudFormation
  1. Apri la console di AWS CloudFormation all'indirizzo https://console.aws.amazon.com/cloudformation.

  2. Scegliere Create stack (Crea stack), quindi With new resources (standard) (Con nuove risorse (standard)).

  3. In Specificare modello, scegliere Carica un file modello.

  4. Selezionare il modello scaricato.

  5. Seleziona Next (Successivo).

  6. Per Stack name (Nome stack), inserire request-validation-tutorial-console, quindi scegliere Next (Avanti).

  7. Per Configure stack options (Configura opzioni di stack), scegliere Next (Successivo).

  8. Per Capabilities (Funzionalità), conferma che AWS CloudFormation può creare risorse IAM nel tuo account.

  9. Scegli Invia.

AWS CloudFormation effettua il provisioning delle risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Quando lo stato dello stack AWS CloudFormation è CREATE_COMPLETE, si è pronti per passare alla fase successiva.

Selezione dell'API appena creata
  1. Selezionare lo stack request-validation-tutorial-console appena creato.

  2. Scegliere Resources (Risorse).

  3. In ID fisico, scegliere l'API. Questo link consente di venire reindirizzati alla console di Gateway Amazon API.

Prima di modificare i metodi GETPOST, è necessario creare un modello.

Creazione di un modello
  1. È necessario che un modello utilizzi la convalida della richiesta nel corpo di una richiesta in arrivo. Per creare un modello seleziona Modelli nel pannello di navigazione principale.

  2. Scegli Crea modello.

  3. Per Nome, immetti PetStoreModel.

  4. In Tipo di contenuto, inserire application/json. Se non viene trovato alcun tipo di contenuto corrispondente, la convalida della richiesta non viene eseguita. Per utilizzare lo stesso modello indipendentemente dal tipo di contenuti, inserisci $default.

  5. Per Descrizione immetti My PetStore Model come descrizione del modello.

  6. Per Schema modello incolla il seguente modello nell'editor di codice e scegli Crea.

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

Per ulteriori informazioni sul modello, consulta Modelli di dati per REST API.

Per configurare la convalida della richiesta per un metodo GET
  1. Nel pannello di navigazione principale scegli Risorse, quindi seleziona il metodo GET.

  2. Nella scheda Richiesta metodo, in Impostazioni richiesta metodo, scegli Modifica.

  3. Per Validatore richiesta seleziona Convalida parametri di stringa query e intestazioni.

  4. In Parametri della stringa di query URL ed effettua le seguenti operazioni:

    1. Scegliere Add query string (Aggiungi stringa di query).

    2. Per Nome, immetti petType.

    3. Attiva Campo obbligatorio.

    4. Mantieni disattivata l'opzione Caching.

  5. Seleziona Salva.

  6. Nella scheda Richiesta di integrazione scegli Modifica in Impostazioni della richiesta di integrazione.

  7. In Parametri della stringa di query URL ed effettua le seguenti operazioni:

    1. Scegliere Add query string (Aggiungi stringa di query).

    2. Per Nome, immetti petType.

    3. In Mappato da, inserire method.request.querystring.petType. Questa operazione associa petType al tipo di animale domestico.

      Per ulteriori informazioni sulla mappatura dei dati, consultare il tutorial relativo alla mappatura dei dati.

    4. Mantieni disattivata l'opzione Caching.

  8. Seleziona Salva.

Per eseguire il test della convalida della richiesta per il metodo GET
  1. Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.

  2. In Stringhe di query immetti petType=dog e scegli Test.

  3. Il test del metodo restituirà 200 OK e un elenco di cani.

    Per informazioni su come trasformare questi dati di output, consultare il tutorial sulla mappatura dei dati.

  4. Rimuovere petType=dog e scegliere Test.

  5. Il test del metodo restituirà un errore 400 con il seguente messaggio di errore:

    { "message": "Missing required request parameters: [petType]" }
Per configurare la convalida della richiesta per il metodo POST
  1. Nel pannello di navigazione principale scegli Risorse, quindi seleziona il metodo POST.

  2. Nella scheda Richiesta metodo, in Impostazioni richiesta metodo, scegli Modifica.

  3. Per Validatore richiesta seleziona Convalida corpo.

  4. In Corpo della richiesta scegli Aggiungi modello.

  5. Per Tipo di contenuto inserisci application/json. Se non viene trovato alcun tipo di contenuto corrispondente, la convalida della richiesta non viene eseguita. Per utilizzare lo stesso modello indipendentemente dal tipo di contenuti, inserisci $default.

    Per Modello seleziona PetStoreModel.

  6. Seleziona Salva.

Per eseguire il test della convalida della richiesta per un metodo POST
  1. Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.

  2. In Corpo della richiesta incolla quanto segue nell'editor di codice:

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

    Scegli Test (Esegui test).

  3. Il test del metodo restituirà 200 OK e un messaggio di operazione riuscita.

  4. In Corpo della richiesta incolla quanto segue nell'editor di codice:

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

    Scegli Test (Esegui test).

  5. Il test del metodo restituirà un errore 400 con il seguente messaggio di errore:

    { "message": "Invalid request body" }

    Nella parte inferiore dei log del test viene restituito il motivo del corpo della richiesta non valido. In questo caso, il prezzo dell'animale era maggiore del valore massimo specificato nel modello.

Per eliminare uno stack AWS CloudFormation
  1. Apri la console di AWS CloudFormation all'indirizzo https://console.aws.amazon.com/cloudformation.

  2. Seleziona lo stack AWS CloudFormation.

  3. Scegli Elimina e conferma la tua scelta.

Passaggi successivi

Configurazione della convalida di base delle richieste tramite la AWS CLI

È possibile creare un validatore per configurare la convalida della richiesta utilizzando la AWS CLI. Per seguire questo tutorial, utilizzare un modello AWS CloudFormation per creare un'API Gateway Amazon API incompleta.

Nota

Questo non è lo stesso modello AWS CloudFormation del tutorial della console.

Utilizzando una risorsa /validator precedentemente esposta, verranno creati i metodi GETPOST. Entrambi i metodi saranno integrati con l'endpoint HTTP http://petstore-demo-endpoint.execute-api.com/petstore/pets. Verranno configurate le due convalide delle richieste seguenti:

  • Nel metodo GET, verrà creato un validatore params-only per convalidare i parametri della stringa di query URL.

  • Nel metodo POST, verrà creato un validatore body-only per convalidare il corpo della richiesta.

Ciò consentirà solo a determinate chiamate API di eseguire il transito all'API.

Creazione di uno stack AWS CloudFormation

Scarica e decomprimi il modello di creazione dell'applicazione app per AWS CloudFormation.

Per completare il tutorial seguente, è necessario disporre della AWS Command Line Interface (AWS CLI) versione 2.

Per i comandi lunghi viene utilizzato un carattere di escape (\) per dividere un comando su più righe.

Nota

In Windows, alcuni comandi della CLI Bash utilizzati comunemente (ad esempio, zip) non sono supportati dai terminali integrati del sistema operativo. Per ottenere una versione integrata su Windows di Ubuntu e Bash, installa il sottosistema Windows per Linux. I comandi della CLI di esempio in questa guida utilizzano la formattazione Linux. Se si utilizza la CLI di Windows, i comandi che includono documenti JSON in linea dovranno essere riformattati.

  1. Utilizzare il seguente comando per creare lo stack 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. AWS CloudFormation effettua il provisioning delle risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Utilizzare il seguente comando per visualizzare lo stato del task AWS CloudFormation.

    aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli
  3. Quando lo stato dello stack AWS CloudFormation è StackStatus: "CREATE_COMPLETE", utilizzare il seguente comando per recuperare i valori di output rilevanti per i passaggi futuri.

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

    Di seguito sono riportati i valori di output:

    • ApiId, ovvero l'ID dell'API. Per questo tutorial, l'ID API è abc123.

    • ResourceID, ovvero l'ID della risorsa del validatore in cui sono esposti i metodi GETPOST. Per questo tutorial, l'ID risorsa è efg456.

Creazione dei validatori della richiesta e importazione di un modello
  1. Per utilizzare la convalida della richiesta con la AWS CLI, è necessario un validatore. Usare il seguente comando per creare un validatore che convalidi solo i parametri della richiesta.

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

    Annotare l'ID del validatore params-only.

  2. Usare il seguente comando per creare un validatore che convalidi solo il corpo della richiesta.

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

    Annotare l'ID del validatore body-only.

  3. È necessario che un modello utilizzi la convalida della richiesta nel corpo di una richiesta in arrivo. Utilizzare il comando seguente per importare un modello.

    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 non viene trovato alcun tipo di contenuto corrispondente, la convalida della richiesta non viene eseguita. Per utilizzare lo stesso modello indipendentemente dal tipo di contenuto, specifica $default come chiave.

Creazione dei metodi GETPOST
  1. Utilizzare il seguente comando per aggiungere il metodo HTTP GET per la risorsa /validate. Questo comando crea il metodo GET, aggiunge il validatore params-only e imposta la stringa di query petType come richiesto.

    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"

    Utilizzare il seguente comando per aggiungere il metodo HTTP POST per la risorsa /validate. Questo comando crea il metodo POST, aggiunge il validatore body-only e collega il modello al validatore solo del 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. Utilizzare il comando seguente per configurare la risposta 200 OK del metodo GET /validate.

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

    Utilizzare il comando seguente per configurare la risposta 200 OK del metodo POST /validate.

    aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200
  3. Utilizzare il comando seguente per configurare una variabile Integration con un endpoint HTTP specificato per il metodo 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'

    Utilizzare il comando seguente per configurare una variabile Integration con un endpoint HTTP specificato per il metodo 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. Utilizzare il comando seguente per configurare una risposta di integrazione per il metodo GET /validation.

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

    Utilizzare il comando seguente per configurare una risposta di integrazione per il metodo POST /validation.

    aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern ""
Per testare l'API
  1. Per testare il metodo GET, che eseguirà la convalida della richiesta per le stringhe di query, usare il seguente comando:

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

    Il risultato restituirà 200 OK e l'elenco dei cani.

  2. Utilizzare il seguente comando per eseguire il test senza includere la stringa di query petType.

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

    Il risultato restituirà un errore 400.

  3. Per testare il metodo POST, che eseguirà la convalida della richiesta per il corpo della richiesta, usare il seguente 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 }'

    Il risultato restituirà 200 OK e un messaggio di operazione riuscita.

  4. Usare il seguente comando per testare l'utilizzo di un corpo non valido.

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

    Il risultato restituirà un errore 400, perché il prezzo del cane supera il prezzo massimo definito dal modello.

Per eliminare uno stack AWS CloudFormation
  • Usare il seguente comando per eliminare le risorse AWS CloudFormation.

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

Configurazione della convalida di base delle richieste utilizzando una definizione OpenAPI

È possibile dichiarare un validatore di richiesta a livello di API specificando un set di oggetti Oggetto x-amazon-apigateway-request-validators.requestValidator nella mappa Oggetto x-amazon-apigateway-request-validators per selezionare la parte della richiesta che verrà convalidata. Nell'esempio di definizione OpenAPI, sono presenti due validatori:

  • Il validatore all, che convalida sia il corpo, mediante il modello di dati RequestBodyModel, sia i parametri.

    In base al modello di dati RequestBodyModel, l'oggetto JSON di input deve contenere le proprietà name, type e price. La proprietà name può essere qualsiasi stringa, type deve essere uno dei campi dell'enumerazione specificati (["dog", "cat", "fish"]) e price deve essere compreso tra 25 e 500. Il parametro id non è obbligatorio.

  • Il validatore param-only, che convalida solo i parametri.

Per attivare un validatore di richieste in tutti i metodi di un'API, specificare una proprietà Proprietà x-amazon-apigateway-request-validator a livello di API della definizione OpenAPI. Nell'esempio di definizione OpenAPI, il validatore all viene utilizzato su tutti i metodi API, salvo diversamente definito. Quando si utilizza un modello per convalidare il corpo, se non viene trovato alcun tipo di contenuto corrispondente, la convalida della richiesta non viene eseguita. Per utilizzare lo stesso modello indipendentemente dal tipo di contenuto, specifica $default come chiave.

Per attivare un validatore di richieste in un singolo metodo, specificare la proprietà x-amazon-apigateway-request-validator a livello di metodo. Nell'esempio di definizione OpenAPI, il validatore param-only sovrascrive il validatore all nel metodo GET.

Per importare l'esempio OpenAPI in Gateway Amazon API, consultare le seguenti istruzioni per eseguire una Importazione di un'API regionale in Gateway API o una Importazione di un'API ottimizzata per l'edge in 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 } } }