Configurazione di una richiesta del metodo in API Gateway

Per configurare una richiesta del metodo, esegui le attività indicate di seguito dopo aver creato una risorsa RestApi:

Puoi eseguire queste attività utilizzando i metodi seguenti:

Impostazione delle risorse API

In un'API di API Gateway le risorse indirizzabili vengono esposte come una struttura di entità Resources (Risorse) dell'API, con la risorsa root (/) nella parte più alta della gerarchia. La risorsa radice è relativa rispetto all'URL di base dell'API, costituito dall'endpoint dell'API e da un nome di fase. Nella console API Gateway questo URI di base, visualizzato nell'editor delle fasi dell'API dopo che l'API è stata distribuita, è Invoke URI (URL chiamata).

L'endpoint dell'API può essere un nome host predefinito o un nome di dominio personalizzato. Il formato del nome host predefinito è il seguente:

{api-id}.execute-api.{region}.amazonaws.com

In questo formato {api-id} rappresenta l'identificatore dell'API generato da API Gateway. La variabile {region} rappresenta la regione AWS (ad esempio, us-east-1) scelta durante la creazione dell'API. Un nome di dominio personalizzato è un nome intuitivo in un dominio Internet valido. Ad esempio se hai registrato un dominio Internet di example.com, qualsiasi *.example.com è un nome di dominio personalizzato valido. Per ulteriori informazioni, consulta l'argomento relativo alla creazione di un nome di dominio personalizzato.

Per l'API di esempio PetStore, la risorsa radice (/) espone il negozio di animali domestici. La risorsa /pets rappresenta l'insieme di animali domestici disponibili nel negozio. /pets/{petId} espone un singolo animale domestico di un identificatore specificato (petId). Il parametro di percorso di {petId} fa parte dei parametri di richiesta.

Per configurare una risorsa API, scegli una risorsa esistente come padre e crea la rispettiva risorsa figlio. Inizia con la risorsa radice come padre, aggiungi una risorsa alla risorsa padre, aggiungi un'alta risorsa a questa risorsa figlio come nuovo padre e così via fino all'identificatore del padre. Quindi aggiungi la risorsa con nome alla risorsa padre.

Il comando get-resources seguente recupera tutte le risorse di un’API:

aws apigateway get-resources --rest-api-id apiId

Per l’API di esempio PetStore, l’output sarà simile al seguente:

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

Ogni voce elenca gli identificatori della risorsa (id) e, ad eccezione della risorsa radice, la rispettiva risorsa padre più prossima (parentId), nonché il nome della risorsa (pathPart). La risorsa radice ha la particolarità di non avere una risorsa padre. Dopo avere scelto una risorsa come padre, si utilizza il comando seguente per aggiungere una risorsa figlio:

aws apigateway create-resource --rest-api-id apiId \
    --parent-id parentId \
    --path-part resourceName

Ad esempio, il comando seguente aggiunge la vendita di cibo per animali domestici al sito Web PetStore:

aws apigateway create-resource --rest-api-id a1b2c3 \
    --parent-id svzr2028x8 \
    --path-part food

L'output sarà simile al seguente:

{
    "path": "/food", 
    "pathPart": "food", 
    "id": "xdsvhp", 
    "parentId": "svzr2028x8"
}

Uso di una risorsa proxy per semplificare l'impostazione dell'API

Con il crescere dell'azienda, il proprietario di PetStore potrebbe decidere di iniziare a vendere anche cibo, giocattoli e altri articoli per animali. A questo scopo, puoi aggiungere /food, /toys e altre risorse sotto la risorsa radice. Puoi anche aggiungere altre risorse sotto ogni categoria di vendita, ad esempio /food/{type}/{item}, /toys/{type}/{item} e così via. Questa operazione può risultare tediosa. Se decidi di aggiungere un livello intermedio {subtype} ai percorsi delle risorse per modificare la gerarchia delle risorse in /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item} e così via, la configurazione dell'API esistente verrà alterata. Per evitare che ciò accada, puoi usare una risorsa proxy di API Gateway per esporre un set di risorse API tutte insieme.

