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.
Argomenti
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 GET
e POST
. 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
Apri la console di AWS CloudFormation all'indirizzo https://console.aws.amazon.com/cloudformation
. -
Scegliere Create stack (Crea stack), quindi With new resources (standard) (Con nuove risorse (standard)).
-
In Specificare modello, scegliere Carica un file modello.
-
Selezionare il modello scaricato.
-
Seleziona Next (Successivo).
-
Per Stack name (Nome stack), inserire
request-validation-tutorial-console
, quindi scegliere Next (Avanti). -
Per Configure stack options (Configura opzioni di stack), scegliere Next (Successivo).
-
Per Capabilities (Funzionalità), conferma che AWS CloudFormation può creare risorse IAM nel tuo account.
-
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
Selezionare lo stack
request-validation-tutorial-console
appena creato.Scegliere Resources (Risorse).
In ID fisico, scegliere l'API. Questo link consente di venire reindirizzati alla console di Gateway Amazon API.
Prima di modificare i metodi GET
e POST
, è necessario creare un modello.
Creazione di un modello
-
È 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.
-
Scegli Crea modello.
-
Per Nome, immetti
PetStoreModel
. -
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
. -
Per Descrizione immetti
My PetStore Model
come descrizione del modello. -
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
-
Nel pannello di navigazione principale scegli Risorse, quindi seleziona il metodo GET.
-
Nella scheda Richiesta metodo, in Impostazioni richiesta metodo, scegli Modifica.
-
Per Validatore richiesta seleziona Convalida parametri di stringa query e intestazioni.
In Parametri della stringa di query URL ed effettua le seguenti operazioni:
Scegliere Add query string (Aggiungi stringa di query).
Per Nome, immetti
petType
.Attiva Campo obbligatorio.
Mantieni disattivata l'opzione Caching.
-
Seleziona Salva.
-
Nella scheda Richiesta di integrazione scegli Modifica in Impostazioni della richiesta di integrazione.
In Parametri della stringa di query URL ed effettua le seguenti operazioni:
Scegliere Add query string (Aggiungi stringa di query).
Per Nome, immetti
petType
.In Mappato da, inserire
method.request.querystring.petType
. Questa operazione associapetType
al tipo di animale domestico.Per ulteriori informazioni sulla mappatura dei dati, consultare il tutorial relativo alla mappatura dei dati.
Mantieni disattivata l'opzione Caching.
Seleziona Salva.
Per eseguire il test della convalida della richiesta per il metodo GET
-
Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
-
In Stringhe di query immetti
petType=dog
e scegli Test. -
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.
-
Rimuovere
petType=dog
e scegliere Test. -
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
-
Nel pannello di navigazione principale scegli Risorse, quindi seleziona il metodo POST.
-
Nella scheda Richiesta metodo, in Impostazioni richiesta metodo, scegli Modifica.
-
Per Validatore richiesta seleziona Convalida corpo.
-
In Corpo della richiesta scegli Aggiungi modello.
-
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.
Seleziona Salva.
Per eseguire il test della convalida della richiesta per un metodo POST
-
Seleziona la scheda Test. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda.
-
In Corpo della richiesta incolla quanto segue nell'editor di codice:
{ "id": 2, "name": "Bella", "type": "dog", "price": 400 }
Scegli Test (Esegui test).
-
Il test del metodo restituirà
200 OK
e un messaggio di operazione riuscita. -
In Corpo della richiesta incolla quanto segue nell'editor di codice:
{ "id": 2, "name": "Bella", "type": "dog", "price": 4000 }
Scegli Test (Esegui test).
-
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
Apri la console di AWS CloudFormation all'indirizzo https://console.aws.amazon.com/cloudformation
. -
Seleziona lo stack AWS CloudFormation.
-
Scegli Elimina e conferma la tua scelta.
Passaggi successivi
Per informazioni su come trasformare i dati di output ed eseguire ulteriori mappature dei dati, consultare il tutorial sulla mappatura dei dati.
Eseguire il tutorial Configurazione della convalida di base delle richieste in AWS CLI per eseguire passaggi simili utilizzando la AWS CLI.
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 GET
e POST
. 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 validatoreparams-only
per convalidare i parametri della stringa di query URL. -
Nel metodo
POST
, verrà creato un validatorebody-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
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
-
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
-
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
GET
ePOST
. Per questo tutorial, l'ID risorsa èefg456
.
Creazione dei validatori della richiesta e importazione di un modello
-
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-onlyAnnotare l'ID del validatore
params-only
. -
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-onlyAnnotare l'ID del validatore
body-only
. -
È 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 GET
e POST
-
Utilizzare il seguente comando per aggiungere il metodo HTTP
GET
per la risorsa/validate
. Questo comando crea il metodoGET
, aggiunge il validatoreparams-only
e imposta la stringa di querypetType
come richiesto.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"Utilizzare il seguente comando per aggiungere il metodo HTTP
POST
per la risorsa/validate
. Questo comando crea il metodoPOST
, aggiunge il validatorebody-only
e collega il modello al validatore solo del 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 -
Utilizzare il comando seguente per configurare la risposta
200 OK
del metodoGET /validate
.aws apigateway put-method-response --rest-api-id
abc123
\ --resource-idefg456
\ --http-method GET \ --status-code 200Utilizzare il comando seguente per configurare la risposta
200 OK
del metodoPOST /validate
.aws apigateway put-method-response --rest-api-id
abc123
\ --resource-idefg456
\ --http-method POST \ --status-code 200 -
Utilizzare il comando seguente per configurare una variabile
Integration
con un endpoint HTTP specificato per il metodoGET /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'Utilizzare il comando seguente per configurare una variabile
Integration
con un endpoint HTTP specificato per il metodoPOST /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' -
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-idefg456
\ --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-idefg456
\ --http-method POST \ --status-code 200 \ --selection-pattern ""
Per testare l'API
-
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-idefg456
\ --http-method GET \ --path-with-query-string '/validate?petType=dog'Il risultato restituirà
200 OK
e l'elenco dei cani. -
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-idefg456
\ --http-method GETIl risultato restituirà un errore
400
. -
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-idefg456
\ --http-method POST \ --body '{"id": 1, "name": "bella", "type": "dog", "price" : 400 }'Il risultato restituirà
200 OK
e un messaggio di operazione riuscita. -
Usare il seguente comando per testare l'utilizzo di un corpo non valido.
aws apigateway test-invoke-method --rest-api-id
abc123
\ --resource-idefg456
\ --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 datiRequestBodyModel
, sia i parametri.In base al modello di dati
RequestBodyModel
, l'oggetto JSON di input deve contenere le proprietàname
,type
eprice
. La proprietàname
può essere qualsiasi stringa,type
deve essere uno dei campi dell'enumerazione specificati (["dog", "cat", "fish"]
) eprice
deve essere compreso tra 25 e 500. Il parametroid
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.