Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Metodi per REST APIs in API Gateway In API Gateway un metodo API include una [richiesta del metodo](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) e una [risposta del metodo](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html). È possibile configurare un metodo API per specificare le operazioni che un client deve eseguire per inviare una richiesta di accesso al servizio nel back-end e le risposte che dovrà ricevere. Per l'input puoi scegliere i parametri di richiesta del metodo o un payload applicabile per consentire al client di fornire i dati obbligatori o facoltativi al runtime. Per l'output si specifica il codice di stato della risposta del metodo, le intestazioni e il corpo applicabile come destinazioni a cui mappare i dati delle risposte di back-end prima che vengano restituite al client. Per aiutare lo sviluppatore del client a capire i comportamenti e i formati di input e output dell'API, puoi [documentare l'API](api-gateway-documenting-api.md) e [fornire messaggi di errore appropriati](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) per le [richieste non valide](api-gateway-method-request-validation.md). Una richiesta del metodo API è una richiesta HTTP. Per configurare la richiesta del metodo, si configura un metodo (o verbo) HTTP, il percorso di una [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API, intestazioni e parametri di stringa di query applicabili. Se il metodo HTTP è `POST`, `PUT` o `PATCH`, devi configurare anche un payload. Ad esempio, per recuperare un animale domestico utilizzando l'[API di PetStore esempio](api-gateway-create-api-from-example.md), è necessario definire il metodo API request of`GET /pets/{petId}`, where `{petId}` è un parametro di percorso che può richiedere un numero in fase di esecuzione. ``` GET /pets/1 Host: apigateway.us-east-1.amazonaws.com ... ``` Se il client specifica un percorso non corretto, ad esempio `/pet/1` o `/pets/one` anziché `/pets/1`, viene generata un'eccezione. Una risposta di metodo API è una risposta HTTP con un codice di stato specifico. Per un'integrazione non proxy, è necessario configurare le risposte di metodo per specificare le destinazioni obbligatorie o facoltative delle mappature. Queste trasformano il corpo o le intestazioni delle risposte di integrazione nel corpo o nelle intestazioni delle risposte del metodo associato. La mappatura può essere semplice come la [trasformazione di un'identità](https://en.wikipedia.org/wiki/Identity_transform) che trasferisce le intestazioni o il corpo tramite l'integrazione senza alcuna modifica. Ad esempio, la risposta del metodo `200` seguente mostra l'esempio di una risposta di integrazione riuscita che viene passata senza essere modificata. ``` 200 OK Content-Type: application/json ... { "id": "1", "type": "dog", "price": "$249.99" } ``` Inizialmente puoi definire una risposta di metodo che corrisponde a una risposta specifica dal back-end. Generalmente vengono utilizzate le risposte 2XX, 4XX e 5XX. Tuttavia questo approccio potrebbe essere poco pratico perché non sempre si conoscono in anticipo le risposte che un back-end potrebbe restituire. In pratica, è possibile designare una sola risposta del metodo come predefinita per gestire le risposte non note o non mappate dal back-end. È buona norma designare la risposta 500 come predefinita. In ogni caso, devi configurare almeno una risposta del metodo per le integrazioni non proxy. In caso contrario API Gateway restituisce una risposta di errore 500 al client, anche quando la richiesta al back-end ha esito positivo. Per fare in modo che l'API supporti un SDK tipizzato in modo sicuro, come un SDK Java, è necessario definire il modello di dati per l'input per le richieste del metodo e il modello di dati per l'output della risposta del metodo. ## Prerequisiti Prima di configurare un metodo API, verifica quanto segue: + Il metodo deve essere disponibile in API Gateway. Segui le istruzioni in [Tutorial: creazione di una REST API con un'integrazione non proxy HTTP](api-gateway-create-api-step-by-step.md). + Se desideri che il metodo comunichi con una funzione Lambda, devi avere già creato il ruolo di invocazione e il ruolo di esecuzione Lambda in IAM. Devi aver creato anche la funzione Lambda con cui il metodo comunicherà in AWS Lambda. Per creare ruoli e funzioni, usa le istruzioni disponibili nella sezione [Creazione di una funzione Lambda per l'integrazione non proxy Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda) dell'argomento [Scegli un tutorial di integrazione AWS Lambda](getting-started-with-lambda-integration.md). + Se desideri che il metodo comunichi con un'integrazione HTTP o proxy HTTP, devi avere già creato l'URL dell'endpoint HTTP con cui il metodo comunicherà e disporre del relativo accesso. + Verifica che i certificati per gli endpoint HTTP e proxy HTTP siano supportati da API Gateway. Per dettagli, consulta [Autorità di certificazione supportate da Gateway API per le integrazioni HTTP e proxy HTTP in Gateway API](api-gateway-supported-certificate-authorities-for-http-endpoints.md). **Topics** + [Prerequisiti](#method-setting-prerequisites) + [Configurazione di una richiesta del metodo in API Gateway](api-gateway-method-settings-method-request.md) + [Configurazione di una risposta di metodo in Gateway API](api-gateway-method-settings-method-response.md) + [Configurazione di un metodo mediante la console API Gateway](how-to-set-up-method-using-console.md) # Configurazione di una richiesta del metodo in API Gateway La configurazione di una richiesta di metodo implica l'esecuzione delle seguenti attività, dopo aver creato una [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa: 1. Creazione di una nuova API o scelta di un'entità [Resource (Risorsa)](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) di un'API esistente. 1. Creazione di una risorsa [Method (Metodo)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) dell'API rappresentata da un verbo HTTP specifico per l'entità `Resource` dell'API nuova o esistente. Puoi suddividere ulteriormente questa attività svolgendo le operazioni secondarie seguenti: + Aggiungi un metodo HTTP alla richiesta del metodo + Configura i parametri di richiesta + Definisci un modello per il corpo della richiesta + Attua uno schema di autorizzazione + Abilita la convalida delle richieste Puoi eseguire queste attività utilizzando i metodi seguenti: + [Console API Gateway](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console) + AWS CLI [comandi ([create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) e put-method)](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) + AWS [Funzioni SDK (ad esempio, in Node.js, [CreateResource](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#createResource-property) e putMethod)](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/APIGateway.html#putMethod-property) + API REST API Gateway ([resource:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateResource.html) e [method:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutMethod.html)). **Topics** + [Impostazione delle risorse API](#setup-method-resources) + [Impostazione di un metodo HTTP](#setup-method-add-http-method) + [Configurazione dei parametri di richiesta del metodo](#setup-method-request-parameters) + [Configurazione di un modello di richiesta del metodo](#setup-method-request-model) + [Configurazione dell'autorizzazione della richiesta del metodo](#setup-method-request-authorization) + [Configurazione della convalida della richiesta del metodo](#setup-method-request-validation) ## Impostazione delle risorse API In un'API di API Gateway le risorse indirizzabili vengono esposte come una struttura di entità [Resources (Risorse)](https://docs.aws.amazon.com/apigateway/latest/api/API_GetResources.html) 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, *\$1api-id\$1* rappresenta l'identificatore 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](how-to-custom-domains.md). Per l'[API PetStore di esempio](api-gateway-create-api-from-example.md), la risorsa root (`/`) espone il pet store. 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](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-resources.html) seguente recupera tutte le risorse di un’API: ``` aws apigateway get-resources --rest-api-id apiId ``` Per l'API PetStore di esempio, l'output è 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, per aggiungere cibo per animali domestici in vendita sul PetStore sito Web, utilizza il seguente comando: ``` 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 Man mano che l'attività cresce, il PetStore proprietario può decidere di mettere in vendita cibo, giocattoli e altri articoli relativi agli animali domestici. 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](api-gateway-set-up-simple-proxy.md) 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](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) 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ò anche fare riferimento a qualsiasi altra risorsa (esistente o to-be-added)`/food/{type}/{item}`, ad esempio`/toys/{type}/{item}`, ecc., oppure `/food/{type}/{subtype}/{item}``/toys/{type}/{subtype}/{item}`, ecc. 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 ``` | Richiesta | Percorso selezionato | Spiegazione | | --- | --- | --- | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/dog` | `GET /pets/dog` | La richiesta corrisponde completamente alla risorsa. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/pets/cats` | `GET /pets/{proxy+}` | La variabile di percorso greedy `/pets/{proxy+}` rileva questa richiesta. | | `GET https://api-id.execute-api.region.amazonaws.com/prod/animals` | `GET /{proxy+}` | La variabile di percorso greedy `/{proxy+}` rileva questa richiesta. | 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)](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) 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](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 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](#setup-method-request-authorization). ## 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](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 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](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 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 APIs in API Gateway](how-to-integration-settings.md). ## 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](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) 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](api-gateway-method-request-validation.md), [generare un SDK](how-to-generate-sdk.md) e inizializzare un modello di mappatura per la configurazione dell'integrazione nella console API Gateway. Per informazioni su come creare un [modello](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html), consultare [Informazioni sui modelli di dati](models-mappings-models.md). 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 impostare i modelli di richiesta del metodo, aggiungi coppie chiave-valore del `"media-type":"model-name"` formato alla `requestModels` mappa quando chiami il AWS CLI `put-method` comando. Per utilizzare lo stesso modello indipendentemente dal tipo di contenuto, specifica `$default` come chiave. [Ad esempio, per impostare un modello sul payload JSON della richiesta del `POST /pets` metodo dell'API di PetStore esempio, puoi utilizzare il seguente comando put-method:](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) ``` 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) che descrive un animale domestico. La definizione effettiva dello schema viene espressa come valore di stringa JSON della proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#schema](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html#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](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType) 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\$1IAM**. 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, consulta [Controllo degli accessi a una REST API con le autorizzazioni IAM](permissions.md). 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 altro soggetto Account AWS possono chiamare i metodi dell'API solo se autorizzati ad assumere un ruolo all'interno del proprietario dell'API Account AWS con le autorizzazioni necessarie per richiamare l'azione. `execute-api:Invoke` Per informazioni sulle autorizzazioni tra account, consulta l'argomento relativo all'[uso dei ruoli IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html). Puoi utilizzare AWS CLI un AWS SDK o un client API REST, come [Postman](https://www.postman.com/), che implementa la [firma Signature Version 4 (SigV4)](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html). 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) sul valore della proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#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](apigateway-use-lambda-authorizer.md). 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 [https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizerId) sul valore della proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id](https://docs.aws.amazon.com/apigateway/latest/api/API_Authorizer.html#id) dell'autorizzatore `COGNITO_USER_POOLS` già creato. Per informazioni sulla creazione di un'autorizzazione per il bacino d’utenza di Amazon Cognito, consulta [Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore](apigateway-integrate-with-cognito.md). ## 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](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html): Il [create-request-validator](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-request-validator.html)comando seguente crea un validatore di richieste 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](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) 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`. # Configurazione di una risposta di metodo in Gateway API Una risposta del metodo API incapsula l'output di una richiesta del metodo API che verrà ricevuta dal client. I dati di output includono un codice di stato HTTP, alcune intestazioni ed eventualmente un corpo. Con le integrazioni non proxy, i parametri di risposta specificati e il corpo possono essere mappati dai dati della risposta di integrazione associati oppure possono essere assegnati determinati valori statici in base alle mappature. Queste mappature vengono specificate nella risposta di integrazione. La mappatura può essere una trasformazione identica che passa attraverso l'integrazione senza alcuna modifica. Con un'integrazione, API Gateway passa automaticamente la risposta di back-end alla risposta del metodo. Non è necessario configurare la risposta del metodo API. Tuttavia, con l'integrazione proxy Lambda, la funzione Lambda deve restituire un risultato in [questo formato di output](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format) per consentire ad API Gateway di mappare la risposta di integrazione a una risposta del metodo. [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) Quando si impostano i codici di stato per un metodo API, è necessario sceglierne uno come predefinito per gestire le risposte di integrazione di un codice di stato non anticipato. È accettabile impostare `500` come valore predefinito perché equivale a trasmettere risposte non mappate come errore del server. Per fini dimostrativi, la console API Gateway imposta come predefinita la risposta `200`. Tuttavia puoi reimpostare il valore su `500`. Per configurare una risposta di metodo, devi aver creato la richiesta. ## Configurazione dello stato del codice di una risposta di metodo Lo stato del codice di una risposta di metodo definisce un tipo di risposta. Ad esempio, le risposte 200, 400 e 500 indicano rispettivamente riposte completate, errore lato client ed errore lato server. Per configurare un codice di stato della risposta del metodo, imposta la proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#statusCode) su un codice di stato HTTP. [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)Il comando seguente crea la risposta del metodo`200`. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 ``` ## Configurazione dei parametri di risposta del metodo I parametri di risposta del metodo definiscono le intestazioni che il client deve ricevere in risposta alla richiesta di metodo associata. Specificano inoltre una destinazione a cui API Gateway mappa un parametro di risposta di integrazione in base alle mappature prescritte nella risposta di integrazione del metodo API. Per configurare i parametri di risposta del metodo, aggiungi alla mappa [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) di `MethodResponse` coppie chiave-valore nel formato `"{parameter-name}":"{boolean}"`. Il [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)comando seguente imposta l'`my-header`intestazione. ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false ``` ## Configurazione dei modelli di risposta del metodo Un modello di risposta del metodo definisce un formato del corpo della risposta. La configurazione di un modello di risposta del metodo è necessaria quando si genera un SDK tipizzato in modo sicuro per l'API. Garantisce che l'output venga trasmesso in una classe appropriata in Java o Objective-C. In altri casi l'impostazione di un modello è facoltativa. Prima di configurare il modello di risposta, è necessario creare il modello in API Gateway. A questo scopo, chiama il comando `[create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html)`. Il comando [create-model](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-model.html) seguente mostra come creare un modello `PetStorePet` per descrivere il corpo della risposta nella richiesta di metodo `GET /pets/{petId}`. ``` aws apigateway create-model \ --rest-api-id vaz7da96z6 \ --content-type application/json \ --name PetStorePet \ --schema '{ \ "$schema": "http://json-schema.org/draft-04/schema#", \ "title": "PetStorePet", \ "type": "object", \ "properties": { \ "id": { "type": "number" }, \ "type": { "type": "string" }, \ "price": { "type": "number" } \ } \ }' ``` Il risultato viene creato come una risorsa [https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) di API Gateway. Per configurare i modelli di risposta del metodo per definire il formato del payload, aggiungi la coppia chiave-valore «application/json»:» PetStorePet "alla mappa della risorsa. [https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseModels) Il [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)comando seguente crea un metodo di risposta che utilizza un modello di risposta per definire il formato del payload: ``` aws apigateway put-method-response \ --rest-api-id vaz7da96z6 \ --resource-id 6sxz2j \ --http-method GET \ --status-code 200 \ --response-parameters method.response.header.my-header=false \ --response-models '{"application/json":"PetStorePet"}' ``` # Configurazione di un metodo mediante la console API Gateway Quando si crea un metodo utilizzando la console REST API, si configura sia la richiesta di integrazione sia la richiesta del metodo. Per impostazione predefinita, Gateway API crea la risposta `200` per il metodo. Le seguenti istruzioni mostrano come modificare le impostazioni di richiesta del metodo e come creare risposte aggiuntive per il metodo. **Topics** + [Modifica di una richiesta del metodo di Gateway API nella console Gateway API](#how-to-method-settings-callers-console) + [Configurazione di una risposta del metodo di API Gateway tramite console API Gateway](#how-to-method-response-settings-console) ## Modifica di una richiesta del metodo di Gateway API nella console Gateway API Queste istruzioni presuppongono che la richiesta del metodo sia già stata creata. Per ulteriori informazioni su come creare un metodo, consulta [Configurazione di una richiesta di integrazione API tramite la console API Gateway](how-to-method-settings-console.md). 1. Seleziona il metodo nel riquadro **Risorse**, quindi scegli la scheda **Richiesta metodo**. 1. Nella sezione **Impostazioni della richiesta del metodo** scegli **Modifica**. 1. Per **Autorizzazione** seleziona un sistema di autorizzazione disponibile. 1. Per abilitare l'accesso aperto al metodo per qualsiasi utente, scegli **Nessuno**. Questa fase può essere ignorata se l'impostazione predefinita non è stata modificata. 1. Per utilizzare le autorizzazioni IAM per controllare l'accesso del client al metodo, scegli `AWS_IAM`. In questo modo il metodo potrà essere chiamato solo dagli utenti dei ruoli IAM a cui è collegata la policy IAM corretta. Per creare il ruolo IAM, specifica una policy di accesso con un formato simile al seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/" ] } ] } ``` ------ In questa policy di accesso, `arn:aws:execute-api:us-east-1:111111111111:aaabbb/*/GET/` è l’ARN del metodo. Per trovare l'ARN del metodo, seleziona il metodo nella pagina **Risorse**. Per ulteriori informazioni sull'impostazione delle autorizzazioni IAM, consulta [Controllo degli accessi a una REST API con le autorizzazioni IAM](permissions.md). Per creare il ruolo IAM è possibile adattare le istruzioni disponibili nel tutorial [Creazione di una funzione Lambda per l'integrazione non proxy Lambda](getting-started-lambda-non-proxy-integration.md#getting-started-new-lambda). 1. Per utilizzare un sistema di autorizzazione Lambda, seleziona un token o un sistema di autorizzazione di richiesta. Affinché questa scelta sia visualizzata nel menu a discesa, è necessario creare un sistema di autorizzazione Lambda. Per informazioni su come creare un'autorizzazione Lambda, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). 1. Per utilizzare un pool di utenti di Amazon Cognito, sceglierne uno disponibile in **Cognito user pool authorizers (Autorizzazioni pool di utenti Cognito)**. Affinché questa scelta sia visualizzata nel menu a discesa, è necessario creare un pool di utenti in Amazon Cognito e un'autorizzazione del pool di utenti di Amazon Cognito in API Gateway. Per informazioni su come creare un'autorizzazione del pool di utenti di Amazon Cognito, consulta [Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore](apigateway-integrate-with-cognito.md). 1. Per specificare la convalida della richiesta, seleziona un valore dal menu a discesa **Validatore richiesta**. Per disattivare la convalida della richiesta, seleziona **Nessuno**. Per ulteriori informazioni su ciascuna opzione, consulta [Richiedi la convalida per REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Seleziona **Chiave API necessaria** per richiedere una chiave API. Quando sono abilitate, le chiavi API vengono utilizzate nei [piani di utilizzo](api-gateway-api-usage-plans.md) per limitare il traffico client. 1. (Facoltativo) Per assegnare un nome di operazione in un SDK Java di questa API generata da Gateway API, immetti un nome in **Nome operazione**. Ad esempio, per la richiesta del metodo `GET /pets/{petId}`, il nome di operazione dell'SDK Java corrispondente è `GetPetsPetId` per impostazione predefinita. Questo nome viene costruito dal verbo HTTP del metodo (`GET`) e dai nomi delle variabili di percorso della risorsa (`Pets` e `PetId`). Se imposti il nome dell'operazione come `getPetById`, il nome di operazione dell'SDK diventa `GetPetById`. 1. Per aggiungere un parametro stringa di query al metodo, procedi come indicato di seguito: 1. Scegli **Parametri della stringa di query URL**, quindi seleziona **Aggiungi stringa di query**. 1. In **Nome** digita il nome del parametro della stringa di query. 1. Se il parametro della stringa di query appena creato viene usato per la convalida della richiesta, scegli l'opzione **Obbligatorio**. Per ulteriori informazioni sulla convalida della richiesta, consulta [Richiedi la convalida per REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Se il parametro della stringa di query appena creato viene usato come parte di una chiave di caching, seleziona l'opzione **Caching**. Per ulteriori informazioni sul caching, consulta [Uso dei parametri di metodo o di integrazione come chiavi di cache per indicizzare le risposte memorizzate nella cache](api-gateway-caching.md#enable-api-gateway-cache-keys). Per rimuovere il parametro della stringa di query, scegli **Rimuovi**. 1. Per aggiungere un parametro di intestazione al metodo, procedi come indicato di seguito: 1. Scegli **Intestazioni di richiesta HTTP**, quindi seleziona **Aggiungi intestazione**. 1. Per **Nome** immetti il nome dell'intestazione. 1. Se l'intestazione appena creata viene usata per la convalida della richiesta, scegli l'opzione **Obbligatorio**. Per ulteriori informazioni sulla convalida della richiesta, consulta [Richiedi la convalida per REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Se l'intestazione appena creata viene usata come parte di una chiave di caching, scegli l'opzione **Caching**. Per ulteriori informazioni sul caching, consulta [Uso dei parametri di metodo o di integrazione come chiavi di cache per indicizzare le risposte memorizzate nella cache](api-gateway-caching.md#enable-api-gateway-cache-keys). Per rimuovere l'intestazione, scegli **Rimuovi**. 1. Per dichiarare il formato del payload di una richiesta di metodo con il verbo HTTP `POST`, `PUT` o `PATCH`, espandi **Corpo della richiesta** e procedi come segue: 1. Scegliere **Add model (Aggiungi modello)**. 1. Per **Content-Type** immetti un tipo MIME (ad esempio `application/json`). 1. Per **Modello** seleziona un modello dal menu a discesa. I modelli attualmente disponibili per l'API includono i modelli `Empty` ed `Error` predefiniti e tutti i modelli creati e aggiunti alla raccolta [Models (Modelli)](https://docs.aws.amazon.com/apigateway/latest/api/API_Model.html) dell'API. Per ulteriori informazioni sulla creazione di un modello, consulta [Modelli di dati per REST APIs](models-mappings-models.md). **Nota** Il modello è utile per informare il client del formato dati previsto di un payload, nonché per generare un modello di mappatura. È importante generare un SDK tipizzato in modo sicuro dell'API in linguaggi come Java, C\$1, Objective-C e Swift. È obbligatorio solo se la convalida di richiesta è abilitata per il payload. 1. Scegli **Save** (Salva). ## Configurazione di una risposta del metodo di API Gateway tramite console API Gateway Un metodo API può avere una o più risposte. Ogni risposta è indicizzata dal rispettivo codice di stato HTTP. Per impostazione predefinita, la console API Gateway aggiunge la risposta `200` alle risposte di metodo. Puoi modificarla in modo che il metodo restituisca `201`. Puoi aggiungere altre risposte, ad esempio `409` per negare l'accesso e `500` per le variabili di fase non inizializzate utilizzate. Per utilizzare la console API Gateway per modificare, eliminare o aggiungere una risposta a un metodo API, segui queste istruzioni. 1. Seleziona il metodo nel riquadro **Risorse**, quindi scegli la scheda **Risposta metodo**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. 1. Nella sezione **Impostazioni risposta metodo** scegli **Crea risposta**. 1. Per **Codice di stato HTTP** inserisci un codice di stato HTTP come `200`, `400` o `500`. Se per una risposta restituita dal back-end non è definita una risposta del metodo corrispondente, API Gateway non è in grado di restituire la risposta al client. Restituisce invece una risposta di errore `500 Internal server error`. 1. Seleziona **Add header (Aggiungi intestazione)**. 1. Per **Nome intestazione** immetti un nome. Per restituire un'intestazione dal back-end al client, aggiungi l'intestazione nella risposta del metodo. 1. Scegli **Aggiungi modello** per definire un formato del corpo della risposta del metodo. Immetti il tipo di supporto del payload della risposta per **Tipo di contenuto** e seleziona un modello dal menu a discesa **Modelli**. 1. Scegli **Save** (Salva). Per modificare una risposta esistente, passa alla risposta del metodo e scegli **Modifica**. Per modificare il **codice di stato HTTP**, scegli **Elimina** e crea una nuova risposta del metodo. Per ogni risposta restituita dal back-end, deve essere configurata una risposta compatibile come risposta del metodo. Tuttavia le intestazioni delle risposte del metodo di configurazione e il modello di payload sono facoltativi, a meno che non si mappi il risultato dal back-end alla risposta del metodo prima della restituzione al client. Inoltre un modello di payload della risposta è importante quando si genera un SDK tipizzato in modo sicuro per l'API.