API Gateway definisce una risorsa proxy come segnaposto per consentire di specificare una risorsa quando viene inviata una richiesta. È possibile esprimere una risorsa proxy mediante uno speciale parametro di percorso {proxy+}, spesso definito parametro di percorso greedy. Il segno + indica le risorse figlio aggiunte. Il segnaposto /parent/{proxy+} indica qualsiasi risorsa che corrisponda al modello di percorso di /parent/*. È possibile utilizzare qualsiasi stringa per il nome del parametro di percorso greedy.

Il comando create-resource seguente crea una risorsa proxy sotto la root (/{proxy+}):

aws apigateway create-resource --rest-api-id apiId \
    --parent-id rootResourceId \
    --path-part {proxy+}

L'output sarà simile al seguente:

{
    "path": "/{proxy+}", 
    "pathPart": "{proxy+}", 
    "id": "234jdr", 
    "parentId": "svzr2028x8"
}

Per l'esempio API PetStore, puoi usare /{proxy+} per rappresentare sia /pets, sia /pets/{petId}. Questa risorsa proxy può fare riferimento anche ad altre risorse (esistenti o da aggiungere), come /food/{type}/{item}, /toys/{type}/{item} e così via oppure /food/{type}/{subtype}/{item}, /toys/{type}/{subtype}/{item} e così via. Lo sviluppatore del back-end stabilisce la gerarchia delle risorse, mentre allo sviluppatore del client spetta il compito di comprenderla. API Gateway si limita a passare al back-end tutto ciò che il client ha inviato.

Un'API può avere più di una risorsa proxy. Ad esempio, le seguenti risorse proxy sono consentite all'interno di un'API, presupponendo che /parent/{proxy+} non sia lo stesso elemento padre di /parent/{child}/{proxy+}.

/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}

Quando una risorsa proxy presenta elementi di pari livello non proxy, le risorse di tali elementi vengono escluse dalla rappresentazione della risorsa proxy. Per gli esempi precedenti, /{proxy+} si riferisce a qualsiasi risorsa al di sotto della risorsa radice, ad eccezione delle risorse /parent[/*]. In altri termini, una richiesta di metodo a una risorsa specifica ha la precedenza rispetto a una richiesta di metodo a una risorsa generica allo stesso livello della gerarchia di risorse.

La tabella seguente mostra come Gateway API instrada le richieste alle seguenti risorse per la fase prod di un’API.

ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog

Una risorsa proxy non può avere risorse figlio. Qualsiasi risorsa API dopo {proxy+} è ridondante e ambigua. Di seguito sono riportate risorse poxy non consentite in un'API.

/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}

Impostazione di un metodo HTTP

Una richiesta del metodo API viene incapsulata dalla risorsa Method (Metodo) di API Gateway. Per configurare la richiesta del metodo, è necessario prima creare un'istanza della risorsa Method impostando almeno un metodo HTTP e un tipo di autorizzazione per il metodo.

Strettamente associato alla risorsa proxy, API Gateway supporta un metodo HTTP di ANY. Questo metodo ANY rappresenta qualsiasi metodo HTTP da fornire al runtime. Consente di utilizzare la configurazione di un solo metodo API per tutti i metodi HTTP supportati di DELETE, GET, HEAD, OPTIONS, PATCH, POST e PUT.

Puoi configurare il metodo ANY anche per una risorsa non proxy. Combinando il metodo ANY con una risorsa proxy, ottieni un'unica configurazione di un metodo API per tutti i metodi HTTP supportati con tutte le risorse di un'API. Inoltre il back-end può evolvere senza alterare la configurazione API esistente.

Prima di configurare un metodo API, valuta chi può chiamare il metodo. Imposta il tipo di autorizzazione in base al tuo piano. Per l'accesso aperto, impostalo su NONE. Per usare le autorizzazioni IAM, imposta il tipo di autorizzazione su AWS_IAM. Per usare una funzione di autorizzazione Lambda, imposta questa proprietà su CUSTOM. Per utilizzare un pool di utenti di Amazon Cognito, imposta il tipo di autorizzazione su COGNITO_USER_POOLS.

Il comando put-method seguente crea una richiesta di metodo per il verbo ANY utilizzando le autorizzazioni IAM per controllare l’accesso.

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method ANY \
    --authorization-type AWS_IAM

Per creare una richiesta del metodo API con un tipo di autorizzazione diverso, consulta Configurazione dell'autorizzazione della richiesta del metodo.

Configurazione dei parametri di richiesta del metodo

I parametri di richiesta del metodo consentono a un client di fornire i dati di input o il contesto di esecuzione necessari per completare la richiesta del metodo. Un parametro di metodo può essere un parametro di percorso, un'intestazione o un parametro stringa di query. Nell'ambito della configurazione della richiesta del metodo, è necessario dichiarare i parametri di richiesta obbligatori per renderli disponibili per il client. Per l'integrazione non proxy, puoi convertire questi parametri di richiesta in un formato compatibile con i requisiti di back-end.

Ad esempio, per la richiesta del metodo GET /pets/{petId}, la variabile di percorso {petId} è un parametro di richiesta obbligatorio. Puoi dichiarare questo parametro di percorso quando chiami il comando put-method di AWS CLI, Il comando put-method seguente crea un metodo con un parametro di percorso obbligatorio:

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id rjkmth \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.path.petId=true

Se un parametro non è obbligatorio, puoi impostarlo su false in request-parameters. Ad esempio, se il metodo GET /pets usa un parametro della stringa di query type e un parametro dell’intestazione age facoltativi, è possibile dichiararli utilizzando il comando put-method seguente:

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.querystring.type=false,method.request.header.age=false

Per impostare il valore request-parameters, anziché questo formato abbreviato, puoi usare una stringa JSON:

'{"method.request.querystring.type":false,"method.request.header.age":false}'

Con questa configurazione, il client può eseguire query sugli animali domestici in base al tipo:

GET /pets?type=dog

Il client può eseguire la query sui cani cuccioli come segue:

GET /pets?type=dog
age:puppy

Per informazioni su come mappare i parametri di richiesta dei metodi ai parametri di richiesta di integrazione, consulta Integrazioni per REST API in Gateway API.

Configurazione di un modello di richiesta del metodo

Per un metodo API che accetta dati di input in un payload, puoi usare un modello. Un modello viene espresso in una bozza 4 dello schema JSON e descrive la struttura dati del corpo della richiesta. Utilizzando un modello, un client può stabilire come costruire un payload di richiesta del metodo come input. Cosa ancora più importante è che API Gateway usa il modello per convalidare una richiesta, generare un SDK e inizializzare un modello di mappatura per la configurazione dell'integrazione nella console API Gateway. Per informazioni su come creare un modello, consultare Informazioni sui modelli di dati.

A seconda del tipo di contenuto, un payload del metodo può avere formati diversi. Un modello viene indicizzato in base al tipo di supporto del payload applicato. API Gateway utilizza l'intestazione di richiesta Content-Type per determinare il tipo di contenuto. Per configurare modelli di richiesta del metodo, è necessario aggiungere coppie chiave-valore nel formato "media-type":"model-name" alla mappa requestModels quando si chiama il comando di AWS CLI put-method.

Per utilizzare lo stesso modello indipendentemente dal tipo di contenuto, specifica $default come chiave.

Ad esempio, per impostare un modello per il payload JSON della richiesta di metodo POST /pets dell’API di esempio PetStore, è possibile chiamare il comando put-method seguente:

aws apigateway put-method \
    --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method POST \
    --authorization-type "NONE" \
    --request-models '{"application/json":"petModel"}'

In questo esempio petModel è il valore della proprietà name di una risorsa Model che descrive un animale domestico. La definizione effettiva dello schema viene espressa come valore di stringa JSON della proprietà schema della risorsa Model.

In un SDK Java o in un altro SDK tipizzato in modo sicuro dell'API i dati di input vengono trasmessi come classe petModel derivata dalla definizione dello schema. Con il modello della richiesta i dati di input nell'SDK generato vengono trasmessi nella classe Empty, che è derivata dal modello Empty predefinito. In questo caso il client non può creare istanze della classe di dati corretta per fornire l'input richiesto.

Configurazione dell'autorizzazione della richiesta del metodo

Per controllare chi può chiamare il metodo API, puoi configurare il tipo di autorizzazione per il metodo. Puoi utilizzare questo tipo per implementare una delle autorizzazioni supportate, inclusi i ruoli e le policy IAM (AWS_IAM), un pool di utenti di Amazon Cognito (COGNITO_USER_POOLS) o un'autorizzazione Lambda (CUSTOM).

Per utilizzare le autorizzazioni IAM per consentire l'accesso al metodo API, imposta la proprietà di input authorization-type su AWS_IAM. Se si imposta questa opzione, API Gateway verifica la firma del chiamante sulla richiesta in base alle credenziali del chiamante. Se l'utente verificato dispone dell'autorizzazione per chiamare il metodo, la richiesta viene accettata. In caso contrario, la richiesta viene rifiutata e il chiamante riceve una risposta di errore. La chiamata al metodo ha esito positivo solo se il chiamante dispone del permesso di richiamare il metodo API. La seguente policy IAM concede al chiamante l'autorizzazione a chiamare qualsiasi metodo API creato all'interno dello stesso Account AWS:

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

Per ulteriori informazioni, consultare Controllo degli accessi a una REST API con le autorizzazioni IAM.

Attualmente, è possibile concedere questa policy solo agli utenti, ai gruppi e ai ruoli all'interno dell'Account AWS del proprietario dell'API. Gli utenti di un Account AWS diverso possono richiamare i metodi API solo se è loro consentito assumere un ruolo all'interno dell'Account AWS del proprietario dell'API con le autorizzazioni necessarie per richiamare l'operazione execute-api:Invoke. Per informazioni sulle autorizzazioni tra account, consulta l'argomento relativo all'uso dei ruoli IAM.

È possibile utilizzare AWS CLI, un AWS SDK o un client della REST API come Postman, che implementa il processo di firma Signature Version 4 (SigV4).

Per utilizzare un autorizzatore Lambda allo scopo di autorizzare l'accesso al metodo API, imposta la proprietà di input authorization-type su CUSTOM e la proprietà di input authorizer-id sul valore della proprietà id di un autorizzatore Lambda esistente. L'autorizzazione Lambda di riferimento può essere di tipo TOKEN o REQUEST. Per informazioni su come creare un'autorizzazione Lambda, consulta Uso di autorizzazioni Lambda di API Gateway.

Per usare un bacino d'utenza di Amazon Cognito per autorizzare l'accesso al metodo API, imposta la proprietà di input authorization-type su COGNITO_USER_POOLS e la proprietà di input authorizer-id sul valore della proprietà id dell'autorizzatore COGNITO_USER_POOLS già creato. Per informazioni sulla creazione di un'autorizzazione per il bacino d’utenza di Amazon Cognito, consulta Controllo degli accessi alle REST API utilizzando pool di utenti di Amazon Cognito come sistema di autorizzazione.

Configurazione della convalida della richiesta del metodo

Puoi abilitare la convalida della richiesta durante la configurazione di una richiesta del metodo API. È necessario creare prima un validatore richiesta: Il comando create-request-validator seguente crea un validatore richiesta solo per il corpo.

aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters

L'output sarà simile al seguente:

{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}

Con questo validatore richiesta è possibile utilizzare la convalida della richiesta nell’ambito della configurazione della richiesta di metodo: Il comando put-method seguente crea una richiesta di metodo che richiede che il corpo della richiesta in entrata corrisponda a PetModel e include due parametri di richiesta non obbligatori:

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl \
    --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

Per includere un parametro di richiesta nella convalida della richiesta, è necessario impostare validateRequestParameters su true per il validatore richiesta e impostare il parametro di richiesta specifico su true nel comando put-method.