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à. # Sviluppa REST APIs in API Gateway In Amazon API Gateway è possibile creare un'API REST come una raccolta di entità programmabili note come [risorse](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) di API Gateway. Ad esempio, si utilizza una [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa per rappresentare un'API che può contenere una raccolta di entità [Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html). Ciascuna entità `Resource` può presentare una o più risorse [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). `Method` è una richiesta in entrata inviata dal client che può contenere un parametro di percorso, un’intestazione o un parametro della stringa di query. Inoltre, a seconda del metodo HTTP, la richiesta può contenere un corpo. Il metodo definisce in che modo il client accede alla `Resource` esposta. Per integrare `Method` con un endpoint di backend, noto anche come endpoint di integrazione, devi creare una risorsa [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). In questo modo la richiesta in arrivo viene inoltrata all'URI dell'endpoint di integrazione specificato. Se necessario, è possibile trasformare i parametri o il corpo della richiesta per soddisfare i requisiti del backend oppure creare un’integrazione proxy, in cui Gateway API invia l’intera richiesta in un formato standardizzato all’URI dell’endpoint di integrazione e quindi invia la risposta direttamente al client. Per le risposte, è possibile creare una [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html)risorsa per rappresentare una risposta ricevuta dal client e creare una [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)risorsa per rappresentare la risposta restituita dal backend. Si utilizza la risposta di integrazione per trasformare i dati della risposta del backend prima di restituirli al client oppure si passa la risposta del backend al client senza modificarla. ## Risorsa di esempio per una REST API Il diagramma seguente mostra come API Gateway implementa questo request/response modello per un proxy HTTP e un'integrazione HTTP non proxy per la risorsa. `GET /pets` Il client invia l’intestazione `x-version:beta` a Gateway API che quindi invia il codice di stato `204` al client. Nell’integrazione non proxy, Gateway API esegue le trasformazioni di dati per soddisfare i requisiti del backend, modificando la richiesta e la risposta di integrazione. In un’integrazione non proxy, è possibile accedere al corpo nella richiesta di metodo ma è necessario trasformarlo nella richiesta di integrazione. Quando l’endpoint di integrazione restituisce una risposta con un corpo, è necessario accedere e trasformarlo nella risposta di integrazione. Non è possibile modificare il corpo nella risposta di metodo. Nell’integrazione proxy, l’endpoint di integrazione modifica la richiesta e la risposta. Gateway API non modifica la richiesta o la risposta di integrazione e invia la richiesta in entrata al backend così com’è. Indipendentemente dal tipo di integrazione, il client ha inviato una richiesta a Gateway API che ha risposto in modo sincrono. ------ #### [ Non-proxy integration ] ![\[Diagramma dell’integrazione non proxy di Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/develop-non-proxy.png) ------ #### [ Proxy integration ] ![\[Diagramma dell’integrazione proxy di Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/develop-proxy.png) ------ I log di esecuzione seguenti mostrano cosa dell’esempio precedente Gateway API registra nei log. Per maggiore chiarezza, alcuni valori e log iniziali sono stati rimossi: ------ #### [ Non-proxy integration ] ``` Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:56:44 UTC 2025 : Method request path: {} Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {} Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations: Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta} Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT} Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null) Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345} Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204 ``` ------ #### [ Proxy integration ] ``` Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678 Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets Wed Feb 12 23:59:42 UTC 2025 : Method request path: {} Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {} Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations: Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta} Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations: Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations: Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204 ``` ------ [Per importare un'API simile e testarla in Console di gestione AWS, vedi l'API di esempio.](api-gateway-create-api-from-example.md) ## Funzionalità aggiuntive per lo sviluppo di REST API Gateway API supporta funzionalità aggiuntive per lo sviluppo della REST API. Ad esempio, per aiutare i clienti a comprendere l’API, è possibile fornire la documentazione relativa all’API. A questo scopo, aggiungi una risorsa [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) per un'entità API supportata. Per controllare il modo in cui i client chiamano un'API, usa le [autorizzazioni IAM](permissions.md), un'[autorizzazione Lambda](apigateway-use-lambda-authorizer.md) o un [pool di utenti di Amazon Cognito](apigateway-integrate-with-cognito.md). Per misurare l'uso dell'API, configura [piani di utilizzo](api-gateway-api-usage-plans.md) per eseguire il throttling delle richieste API. Puoi abilitare queste impostazioni durante la creazione o l'aggiornamento dell'API. Il diagramma seguente mostra le funzionalità disponibili per lo sviluppo di REST API e dove tali funzionalità sono configurate nel modello di richiesta/risposta. ![\[Diagramma delle funzionalità di Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/develop-features.png) Per un'introduzione su come creare un'API, consulta [Tutorial: creazione di una REST API con un'integrazione proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Per ulteriori informazioni sulle funzionalità di Gateway API che potresti utilizzare durante lo sviluppo di una REST API, consulta i seguenti argomenti. Questi argomenti contengono informazioni e procedure concettuali che è possibile eseguire utilizzando la console API Gateway, l'API REST API Gateway AWS CLI, o una delle AWS SDKs. **Topics** + [Risorsa di esempio per una REST API](#rest-api-develop-example) + [Funzionalità aggiuntive per lo sviluppo di REST API](#rest-api-develop-details) + [Tipi di endpoint API per REST APIs in API Gateway](api-gateway-api-endpoint-types.md) + [Politiche di sicurezza per REST APIs in API Gateway](apigateway-security-policies.md) + [Tipi di indirizzo IP per REST API in Gateway API](api-gateway-ip-address-type.md) + [Metodi per REST APIs in API Gateway](how-to-method-settings.md) + [Controlla e gestisci l'accesso a REST APIs in API Gateway](apigateway-control-access-to-api.md) + [Integrazioni per REST APIs in API Gateway](how-to-integration-settings.md) + [Richiedi la convalida per REST APIs in API Gateway](api-gateway-method-request-validation.md) + [Trasformazioni dei dati per REST APIs in API Gateway](rest-api-data-transformations.md) + [Risposte gateway per REST APIs in API Gateway](api-gateway-gatewayResponse-definition.md) + [CORS per REST APIs in API Gateway](how-to-cors.md) + [Tipi di supporti binari per REST APIs in API Gateway](api-gateway-payload-encodings.md) + [Invocazione di REST API in Gateway API](how-to-call-api.md) + [Sviluppa REST APIs utilizzando OpenAPI in API Gateway](api-gateway-import-api.md) # Tipi di endpoint API per REST APIs in API Gateway Per tipo di *[endpoint API](api-gateway-basic-concept.md#apigateway-definition-api-endpoints)* si intende il nome host dell'API. Il tipo di endpoint dell’API può essere *ottimizzato per l’edge*, *regionale* o *privato*, a seconda della provenienza della maggior parte del traffico dell’API. ## Endpoint API ottimizzati per edge Un *[endpoint API ottimizzato per l'edge in genere indirizza le richieste al CloudFront Point of Presence (POP) più vicino, il che può essere utile nei casi in cui i clienti sono distribuiti geograficamente](api-gateway-basic-concept.md#apigateway-definition-edge-optimized-api-endpoint)*. Questo è il tipo di endpoint predefinito per API Gateway APIs REST. Ottimizzato per Edge, usa APIs le maiuscole per i nomi delle [intestazioni HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers) (ad esempio,). `Cookie` CloudFront ordina i cookie HTTP in ordine naturale in base al nome del cookie prima di inoltrare la richiesta all'origine. Per ulteriori informazioni sul modo in cui CloudFront elabora i cookie, consulta [Memorizzazione nella cache dei contenuti](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Cookies.html) basati sui cookie. Qualsiasi nome di dominio utilizzato per un'API con edge ottimizzato si applica in tutte le regioni. ## Endpoint API regionali Un *[endpoint API regionale](api-gateway-basic-concept.md#apigateway-definition-regional-api-endpoint)* è destinato a client inclusi nella stessa Regione. L’API regionale riduce il sovraccarico delle connessioni nei casi in cui un client in esecuzione su un’istanza EC2 chiama un’API nella stessa Regione o un’API è destinata all’utilizzo da parte di un numero limitato di client con domanda elevata. Per un’API regionale, il nome di dominio personalizzato è specifico della Regione in cui viene implementata l’API. Se si distribuisce un’API regionale in più Regioni, questa può avere lo stesso nome di dominio personalizzato in tutte le Regioni. È possibile utilizzare domini personalizzati insieme ad Amazon Route 53 per eseguire attività come l'[instradamento basato su latenza](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html#routing-policy-latency). Per ulteriori informazioni, consulta [Configurazione di un nome di dominio personalizzato regionale in Gateway API](apigateway-regional-api-custom-domain-create.md) e [Configurazione di un nome di dominio personalizzato ottimizzato per l'edge in Gateway API](how-to-edge-optimized-custom-domain-name.md). Gli endpoint di API regionali passano tutti i nomi di intestazione senza alcuna modifica. **Nota** Nei casi in cui i client API siano distribuiti geograficamente, può comunque essere opportuno utilizzare un endpoint API regionale, insieme alla propria CloudFront distribuzione Amazon per garantire che API Gateway non associ l'API a distribuzioni controllate dal servizio. CloudFront Per ulteriori informazioni su questo caso d'uso, vedi [Come posso configurare API Gateway con la mia CloudFront distribuzione?](https://repost.aws/knowledge-center/api-gateway-cloudfront-distribution) . ## Endpoint API privati Un *[endpoint di API privato](api-gateway-basic-concept.md#apigateway-definition-private-api-endpoint)* è un endpoint di API al quale è possibile accedere solo da Amazon Virtual Private Cloud (VPC) utilizzando un endpoint VPC di interfaccia, ovvero un'interfaccia di rete dell'endpoint creato nel VPC. Per ulteriori informazioni, consulta [REST privato APIs in API Gateway](apigateway-private-apis.md). Gli endpoint API privati passano tutti i nomi delle intestazioni senza alcuna modifica. # Modifica di un tipo di endpoint API pubblico o privato in API Gateway La modifica di un tipo di endpoint API richiede l'aggiornamento della configurazione dell'API. Puoi modificare un tipo di API esistente utilizzando la console API Gateway AWS CLI, o un AWS SDK per API Gateway. Il tipo di endpoint non potrà essere modificato fino a quando non viene completata la modifica corrente ma, durante tale periodo, l’API sarà disponibile. Sono supportate le seguenti modifiche ai tipi di endpoint: + Da ottimizzato per l'edge a regionale o privato + Da regionale a ottimizzato per l'edge o privato + Da privato a regionale Non è possibile modificare un'API privata in un'API ottimizzata per i confini. Se si intende modificare un'API pubblica da ottimizzata per l'edge a regionale o viceversa, è importante notare che un'API ottimizzata per l'edge può avere comportamenti diversi rispetto a un'API regionale. Ad esempio, un'API ottimizzata per i confini rimuove l'intestazione `Content-MD5`. Qualsiasi valore MD5 hash passato al backend può essere espresso in un parametro della stringa di richiesta o in una proprietà body. Tuttavia, l'API regionale passa questa intestazione, ma può rimappare il nome di intestazione a un altro nome. La comprensione delle differenze può aiutare a scegliere come aggiornare un'API ottimizzata per l'edge in una regionale o un'API regionale in una ottimizzata per l'edge. **Topics** + [Uso della console API Gateway per modificare un tipo di endpoint API](#migrate-api-using-console) + [Utilizza il per modificare il tipo AWS CLI di endpoint dell'API](#migrate-api-using-aws-cli) ## Uso della console API Gateway per modificare un tipo di endpoint API Per modificare il tipo di endpoint API della tua API, esegui uno dei seguenti insiemi di passaggi: **Conversione di un endpoint pubblico da regionale o ottimizzato per l'edge e viceversa** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegli **Impostazioni API**. 1. Nella sezione **Dettagli API**, scegli **Modifica**. 1. In **Tipo di endpoint API**, seleziona **Ottimizzato per l'edge** o **Regionale**. 1. Scegli **Save changes** (Salva modifiche). 1. Ridistribuisci la tua API in modo che le modifiche diventino effettive. **Per convertire un endpoint privato in un endpoint regionale** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Modifica la politica delle risorse per la tua API per rimuovere qualsiasi menzione VPCs o endpoint VPC in modo che le chiamate API dall'esterno del tuo VPC e dall'interno del tuo VPC abbiano esito positivo. 1. Scegli **Impostazioni API**. 1. Nella sezione **Dettagli API**, scegli **Modifica**. 1. In **Tipo di endpoint**, scegli**Regionale**. 1. Scegli **Save changes** (Salva modifiche). 1. Rimuovi la policy delle risorse dall'API. 1. Ridistribuisci la tua API in modo che le modifiche diventino effettive. Poiché stai migrando il tipo di endpoint da privato a regionale, API Gateway cambia il tipo di indirizzo IP in. IPv4 Per ulteriori informazioni, consulta [Tipi di indirizzo IP per REST API in Gateway API](api-gateway-ip-address-type.md). **Per convertire un endpoint regionale in un endpoint privato** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Crea una policy delle risorse che fornisca l'accesso al VPC o all'endpoint VPC. Per ulteriori informazioni, consulta [Passaggio 3: impostare una policy delle risorse per un'API privata.](apigateway-private-api-create.md#apigateway-private-api-set-up-resource-policy). 1. Scegli **Impostazioni API**. 1. Nella sezione **Dettagli API**, scegli **Modifica**. 1. Per **Tipo di endpoint API** scegli **Privato**. 1. (Facoltativo) Per l'**endpoint VPC IDs**, seleziona l'endpoint VPC IDs che desideri associare alla tua API privata. 1. Scegli **Save changes** (Salva modifiche). 1. Ridistribuisci la tua API in modo che le modifiche diventino effettive. Dal momento che si sta migrando il tipo di endpoint da regionale a privato, Gateway API modifica il tipo di indirizzo IP in dualstack. Per ulteriori informazioni, consulta [Tipi di indirizzo IP per REST API in Gateway API](api-gateway-ip-address-type.md). ## Utilizza il per modificare il tipo AWS CLI di endpoint dell'API Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente aggiorna un'API ottimizzata per l'edge in un'API regionale: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/endpointConfiguration/types/EDGE,value=REGIONAL ``` La risposta di esito positivo ha il codice di stato `200 OK` e un payload simile al seguente: ``` { "createdDate": "2017-10-16T04:09:31Z", "description": "Your first API with Amazon API Gateway. This is a sample API that integrates via HTTP with our demo Pet Store endpoints", "endpointConfiguration": { "types": "REGIONAL" }, "id": "a1b2c3", "name": "PetStore imported as edge-optimized" } ``` Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente aggiorna un'API regionale a un'API ottimizzata per l'edge: ``` aws apigateway update-rest-api \ --rest-api-id a1b2c3 \ --patch-operations op=replace,path=/endpointConfiguration/types/REGIONAL,value=EDGE ``` Poiché [put-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-rest-api.html)serve per aggiornare le definizioni delle API, non è applicabile all'aggiornamento di un tipo di endpoint API. # Politiche di sicurezza per REST APIs in API Gateway Una *policy di sicurezza* è una combinazione predefinita di versione TLS minima e suite di crittografia offerta da Gateway API. Quando i client stabiliscono un handshake TLS sull’API o sul nome di dominio personalizzato, la policy di sicurezza applica la versione di TLS e il pacchetto di crittografia accettato da API Gateway. Le politiche di sicurezza proteggono i nomi di dominio dell'utente APIs e quelli personalizzati da problemi di sicurezza della rete, come la manomissione e l'intercettazione tra un client e un server. API Gateway supporta policy di sicurezza legacy e policy di sicurezza avanzate. `TLS_1_0`e `TLS_1_2` sono politiche di sicurezza obsolete. Utilizza queste politiche di sicurezza per la compatibilità con le versioni precedenti. Qualsiasi politica che inizia con `SecurityPolicy_` è una politica di sicurezza avanzata. Utilizza queste policy per carichi di lavoro regolamentati, governance avanzata o per utilizzare la crittografia post-quantistica. Quando utilizzi una policy di sicurezza avanzata, devi anche impostare la modalità di accesso agli endpoint per una governance aggiuntiva. Per ulteriori informazioni, consulta [Modalità di accesso agli endpoint](#apigateway-security-policies-endpoint-access-mode). ## In che modo API Gateway applica le politiche di sicurezza L'esempio seguente mostra come API Gateway applica le policy di `SecurityPolicy_TLS13_1_3_2025_09` sicurezza utilizzando la policy di sicurezza come esempio. La politica `SecurityPolicy_TLS13_1_3_2025_09` di sicurezza accetta il traffico TLS 1.3 e rifiuta il traffico TLS 1.2 e TLS 1.0. Per il traffico TLS 1.3, la politica di sicurezza accetta le seguenti suite di crittografia: + `TLS_AES_128_GCM_SHA256` + `TLS_AES_256_GCM_SHA384` + `TLS_CHACHA20_POLY1305_SHA256` API Gateway non accetta altre suite di crittografia. Ad esempio, la politica di sicurezza rifiuterebbe qualsiasi traffico TLS 1.3 che utilizza la suite di crittografia. `AES128-SHA` Per ulteriori informazioni sulle versioni e le crittografie TLS supportate, consulta. [Policy di sicurezza supportate](apigateway-security-policies-list.md) Per monitorare il protocollo TLS e i client di crittografia utilizzati per accedere al tuo API Gateway, puoi utilizzare le variabili `$context.tlsVersion` e di `$context.cipherSuite` contesto nei tuoi log di accesso. Per ulteriori informazioni, consulta [Monitoraggio delle REST API in Gateway API](rest-api-monitor.md). ## Modalità di accesso agli endpoint La modalità di accesso agli endpoint è un parametro aggiuntivo che è necessario specificare per qualsiasi REST API o nome di dominio personalizzato che utilizza una politica di sicurezza avanzata che inizia con `SecurityPolicy_`. Questa operazione viene eseguita quando si crea la risorsa o se si modifica la politica di sicurezza da una politica precedente a una politica avanzata. Quando la modalità di accesso agli endpoint è impostata su`STRICT`, qualsiasi richiesta all'API REST o al nome di dominio personalizzato deve superare i seguenti controlli: + La richiesta deve provenire dallo stesso tipo di endpoint API Gateway della risorsa. Potrebbe provenire da un endpoint regionale, ottimizzato per l’edge o privato. + Se utilizzi un endpoint regionale o privato, API Gateway utilizza l'host matching SNI. Se utilizzi un endpoint ottimizzato per l'edge, API Gateway è conforme alla CloudFront protezione del fronting del dominio. [Per ulteriori informazioni, consulta Domain fronting.](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/CNAMEs.html#alternate-domain-names-restrictions) Se una di queste condizioni non viene soddisfatta, API Gateway rifiuta la richiesta. Si consiglia di utilizzare la modalità di accesso agli `STRICT` endpoint quando possibile. Per migrare un'API o un nome di dominio esistente per utilizzare la modalità di accesso agli endpoint rigorosa, aggiorna innanzitutto la policy di sicurezza con una policy di sicurezza avanzata e mantieni impostata la modalità di accesso agli endpoint. `BASIC` Dopo aver convalidato i registri del traffico e degli accessi, imposta la modalità di accesso agli endpoint su. `STRICT` Quando esegui la migrazione della modalità di accesso all'endpoint da `STRICT` a`BASIC`, l'endpoint non sarà disponibile per circa 15 minuti man mano che le modifiche si propagano. Non è necessario impostare la modalità di accesso all'endpoint `STRICT` per determinate architetture applicative, ma impostare invece la modalità di accesso all'endpoint su. `BASIC` La tabella seguente mostra alcune architetture applicative e una raccomandazione per consentire all'API REST o al nome di dominio personalizzato di utilizzare la modalità di accesso agli endpoint. `STRICT` | Architecture | Migrazione consigliata | | --- | --- | | Utilizzo di un endpoint VPC per accedere a un nome di dominio pubblico personalizzato. | Questa architettura utilizza traffico di tipo cross-endpoint. Ti consigliamo di effettuare la migrazione a. [Nomi di dominio personalizzati per uso privato APIs in API Gateway](apigateway-private-custom-domains.md) | | Utilizzo di qualsiasi metodo per richiamare un'API privata che non utilizzi un nome di dominio personalizzato o nomi DNS privati. | Questa architettura crea una mancata corrispondenza tra l'intestazione dell'host e l'SNI utilizzato nell'handshake TLS e non supera le restrizioni di fronting del dominio. CloudFront Ti consigliamo di migrare il tuo VPC per utilizzare un DNS privato. | | Utilizzo dello sharding del dominio per distribuire contenuti su più domini o sottodomini. | Questa architettura crea una discrepanza tra l'intestazione dell'host e l'SNI utilizzato nell'handshake TLS e non supera le restrizioni di fronting del dominio. CloudFront Ti consigliamo di utilizzare `HTTP/2` e migrare da questo anti-pattern. | Di seguito sono riportate alcune considerazioni sull'utilizzo della modalità di accesso agli endpoint: + Se la modalità di accesso all'endpoint di un'API o di un nome di dominio è`STRICT`, non puoi modificare il tipo di endpoint. Per modificare il tipo di endpoint, modifica innanzitutto la modalità di accesso all'endpoint in. `BASIC` + Dopo aver modificato la modalità di accesso agli endpoint da `BASIC` a`STRICT`, API Gateway impiega un ritardo di 15 minuti per applicare la modalità di accesso agli endpoint rigorosa. + Quando si modifica una policy di sicurezza da una policy iniziale `SecurityPolicy_` a una policy legacy, è necessario disattivare la modalità di accesso agli endpoint su. `""` ## Considerazioni Di seguito sono riportate le considerazioni relative alle politiche di sicurezza per REST APIs in API Gateway: + È possibile importare la politica di sicurezza in un file di definizione OpenAPI. Per ulteriori informazioni, consulta [x-amazon-apigateway-endpoint-modalità di accessox-amazon-apigateway-security-politica](openapi-extensions-security-policy.md). + La tua API può essere mappata su un nome di dominio personalizzato con una politica di sicurezza diversa dalla tua API. Quando richiami quel nome di dominio personalizzato, API Gateway utilizza la politica di sicurezza dell'API per negoziare l'handshake TLS. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API. + Se si modifica la politica di sicurezza, il completamento dell'aggiornamento richiede circa 15 minuti. Puoi monitorare `apiStatus` la tua API. Man mano che la tua API si aggiorna, lo `apiStatus` è `UPDATING` e quando sarà completata, lo sarà`AVAILABLE`. Una volta raggiunto lo stato dell'API`UPDATING`, puoi comunque richiamarla. + API Gateway supporta le politiche di sicurezza su tutti APIs. Tuttavia, puoi scegliere solo una politica di sicurezza per REST APIs. API Gateway supporta solo la politica `TLS_1_2` di sicurezza per HTTP o WebSocket APIs. + Non è possibile aggiornare la politica di sicurezza per un'API da `TLS_1_0` a`TLS_1_2`. + Alcune politiche di sicurezza supportano sia le suite di crittografia ECDSA che RSA. Se si utilizza questo tipo di policy con un nome di dominio personalizzato, le suite di crittografia corrispondono al tipo di chiave di certificato fornito dal cliente, RSA o ECDSA. Se utilizzi questo tipo di policy con un'API REST, le suite di crittografia corrispondono alle suite di crittografia compatibili con i tipi di certificati RSA. # Policy di sicurezza supportate Le tabelle seguenti descrivono le [politiche di sicurezza](apigateway-security-policies.md) che possono essere specificate per ogni tipo di endpoint dell'API REST e tipo di nome di dominio personalizzato. Queste politiche consentono di controllare le connessioni in entrata. API Gateway supporta solo TLS 1.2 in uscita. Puoi aggiornare la politica di sicurezza per la tua API o il tuo nome di dominio personalizzato in qualsiasi momento. Le politiche contenute `FIPS` nel titolo sono compatibili con il Federal Information Processing Standard (FIPS), uno standard governativo statunitense e canadese che specifica i requisiti di sicurezza per i moduli crittografici che proteggono le informazioni sensibili. Per ulteriori informazioni, consulta [Federal Information Processing Standard (FIPS) 140](https://aws.amazon.com/compliance/fips/) nella pagina *AWS Cloud* Security Compliance. Tutte le politiche FIPS sfruttano il modulo crittografico convalidato FIPS AWS-LC. Per saperne di più, consulta la pagina del modulo crittografico [AWS-LC sul sito del *NIST Cryptographic* Module](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4631) Validation Program. Le politiche contenute `PQ` nel titolo utilizzano la [crittografia post-quantistica (PQC)](https://aws.amazon.com/security/post-quantum-cryptography/) per implementare algoritmi ibridi di scambio di chiavi per TLS per garantire la riservatezza del traffico contro le future minacce informatiche quantistiche. Le politiche contenute `PFS` nel titolo utilizzano [Perfect Forward Secrecy (PFS](https://en.wikipedia.org/wiki/Forward_secrecy)) per garantire che le chiavi di sessione non vengano compromesse. Le politiche che le contengono entrambe `FIPS` e `PQ` nel loro titolo supportano entrambe queste funzionalità. ## Politiche di sicurezza predefinite Quando crei una nuova API REST o un dominio personalizzato, alla risorsa viene assegnata una politica di sicurezza predefinita. La tabella seguente mostra la politica di sicurezza predefinita per queste risorse. | **Risorsa** | **Nome della politica di sicurezza predefinita** | | --- | --- | | Regionale APIs | TLS\$11\$10 | | Ottimizzato per Edge APIs | TLS\$11\$10 | | Privato APIs | TLS\$11\$12 | | Dominio regionale | TLS\$11\$12 | | Dominio ottimizzato per Edge | TLS\$11\$12 | | Dominio privato | TLS\$11\$12 | ## Politiche di sicurezza supportate per nomi di dominio regionali, privati e personalizzati APIs La tabella seguente descrive le politiche di sicurezza che possono essere specificate per i nomi di dominio regionali, privati APIs e personalizzati: | **Policy di sicurezza** | **Versioni TLS supportate** | **Cifre supportate** | | --- | --- | --- | | SecurityPolicy\$1 \$11\$13\$12025\$109 TLS13 | TLS13. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 \$11\$13\$1FIPS\$12025\$109 TLS13 | TLS13. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 \$11\$12\$1FIPS\$1PFS\$1PQ\$12025\$109 TLS13 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 TLS13 1\$12\$1PFS\$1PQ\$12025\$109 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 TLS13 1\$12\$1PQ\$12025\$109 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 \$11\$12\$12021\$106 TLS13 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$12 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$10 | TLS13. TLS12. TLS11. TLS10. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | ## Politiche di sicurezza supportate per nomi di dominio personalizzati e ottimizzati per i dispositivi APIs periferici La tabella seguente descrive le politiche di sicurezza che possono essere specificate per i nomi di dominio personalizzati ottimizzati per i bordi e ottimizzati APIs per i bordi: | **Nome della politica di sicurezza** | **Versioni TLS supportate** | **Cifre supportate** | | --- | --- | --- | | SecurityPolicy\$1 \$12025\$1EDGE TLS13 | TLS13. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 \$1PFS\$12025\$1EDGE TLS12 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | SecurityPolicy\$1 2018 EDGE TLS12 | TLS13. TLS12. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | | TLS\$11\$10 | TLS13. TLS12. TLS11. TLS10. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-security-policies-list.html) | ## OpenSSL e nomi crittografia RFC OpenSSL e IETF RFC 5246 utilizzano nomi diversi per le stesse crittografie. La tabella seguente mappa il nome OpenSSL al nome RFC per ogni crittografia. Per ulteriori informazioni, consultare [ciphers](https://docs.openssl.org/1.1.1/man1/ciphers/) nella documentazione OpenSSL. | **Nome crittografia OpenSSL** | **Nome crittografia RFC** | | --- | --- | | TLS\$1AES\$1128\$1GCM\$1 SHA256 | TLS\$1AES\$1128\$1GCM\$1 SHA256 | | TLS\$1AES\$1256\$1GCM\$1 SHA384 | TLS\$1AES\$1256\$1GCM\$1 SHA384 | | TLS\$1 \$1 CHACHA20 POLY1305 SHA256 | CHACHA20TLS\$1 \$1 POLY1305 SHA256 | | ECDHE-RSA- -GCM- AES128 SHA256 | TLS\$1ECDHE\$1RSA\$1CON\$1AES\$1128\$1GCM\$1 SHA256 | | ECDHE-RSA- - AES128 SHA256 | TLS\$1ECDHE\$1RSA\$1CON\$1AES\$1128\$1CBC\$1 SHA256 | | ECDHE-RSA- -SHA AES128 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | | ECDHE-RSA- AES256 -GCM- SHA384 | TLS\$1ECDHE\$1RSA\$1CON\$1AES\$1256\$1GCM\$1 SHA384 | | ECDHE-RSA- - AES256 SHA384 | TLS\$1ECDHE\$1RSA\$1CON\$1AES\$1256\$1CBC\$1 SHA384 | | ECDHE-RSA- -SHA AES256 | TLS\$1ECDHE\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | | AES128-GCM- SHA256 | TLS\$1RSA\$1CON\$1AES\$1128\$1GCM\$1 SHA256 | | AES256-GCM- SHA384 | TLS\$1RSA\$1CON\$1AES\$1256\$1GCM\$1 SHA384 | | AES128-SHA256 | TLS\$1RSA\$1CON\$1AES\$1128\$1CBC\$1 SHA256 | | AES256-SHA | TLS\$1RSA\$1WITH\$1AES\$1256\$1CBC\$1SHA | | AES128-SHA | TLS\$1RSA\$1WITH\$1AES\$1128\$1CBC\$1SHA | | DES- -SHA CBC3 | TLS\$1RSA\$1WITH\$13DES\$1EDE\$1CBC\$1SHA | # Come modificare una politica di sicurezza Puoi modificare la politica di sicurezza per la tua API. Se invii traffico a te APIs tramite il tuo nome di dominio personalizzato, non è necessario che l'API e il nome di dominio personalizzato abbiano la stessa politica di sicurezza. Quando richiami quel nome di dominio personalizzato, API Gateway utilizza la politica di sicurezza dell'API per negoziare l'handshake TLS. Tuttavia, per motivi di coerenza, ti consigliamo di utilizzare la stessa politica di sicurezza per il nome di dominio e l'API personalizzati. Se modifichi la politica di sicurezza, sono necessari circa 15 minuti per completare l'aggiornamento. Puoi monitorare `apiStatus` la tua API. Man mano che la tua API si aggiorna, lo `apiStatus` è `UPDATING` e quando sarà completata, lo sarà`AVAILABLE`. Quando la tua API viene aggiornata, puoi comunque richiamarla. ------ #### [ Console di gestione AWS ] **Per modificare la politica di sicurezza di un'API** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere **Impostazioni API**, quindi scegliere **Modifica**. 1. Per **Politica di sicurezza**, seleziona una nuova politica che inizi con. `SecurityPolicy_` 1. Per la **modalità di accesso agli endpoint**, scegli **Strict**. 1. Scegli **Save changes** (Salva modifiche). Implementa nuovamente l'API per rendere effettive le modifiche. Poiché hai modificato la modalità di accesso agli endpoint in Strict, occorreranno circa 15 minuti prima che le modifiche si propaghino completamente. ------ #### [ AWS CLI ] Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente aggiorna un'API per utilizzare la politica `SecurityPolicy_TLS13_1_3_2025_09` di sicurezza: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations '[ { "op": "replace", "path": "/securityPolicy", "value": "SecurityPolicy_TLS13_1_3_2025_09" }, { "op": "replace", "path": "/endpointAccessMode", "value": "STRICT" } ]' ``` L'output sarà simile al seguente: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a new security policy", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09", "endpointAccessMode": "STRICT" "rootResourceId": "efg456" } ``` Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente aggiorna un'API che utilizzava una politica di sicurezza avanzata per utilizzare la politica `TLS_1_0` di sicurezza. ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations '[ { "op": "replace", "path": "/securityPolicy", "value": "TLS_1_0" }, { "op": "replace", "path": "/endpointAccessMode", "value": "" } ]' ``` L'output sarà simile al seguente: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a new security policy", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "securityPolicy": "TLS_1_0", "rootResourceId": "efg456" } ``` ------ # Tipi di indirizzo IP per REST API in Gateway API Quando si crea un’API, è possibile specificare il tipo di indirizzo IP che può invocarla. È possibile scegliere IPv4 per risolvere gli indirizzi IPv4 per invocare l’API oppure dualstack per consentire a entrambi gli indirizzi IPv4 e IPv6 di invocare l’API. È consigliabile impostare il tipo di indirizzo IP su dualstack per ridurre l’esaurimento dello spazio IP o per il livello di sicurezza. Per ulteriori informazioni sui vantaggi del tipo di indirizzo IP dualstack, consultare [IPv6 on AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). Per limitare l’API al solo traffico IPv6, è possibile creare una policy di risorse e limitare gli indirizzi IP di origine solo agli intervalli IPv6. È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’API. Questa modifica ha effetto immediato e non è necessario implementare nuovamente l’API. Per ulteriori informazioni, consulta [Esempio: negare il traffico API in base all'indirizzo IP di origine o a un intervallo di indirizzi IP](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example) ## Considerazioni sui tipi di indirizzo IP Le seguenti considerazioni potrebbero influire sull’utilizzo dei tipi di indirizzo IP: + Il tipo di indirizzo IP predefinito per tutte le API regionali e ottimizzate l’edge è IPv4. + Le API private possono avere solo il tipo di indirizzo IP dualstack. + Se per un’API esistente si modifica il tipo di indirizzo IP da IPv4 a dualstack, è necessario verificare che tutte le policy che controllano l’accesso alle API siano aggiornate in modo da tenere conto delle chiamate IPv6. Quando si modifica il tipo di indirizzo IP, la modifica diventa immediatamente effettiva. + Se si esegue la migrazione del tipo di endpoint di un’API da ottimizzato per l’edge o regionale a privato, Gateway API modifica il tipo di indirizzo IP in dualstack. Per ulteriori informazioni, consulta [Modifica di un tipo di endpoint API pubblico o privato in API Gateway](apigateway-api-migration.md). + Se si esegue la migrazione del tipo di endpoint di un’API da privato a regionale, è necessario impostare il tipo di indirizzo IP su dualstack. Una volta completata la migrazione dell’endpoint, è possibile modificare il tipo di indirizzo IP in IPv4. Per ulteriori informazioni, consulta [Modifica di un tipo di endpoint API pubblico o privato in API Gateway](apigateway-api-migration.md). + L’API può essere mappata su un nome di dominio personalizzato con un tipo di indirizzo IP diverso da quello dell’API. Se si disabilita l’endpoint API predefinito, si potrebbe influire sul modo in cui i chiamanti possono invocare l’API. + Non è possibile utilizzare un file di definizione esterno per configurare il tipo di indirizzo IP dell’API. # Modifica del tipo di indirizzo IP di una REST API È possibile modificare il tipo di indirizzo IP aggiornando la configurazione dell’API. È possibile aggiornare la configurazione dell’API utilizzando la Console di gestione AWS, AWS CLI, CloudFormation o un AWS SDK. Se si modifica il tipo di indirizzo IP dell’API, non è necessario eseguire di nuovo l’implementazione dell’API per rendere effettive le modifiche. Prima di modificare il tipo di indirizzo IP, è necessario verificare che tutte le policy che controllano l’accesso alle API siano aggiornate in modo da tenere conto delle chiamate IPv6. ------ #### [ Console di gestione AWS ] **Per modificare il tipo di indirizzo IP di una REST API** 1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Scegliere una REST API. 1. Scegliere **Impostazioni API**, quindi scegliere **Modifica**. 1. Per Tipo di indirizzo IP, selezionare **IPv4** o **Dualstack**. 1. Scegli **Save changes** (Salva modifiche). La modifica alla configurazione dell’API ha effetto immediato. ------ #### [ AWS CLI ] Il comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) seguente aggiorna un’API in modo che abbia un tipo di indirizzo IP dualstack: ``` aws apigateway update-rest-api \ --rest-api-id abcd1234 \ --patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'" ``` L'output sarà simile al seguente: ``` { "id": "abcd1234", "name": "MyAPI", "description": "My API with a dualstack IP address type", "createdDate": "2025-02-04T11:47:06-08:00", "apiKeySource": "HEADER", "endpointConfiguration": { "types": [ "REGIONAL" ], "ipAddressType": "dualstack" }, "tags": {}, "disableExecuteApiEndpoint": false, "rootResourceId": "efg456" } ``` ------ # 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. # Controlla e gestisci l'accesso a REST APIs in API Gateway API Gateway supporta più meccanismi per controllare e gestire l'accesso all'API. Puoi usare i seguenti meccanismi per l'autenticazione e l'autorizzazione: + **Le policy relative alle risorse ti consentono di** creare policy basate sulle risorse per consentire o negare l'accesso ai tuoi metodi APIs e ai tuoi metodi da indirizzi IP di origine o endpoint VPC specifici. Per ulteriori informazioni, consulta [Controllo degli accessi a una REST API con le policy delle risorse Gateway API](apigateway-resource-policies.md). + **I ruoli e le policy AWS IAM standard** offrono controlli di accesso flessibili e robusti che possono essere applicati a un'intera API o a singoli metodi. I ruoli e le policy IAM possono essere utilizzati per controllare chi può creare e gestire APIs i tuoi e chi può richiamarli. Per ulteriori informazioni, consulta [Controllo degli accessi a una REST API con le autorizzazioni IAM](permissions.md). + I **tag IAM** possono essere utilizzati insieme alle policy IAM per controllare l'accesso. Per ulteriori informazioni, consulta [Utilizzo dei tag per controllare l'accesso alle risorse REST API di Gateway API](apigateway-tagging-iam-policy.md). + **Le policy degli endpoint per gli endpoint VPC di interfaccia** [ti consentono di collegare le policy delle risorse IAM agli endpoint VPC di interfaccia per migliorare la sicurezza del tuo ambiente privato. APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html) Per ulteriori informazioni, consulta [Usa le policy degli endpoint VPC per uso privato APIs in API Gateway](apigateway-vpc-endpoint-policies.md). + Le **autorizzazioni Lambda** sono funzioni Lambda che controllano l'accesso ai metodi API REST usando l'autenticazione con token di connessione, nonché le informazioni descritte da intestazioni, percorsi, stringhe di query, variabili di fase o parametri di richiesta di variabili di contesto. Le autorizzazioni Lambda vengono utilizzate per controllare chi può richiamare i metodi API REST. Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). + I **pool di utenti di Amazon Cognito** ti consentono di creare soluzioni di autenticazione e autorizzazione personalizzabili per il tuo REST. APIs I pool di utenti di Amazon Cognito vengono utilizzati per controllare chi può richiamare i metodi delle API REST. Per ulteriori informazioni, consulta [Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore](apigateway-integrate-with-cognito.md). Puoi utilizzare i seguenti meccanismi per l'esecuzione di altre attività correlate al controllo degli accessi: + La funzionalità **Cross-origin resource sharing (CORS)** consente di controllare il modo in cui l'API REST risponde alle richieste di risorse multidominio. Per ulteriori informazioni, consulta [CORS per REST APIs in API Gateway](how-to-cors.md). + I **certificati SSL lato client** possono essere utilizzati per verificare che le richieste HTTP al sistema back-end provengano da API Gateway. Per ulteriori informazioni, consulta [Generazione e configurazione di un certificato SSL per l'autenticazione backend in Gateway API](getting-started-client-side-ssl-authentication.md). + **AWS WAF** può essere utilizzato per proteggere l'API di API Gateway da exploit di Web comuni. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). Puoi utilizzare i seguenti meccanismi per monitorare e limitare l'accesso che è stato consentito ai client autorizzati: + I **piani di utilizzo** consentono di fornire **chiavi API** ai clienti e quindi di monitorare e limitare l'utilizzo delle fasi e dei metodi API per ciascuna chiave API. Per ulteriori informazioni, consulta [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md). # Controllo degli accessi a una REST API con le policy delle risorse Gateway API Le *policy delle risorse* di Gateway Amazon API sono documenti di policy JSON collegati a un'API per controllare se un principale specificato (in genere un gruppo o un ruolo IAM) può richiamare l'API. È possibile usare le policy di risorse API Gateway per consentire alle API di essere chiamate in modo sicuro da: + Utenti di un AWS account specificato. + Intervalli di indirizzi IP sorgente specificati o blocchi CIDR. + Cloud privati virtuali (VPCs) o endpoint VPC specificati (in qualsiasi account). È possibile allegare una policy di risorse per qualsiasi tipo di endpoint API in API Gateway utilizzando Console di gestione AWS la AWS CLI o. AWS SDKs In [ambito privato APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-private-apis.html), puoi utilizzare le policy delle risorse insieme alle policy degli endpoint VPC per controllare quali principali hanno accesso a quali risorse e azioni. Per ulteriori informazioni, consulta [Usa le policy degli endpoint VPC per uso privato APIs in API Gateway](apigateway-vpc-endpoint-policies.md). Le policy delle risorse API Gateway sono diverse dalle policy IAM basate su identità. Le policy IAM basate su identità sono collegate a utenti, gruppi o ruoli IAM e definiscono le operazioni che tali identità sono in grado di eseguire e su quali risorse. Le policy delle risorse API Gateway sono collegate alle risorse. L'utilizzo combinato delle policy delle risorse API Gateway e delle policy IAM è consentito. Per ulteriori informazioni, consultare [Identity-Based Policies and Resource-Based Policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html). **Topics** + [Panoramica della sintassi delle policy di accesso per Amazon API Gateway](apigateway-control-access-policy-language-overview.md) + [Come le policy delle risorse API Gateway influiscono sul flusso di lavoro delle autorizzazioni](apigateway-authorization-flow.md) + [Esempi di policy delle risorse API Gateway](apigateway-resource-policies-examples.md) + [Creazione e collegamento di una policy delle risorse API Gateway a un'API](apigateway-resource-policies-create-attach.md) + [AWS chiavi di condizione che possono essere utilizzate nelle politiche delle risorse di API Gateway](apigateway-resource-policies-aws-condition-keys.md) # Panoramica della sintassi delle policy di accesso per Amazon API Gateway Questa pagina descrive gli elementi di base usati nelle policy per le risorse Amazon API Gateway. Le policy delle risorse vengono specificate utilizzando la stessa sintassi delle policy IAM. Per informazioni complete sulla sintassi delle policy, consulta [Panoramica delle policy IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) e [Riferimento alle policy AWS Identity and Access Management](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies.html) nella *Guida per l'utente di IAM*. Per informazioni su come un AWS servizio decide se una determinata richiesta deve essere consentita o rifiutata, vedere [Determinare se una richiesta è consentita](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#policy-eval-denyallow) o rifiutata. ## Elementi comuni in una policy di accesso In termini basilari, una policy delle risorse contiene i seguenti elementi: + **Risorse**: APIs sono le risorse di Amazon API Gateway per le quali puoi consentire o negare le autorizzazioni. In una policy, utilizzare l'Amazon Resource Name (ARN) per identificare la risorsa. È inoltre possibile utilizzare la sintassi abbreviata, che API Gateway espande automaticamente fino all'ARN completo quando si salva una policy delle risorse. Per ulteriori informazioni, consulta [Esempi di policy delle risorse API Gateway](apigateway-resource-policies-examples.md). Per il formato dell'elemento `Resource` completo, consulta [Formato dell'elemento Resource delle autorizzazioni per l'esecuzione dell'API in API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-resource-format-for-executing-api). + **Azioni**: per ogni risorsa, Amazon API Gateway supporta un insieme di operazioni. Vengono identificate le operazioni delle risorse che verranno consentite (o rifiutate) utilizzando le parole chiave dell'operazione. Ad esempio, l'autorizzazione `execute-api:Invoke` consentirà all'utente di richiamare un'API in seguito alla richiesta di un client. Per il formato dell'elemento `Action`, consulta [Formato dell'elemento Action delle autorizzazioni per l'esecuzione dell'API in API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-iam-policy-action-format-for-executing-api). + **Effetto**: l'effetto prodotto quando l'utente richiede una determinata operazione; può essere `Allow` o `Deny`. È anche possibile rifiutare esplicitamente l'accesso a una risorsa per essere certi che un utente non sia in grado di accedervi, anche quando tale accesso è assegnato da un'altra policy. **Nota** "Rifiuto implicito" ha lo stesso significato di "rifiuto per default". Un "rifiuto implicito" è diverso da un "rifiuto esplicito". Per ulteriori informazioni, consulta la sezione sulla [differenza tra rifiuto per default e rifiuto esplicito](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_evaluation-logic.html#AccessPolicyLanguage_Interplay). + **Principale**: account o utente autorizzato ad accedere alle operazioni e alle risorse nell'istruzione. In una policy delle risorse, il principale è l'utente o l'account che riceve questa autorizzazione. L'esempio di policy delle risorse seguente mostra gli elementi di policy comuni descritti in precedenza. La policy concede l'accesso all'API in base a quanto specificato *account-id* nel campo specificato *region* a qualsiasi utente il cui indirizzo IP di origine si trova nel blocco di indirizzi. *123.4.5.6/24* La policy nega l'accesso all'API se l'IP di origine dell'utente non rientra nell'intervallo. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:*" }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:*", "Condition": { "NotIpAddress": { "aws:SourceIp": "123.4.5.6/24" } } } ] } ``` ------ # Come le policy delle risorse API Gateway influiscono sul flusso di lavoro delle autorizzazioni Quando API Gateway valuta la policy delle risorse collegata all'API, il risultato è influenzato dal tipo di autenticazione definito per l'API, come illustrato nei diagrammi nelle seguenti sezioni. **Topics** + [Solo policy delle risorse API Gateway](#apigateway-authorization-flow-resource-policy-only) + [Autorizzazione Lambda e policy delle risorse](#apigateway-authorization-flow-lambda) + [Autenticazione IAM e policy delle risorse](#apigateway-authorization-flow-iam) + [Autenticazione Amazon Cognito e policy delle risorse](#apigateway-authorization-flow-cognito) + [Tabelle dei risultati della valutazione delle policy](#apigateway-resource-policies-iam-policies-interaction) ## Solo policy delle risorse API Gateway In questo flusso di lavoro, una policy delle risorse API Gateway è collegata all'API, ma non viene definito alcun tipo di autenticazione per l'API. La valutazione della policy comporta la ricerca di un'autorizzazione esplicita basata sui criteri in entrata dell'intermediario. Un rifiuto implicito o esplicito comporta il rifiuto dell'intermediario. ![\[Flusso di autorizzazione solo di una policy delle risorse.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-auth-resource-policy-only.png) Di seguito viene riportato un esempio di tale policy delle risorse. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ ## Autorizzazione Lambda e policy delle risorse In questo flusso di lavoro, un'autorizzazione Lambda è configurata per l'API in aggiunta a una policy delle risorse. La policy delle risorse viene valutata in due fasi. Prima di chiamare l'autorizzazione Lambda, API Gateway valuta innanzitutto la policy e controlla la presenza di eventuali negazioni esplicite. Se riscontrati, all'intermediario viene negato subito l'accesso. In caso contrario viene chiamata l'autorizzazione Lambda, che restituisce un [documento della policy](api-gateway-lambda-authorizer-output.md) che viene valutato insieme alla policy delle risorse. Se il sistema di autorizzazione utilizza il caching, Gateway API potrebbe restituire il documento di policy memorizzato nella cache. Il risultato è determinato in base alla [tabella A](#apigateway-resource-policies-iam-policies-interaction). La seguente policy delle risorse di esempio autorizza le chiamate solo dall'endpoint VPC il cui ID è `vpce-1a2b3c4d`. Nella fase di valutazione "pre-autorizzazione", solo le chiamate provenienti dall'endpoint VPC indicato nell'esempio sono autorizzate a proseguire e a valutare l'autorizzazione Lambda. Tutte le chiamate rimanenti vengono bloccate. Questo flusso di lavoro di autorizzazione è lo stesso se si utilizza un nome di dominio personalizzato per un’API privata. ![\[Flusso di autorizzazione per una policy delle risorse e un sistema di autorizzazione Lambda.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-auth-lambda-resource-policy.png) ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ ## Autenticazione IAM e policy delle risorse In questo flusso di lavoro, viene configurata un'autenticazione IAM per l'API in aggiunta a una policy delle risorse. Dopo l'autenticazione dell'utente con il servizio IAM, l'API valuta sia le policy collegate all'utente sia la policy delle risorse. Il risultato varia a seconda che il chiamante si trovi nello stesso account Account AWS o in un altro Account AWS, rispetto al proprietario dell'API. Se il chiamante e il proprietario dell'API sono in account diversi, il chiamante sarà autorizzato esplicitamente a procedere sia dalle policy dell'utente IAM sia dalla policy delle risorse. Per ulteriori informazioni, consulta la [tabella B](#apigateway-resource-policies-iam-policies-interaction). Tuttavia, se il chiamante e il proprietario dell'API si trovano nello stesso Account AWS, le policy dell'utente IAM o la policy delle risorse devono esplicitamente autorizzare il chiamante a proseguire. Per ulteriori informazioni, consulta la [tabella A](#apigateway-resource-policies-iam-policies-interaction). ![\[Flusso di autorizzazione per una policy delle risorse e un'autenticazione IAM.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-auth-iam-resource-policy.png) Di seguito viene riportato un esempio di policy delle risorse multiaccount. Ipotizzando che la policy IAM contenga un'autorizzazione di questo tipo, questa policy delle risorse permette chiamate solo dal VPC il cui ID VPC è `vpc-2f09a348`. Per ulteriori informazioni, consulta la [tabella B](#apigateway-resource-policies-iam-policies-interaction). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/" ], "Condition" : { "StringEquals": { "aws:SourceVpc": "vpc-2f09a348" } } } ] } ``` ------ ## Autenticazione Amazon Cognito e policy delle risorse In questo flusso di lavoro, un [pool di utenti di Amazon Cognito](apigateway-integrate-with-cognito.md) è configurato per l'API in aggiunta a una policy delle risorse. API Gateway tenta innanzitutto di autenticare l'intermediario tramite Amazon Cognito. Questa operazione viene in genere eseguita tramite un [token JWT](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) fornito dall'intermediario. Se l'autenticazione va a buon fine, la policy delle risorse viene valutata in modo indipendente ed è richiesta un'autorizzazione esplicita. Un rifiuto o "non consentire né rifiutare" si traduce in un rifiuto. Di seguito è riportato un esempio di una policy delle risorse che potrebbe essere utilizzata insieme a pool di utenti di Amazon Cognito. ![\[Flusso di autorizzazione per una policy delle risorse e un sistema di autorizzazione di Amazon Cognito.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/apigateway-auth-cognito-resource-policy.png) Di seguito è riportato un esempio di politica delle risorse che consente chiamate solo da una fonte specificata IPs, presupponendo che il token di autenticazione Amazon Cognito contenga un'autorizzazione. Per ulteriori informazioni, consulta la [tabella B](#apigateway-resource-policies-iam-policies-interaction). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:us-east-1:111111111111:api-id/", "Condition": { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ ## Tabelle dei risultati della valutazione delle policy La tabella A riporta il comportamento risultante quando l'accesso a un'API di Gateway API è controllato da una policy IAM o da un sistema di autorizzazione Lambda e da una policy delle risorse Gateway API, entrambe nello stesso Account AWS. | **Policy IAM (o sistema di autorizzazione Lambda)** | **Policy delle risorse Gateway API** | **Comportamento risultante** | | --- | --- | --- | | Abilita | Abilita | Abilita | | Abilita | Né Abilita né Rifiuta | Abilita | | Abilita | Rifiuta | Explicit Deny (rifiuto esplicito) | | Né Abilita né Rifiuta | Abilita | Abilita | | Né Abilita né Rifiuta | Né Abilita né Rifiuta | Rifiuto implicito | | Né Abilita né Rifiuta | Rifiuta | Explicit Deny (rifiuto esplicito) | | Rifiuta | Abilita | Explicit Deny (rifiuto esplicito) | | Rifiuta | Né Abilita né Rifiuta | Explicit Deny (rifiuto esplicito) | | Rifiuta | Rifiuta | Explicit Deny (rifiuto esplicito) | La Tabella B elenca il comportamento risultante quando l'accesso a un'API API Gateway è controllato da una policy IAM o da un autorizzatore di pool di utenti di Amazon Cognito e da una policy di risorse API Gateway, che sono diversi. Account AWS Se una delle due è silente (non permette né rifiuta). l'accesso multiaccount viene negato. Questo perché l'accesso multi-account richiede l'autorizzazione esplicita all'accesso sia dalla policy delle risorse sia dalla policy IAM o dal sistema di autorizzazione del pool di utenti di Amazon Cognito. | **Policy IAM o sistema di autorizzazione del pool di utenti di Amazon Cognito** | **Policy delle risorse Gateway API** | **Comportamento risultante** | | --- | --- | --- | | Abilita | Abilita | Abilita | | Abilita | Né Abilita né Rifiuta | Rifiuto implicito | | Abilita | Rifiuta | Explicit Deny (rifiuto esplicito) | | Né Abilita né Rifiuta | Abilita | Rifiuto implicito | | Né Abilita né Rifiuta | Né Abilita né Rifiuta | Rifiuto implicito | | Né Abilita né Rifiuta | Rifiuta | Explicit Deny (rifiuto esplicito) | | Rifiuta | Abilita | Explicit Deny (rifiuto esplicito) | | Rifiuta | Né Abilita né Rifiuta | Explicit Deny (rifiuto esplicito) | | Rifiuta | Rifiuta | Explicit Deny (rifiuto esplicito) | # Esempi di policy delle risorse API Gateway Questa pagina include alcuni esempi di casi d'uso tipici per le policy delle risorse API Gateway. Le policy di esempio seguenti utilizzano una sintassi semplificata per specificare la risorsa API. Questa sintassi semplificata è un modo abbreviato per fare riferimento a una risorsa API, invece di specificare l'Amazon Resource Name (ARN) completo. API Gateway converte la sintassi abbreviata nell'ARN completo quando si salva la policy. Ad esempio, è possibile specificare la risorsa `execute-api:/stage-name/GET/pets` in una policy delle risorse. API Gateway converte la risorsa in `arn:aws:execute-api:us-east-2:123456789012:aabbccddee/stage-name/GET/pets` quando si salva la policy delle risorse. API Gateway crea l'ARN completo utilizzando la regione corrente, l'ID dell' AWS account e l'ID dell'API REST a cui è associata la politica delle risorse. È possibile utilizzare `execute-api:/*` per rappresentare tutti gli stadi, i metodi e i percorsi nell'API corrente. Per informazioni sulla sintassi della/e policy di accesso, consulta [Panoramica della sintassi delle policy di accesso per Amazon API Gateway](apigateway-control-access-policy-language-overview.md). **Topics** + [Esempio: consentire ai ruoli di un altro AWS account di utilizzare un'API](#apigateway-resource-policies-cross-account-example) + [Esempio: negare il traffico API in base all'indirizzo IP di origine o a un intervallo di indirizzi IP](#apigateway-resource-policies-source-ip-address-example) + [Esempio: rifiutare il traffico API in base all'indirizzo IP di origine o all'intervallo quando si utilizza un'API privata](#apigateway-resource-policies-source-ip-address-vpc-example) + [Esempio: consenti il traffico di API private in base all'endpoint VPC o al VPC sorgente](#apigateway-resource-policies-source-vpc-example) ## Esempio: consentire ai ruoli di un altro AWS account di utilizzare un'API L'esempio seguente di policy in materia di risorse concede l'accesso dell'API in un AWS account a due ruoli in un AWS account diverso tramite i protocolli [Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/create-signed-request.html) (SigV4) o [Signature Version 4a (SigV4a](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html#how-sigv4a-works)). In particolare, allo sviluppatore e al ruolo di amministratore dell' AWS account identificato da `account-id-2` viene concessa l'azione per eseguire l'`execute-api:Invoke``GET`azione sulla `pets` risorsa (API) dell'account. AWS ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111122223333:role/developer", "arn:aws:iam::111122223333:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ ## Esempio: negare il traffico API in base all'indirizzo IP di origine o a un intervallo di indirizzi IP L'esempio di policy delle risorse seguente rifiuta (blocca) il traffico in ingresso verso un'API da due blocchi di indirizzi IP di origine specificati. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "IpAddress": { "aws:SourceIp": ["192.0.2.0/24", "198.51.100.0/24" ] } } } ] } ``` ------ Se utilizzi policy utente IAM o policy di risorse API Gateway per controllare l'accesso ad API Gateway o a qualsiasi API Gateway APIs, conferma che le policy siano aggiornate per includere intervalli di IPv6 indirizzi. Le policy che non sono aggiornate per gestire IPv6 gli indirizzi potrebbero influire sull'accesso del cliente ad API Gateway quando inizia a utilizzare l'endpoint dualstack. Per ulteriori informazioni, consulta [Utilizzo IPv6 degli indirizzi nelle politiche IAM](api-ref.md#api-reference-service-endpoints-dualstack-iam). ## Esempio: rifiutare il traffico API in base all'indirizzo IP di origine o all'intervallo quando si utilizza un'API privata L'esempio di policy delle risorse seguente rifiuta (blocca) il traffico in ingresso verso un'API da due blocchi di indirizzi IP di origine specificati. Quando si utilizza private APIs, l'endpoint VPC `execute-api` riscrive l'indirizzo IP di origine originale. La condizione `aws:VpcSourceIp` filtra la richiesta rispetto all'indirizzo IP del richiedente originale. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "IpAddress": { "aws:VpcSourceIp": ["192.0.2.0/24", "198.51.100.0/24"] } } } ] } ``` ------ ## Esempio: consenti il traffico di API private in base all'endpoint VPC o al VPC sorgente Le seguenti policy delle risorse di esempio consentono il traffico in entrata per un'API privata solo da un VPC o da un endpoint VPC specifici. Questa policy della risorsa di esempio specifica il VPC di origine: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpc": "vpc-1a2b3c4d" } } } ] } ``` ------ Questa policy della risorsa di esempio specifica l'endpoint VPC di origine: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "vpce-1a2b3c4d" } } } ] } ``` ------ # Creazione e collegamento di una policy delle risorse API Gateway a un'API Per consentire a un utente di accedere all'API chiamando il servizio di esecuzione dell'API, è necessario creare una policy delle risorse Gateway API e collegare la policy all'API. Il collegamento di una policy all'API comporta l'applicazione delle autorizzazioni della policy ai metodi dell'API. Se si aggiorna la policy delle risorse, è necessario implementare l'API. **Topics** + [Prerequisiti](#apigateway-resource-policies-prerequisites) + [Collegamento di una policy delle risorse a un'API di Gateway API](#apigateway-resource-policies-create-attach-procedure) + [Risoluzione dei problemi relativi alla policy delle risorse](#apigateway-resource-policies-troubleshoot) ## Prerequisiti Per aggiornare una policy delle risorse Gateway API, è necessario disporre delle autorizzazioni `apigateway:UpdateRestApiPolicy` e `apigateway:PATCH`. Per un'API ottimizzata per l'edge o regionale, è possibile collegare la policy delle risorse all'API al momento della creazione o dopo che è stata implementata. Un'API privata non può essere implementata senza una policy delle risorse. Per ulteriori informazioni, consulta [REST privato APIs in API Gateway](apigateway-private-apis.md). ## Collegamento di una policy delle risorse a un'API di Gateway API La procedura seguente mostra come collegare una policy delle risorse a un'API di Gateway API. ------ #### [ Console di gestione AWS ] **Per collegare una policy delle risorse a un'API di API Gateway** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Nel riquadro di navigazione principale, scegli **Policy delle risorse**. 1. Scegli **Crea policy**. 1. (Facoltativo) Scegli **Seleziona un modello** per generare una policy di esempio. Negli esempi di policy, i segnaposto sono racchiusi tra parentesi graffe doppie (`"{{placeholder}}"`). Sostituisci ogni segnaposto, incluse le parentesi graffe, con le informazioni necessarie. 1. Se non utilizzi uno dei modelli di esmepio, immetti la tua policy delle risorse. 1. Scegli **Save changes** (Salva modifiche). Se l'API è stata distribuita in precedenza nella console API Gateway, sarà necessario ridistribuirla affinché la policy delle risorse diventi effettiva. ------ #### [ AWS CLI ] Per utilizzare il AWS CLI per creare una nuova API e allegare ad essa una politica delle risorse, usa il seguente comando: [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html) ``` aws apigateway create-rest-api \ --name "api-name" \ --policy "{\"jsonEscapedPolicyDocument\"}" ``` Per utilizzare AWS CLI per allegare una politica delle risorse a un'API esistente, utilizzare il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente: ``` aws apigateway update-rest-api \ --rest-api-id api-id \ --patch-operations op=replace,path=/policy,value='"{\"jsonEscapedPolicyDocument\"}"' ``` È inoltre possibile allegare la politica delle risorse come `policy.json` file separato e includerla nel [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando. Il [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando seguente crea una nuova API con una politica delle risorse: ``` aws apigateway create-rest-api \ --name "api-name" \ --policy file://policy.json ``` Il file `policy.json` è una policy delle risorse Gateway API, come descritto in [Esempio: negare il traffico API in base all'indirizzo IP di origine o a un intervallo di indirizzi IP](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ------ #### [ AWS CloudFormation ] È possibile utilizzare CloudFormation per creare un'API con una politica delle risorse. L'esempio seguente crea una REST API con la policy delle risorse di esempio, come descritto in [Esempio: negare il traffico API in base all'indirizzo IP di origine o a un intervallo di indirizzi IP](apigateway-resource-policies-examples.md#apigateway-resource-policies-source-ip-address-example). ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: testapi Policy: Statement: - Action: 'execute-api:Invoke' Effect: Allow Principal: '*' Resource: 'execute-api:/*' - Action: 'execute-api:Invoke' Effect: Deny Principal: '*' Resource: 'execute-api:/*' Condition: IpAddress: 'aws:SourceIp': ["192.0.2.0/24", "198.51.100.0/24" ] Version: 2012-10-17 Resource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'helloworld' MethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref Resource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: MOCK RequestTemplates: application/json: '{"statusCode": 200}' IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: '{}' MethodResponses: - StatusCode: 200 ResponseModels: application/json: 'Empty' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - MethodGet Properties: RestApiId: !Ref Api StageName: test ``` ------ ## Risoluzione dei problemi relativi alla policy delle risorse La seguente guida può aiutare a risolvere i problemi relativi alla policy delle risorse. ### L'API restituisce \$1"Message":"User: anonymous is not authorized to perform: execute-api:Invoke on resource: arn:aws:execute-api:us-east-1:\$1\$1\$1\$1\$1\$1\$1\$1/\$1\$1\$1\$1/\$1\$1\$1\$1/"\$1 Nella politica delle risorse, se imposti il AWS Principal su un principale, ad esempio: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": [ "arn:aws:iam::111111111111:role/developer", "arn:aws:iam::111111111111:role/Admin" ] }, "Action": "execute-api:Invoke", "Resource": [ "execute-api:/stage/GET/pets" ] } ] } ``` ------ Devi utilizzare l'autorizzazione `AWS_IAM` per ogni metodo dell'API, altrimenti l'API restituirà il messaggio di errore precedente. Per ulteriori indicazioni su come attivare l'autorizzazione `AWS_IAM` per un metodo, consulta [Metodi per REST APIs in API Gateway](how-to-method-settings.md). ### La policy delle risorse non viene aggiornata Se aggiorni la policy delle risorse dopo la creazione dell'API, dovrai distribuire l'API per propagare le modifiche dopo il collegamento della policy aggiornata. L'aggiornamento o il salvataggio della policy non modificherà il comportamento di runtime dell'API. Per ulteriori informazioni sulla distribuzione della tua API, vedi [Implementazione di REST API in Gateway API](how-to-deploy-api.md). ### La policy delle risorse restituisce il seguente errore: Invalid policy document. Please check the policy syntax and ensure that Principals are valid. Per correggere questo errore, è consigliabile innanzitutto controllare la sintassi della policy. Per ulteriori informazioni, consulta [Panoramica della sintassi delle policy di accesso per Amazon API Gateway](apigateway-control-access-policy-language-overview.md). Si suggerisce anche di verificare che tutti i principali specificati siano validi e non siano stati eliminati. Inoltre, se l'API si trova in una [Regione con consenso esplicito](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html?icmpid=docs_homepage_addtlrcs#optinregion), verificare che la Regione sia abilitata per tutti gli account della policy delle risorse. # AWS chiavi di condizione che possono essere utilizzate nelle politiche delle risorse di API Gateway La tabella seguente contiene le chiavi di AWS condizione che possono essere utilizzate nelle politiche delle risorse per APIs API Gateway per ogni tipo di autorizzazione. Per ulteriori informazioni sulle chiavi AWS condizionali, consulta [AWS Global Condition Context Keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html). | **Chiavi di condizione** | **Criteri** | **Necessita di `AuthN`?** | **Tipo di autorizzazione** | | --- | --- | --- | --- | | aws:CurrentTime | Nessuna | No | Tutti | | aws:EpochTime | Nessuna | No | Tutti | | aws:TokenIssueTime | La chiave è presente solo nelle richieste firmate utilizzando credenziali di sicurezza temporanee. | Sì | IAM | | aws:MultiFactorAuthPresent | La chiave è presente solo nelle richieste firmate utilizzando credenziali di sicurezza temporanee. | Sì | IAM | | aws:MultiFactorAuthAge | La chiave è presente solo se MFA è presente nelle richieste. | Sì | IAM | | aws:PrincipalAccount | Nessuna | Sì | IAM | | aws:PrincipalArn | Nessuna | Sì | IAM | | aws:PrincipalOrgID | Questa chiave viene inclusa nel contesto della richiesta solo se l'entità è membro di un'organizzazione. | Sì | IAM | | aws:PrincipalOrgPaths | Questa chiave viene inclusa nel contesto della richiesta solo se l'entità è membro di un'organizzazione. | Sì | IAM | | aws:PrincipalTag | Questa chiave è inclusa nel contesto della richiesta se l'entità utilizza un utente IAM con tag collegati. È inclusa per un'entità che utilizza un ruolo IAM con tag collegati o tag di sessione. | Sì | IAM | | aws:PrincipalType | Nessuna | Sì | IAM | | aws:Referer | La chiave è presente solo se il valore è fornito dall'intermediario nell'intestazione HTTP. | No | Tutti | | aws:SecureTransport | Nessuna | No | Tutti | | aws:SourceArn | Nessuna | No | Tutti | | aws:SourceIp | Nessuna | No | Tutti | | aws:SourceVpc | Questa chiave può essere utilizzata solo per uso privato APIs. | No | Tutti | | aws:SourceVpce | Questa chiave può essere usata solo per uso privato APIs. | No | Tutti | | aws:VpcSourceIp | Questa chiave può essere usata solo per uso privato APIs. | No | Tutti | | aws:UserAgent | La chiave è presente solo se il valore è fornito dall'intermediario nell'intestazione HTTP. | No | Tutti | | aws:userid | Nessuna | Sì | IAM | | aws:username | Nessuna | Sì | IAM | # Controllo degli accessi a una REST API con le autorizzazioni IAM Puoi controllare l'accesso all'API di Amazon API Gateway con le [autorizzazioni IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_controlling.html) controllando l'accesso ai seguenti due processi componenti di API Gateway: + Per creare, distribuire e gestire un'API in API Gateway, è necessario concedere allo sviluppatore dell'API le autorizzazioni per eseguire le operazioni richieste supportate dal componente di gestione dell'API di API Gateway. + Per chiamare un'API distribuita o per aggiornare la memorizzazione nella cache dell'API, è necessario concedere all'intermediario dell'API le autorizzazioni per eseguire le operazioni IAM supportate dal componente di esecuzione dell'API di API Gateway. Il controllo degli accessi per i due processi prevede l'uso dei due diversi modelli di autorizzazione illustrati più avanti. ## Modello di autorizzazione API Gateway per la creazione e la gestione di un'API Per consentire a uno sviluppatore di API di creare e gestire un'API in API Gateway, è necessario [creare le policy di autorizzazione IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) che consentono a uno sviluppatore di API specifico di creare, aggiornare, distribuire, visualizzare o eliminare le [entità API](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) richieste. È possibile collegare la policy delle autorizzazioni a un utente, un ruolo o un gruppo. Per fornire l’accesso, aggiungi autorizzazioni agli utenti, gruppi o ruoli: + Utenti e gruppi in AWS IAM Identity Center: Crea un set di autorizzazioni. Segui le istruzioni riportate nella pagina [Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/howtocreatepermissionset.html) (Creazione di un set di autorizzazioni) nella *Guida per l’utente di AWS IAM Identity Center *. + Utenti gestiti in IAM tramite un provider di identità: Crea un ruolo per la federazione delle identità. Segui le istruzioni riportate nella pagina [Create a role for a third-party identity provider (federation)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-idp.html) della *Guida per l’utente IAM*. + Utenti IAM: + Crea un ruolo che l’utente possa assumere. Segui le istruzioni riportate nella pagina [Create a role for an IAM user](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-user.html) della *Guida per l’utente IAM*. + (Non consigliato) Collega una policy direttamente a un utente o aggiungi un utente a un gruppo di utenti. Segui le istruzioni riportate nella pagina [Aggiunta di autorizzazioni a un utente (console)](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) nella *Guida per l’utente IAM*. Per ulteriori informazioni su come usare il modello di autorizzazione, consulta [Policy basate su identità dei API Gateway](security_iam_service-with-iam.md#security_iam_service-with-iam-id-based-policies). ## Modello di autorizzazione API Gateway per invocare un'API Per consentire a un chiamante dell'API di richiamare l'API o aggiornare la relativa memorizzazione nella cache, è necessario creare policy IAM che permettano al chiamante dell'API specificato di richiamare il metodo API per il quale è abilitata l'autenticazione dell'utente. Lo sviluppatore dell'API imposta la proprietà `authorizationType` del metodo su `AWS_IAM` per richiedere al chiamante di inviare le chiavi di accesso dell'utente per l'autenticazione. Gateway API supporta Signature Version 4a (SigV4a) e Signature Version 4 (SigV4) per autenticare le credenziali dell’utente. Per ulteriori informazioni, consultare [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Sarà quindi possibile collegare la policy all'utente, al gruppo o al ruolo. In questa istruzione di policy di autorizzazione IAM l'elemento IAM `Resource` contiene un elenco di metodi API distribuiti identificati da verbi HTTP e [percorsi di risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) API Gateway specifici. L'elemento IAM `Action` contiene le operazioni di esecuzione API di API Gateway richieste. Tali operazioni includono `execute-api:Invoke` o `execute-api:InvalidateCache`, dove `execute-api` designa il componente di esecuzione dell'API sottostante di API Gateway. Per ulteriori informazioni su come usare il modello di autorizzazione, consulta [Controllo degli accessi per invocare un'API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). Quando un'API è integrata con un AWS servizio (ad esempio AWS Lambda) nel backend, API Gateway deve disporre anche delle autorizzazioni per accedere a AWS risorse integrate (ad esempio, richiamando una funzione Lambda) per conto del chiamante dell'API. Per concedere queste autorizzazioni, crea un ruolo IAM del tipo **AWS service for API Gateway (Servizio AWS per API Gateway)**. Quando crei questo ruolo nella console di gestione IAM, tale ruolo contiene la policy di attendibilità IAM seguente, in base alla quale API Gateway viene dichiarato un'entità attendibile che può assumere quel ruolo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ Se crei il ruolo IAM chiamando il comando [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) della CLI o un metodo SDK corrispondente, devi fornire la policy di attendibilità precedente come parametro di input di `assume-role-policy-document`. Non tentate di creare tale policy direttamente nella console di gestione IAM o di chiamare il comando AWS CLI [create-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/create-policy.html) o un metodo SDK corrispondente. Affinché API Gateway richiami il AWS servizio integrato, devi anche associare a questo ruolo le politiche di autorizzazione IAM appropriate per la chiamata AWS ai servizi integrati. Ad esempio, per chiamare una funzione Lambda, devi includere la seguente policy di autorizzazione IAM nel ruolo IAM: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "lambda:InvokeFunction", "Resource": "*" } ] } ``` ------ Lambda supporta le policy di accesso basate su risorse, che combinano policy di autorizzazione e di attendibilità. Quando integri un'API con una funzione Lambda utilizzando la console API Gateway, non ti viene richiesto di impostare questo ruolo IAM esplicitamente, poiché la console imposta automaticamente con il tuo consenso le autorizzazioni basate su risorse sulla funzione Lambda. **Nota** Per implementare il controllo degli accessi a un AWS servizio, puoi utilizzare il modello di autorizzazioni basato sul chiamante, in cui una policy di autorizzazione è collegata direttamente all'utente o al gruppo del chiamante, oppure il modello di autorizzazione basato sui ruoli, in cui una policy di autorizzazioni è associata a un ruolo IAM che API Gateway può assumere. Le policy di autorizzazione possono differire nei due modelli. Ad esempio la policy basata su intermediario blocca l'accesso, mentre quella basata su ruolo lo consente. Puoi trarne vantaggio per richiedere che un utente acceda a un AWS servizio solo tramite un'API API Gateway. # Controllo degli accessi per invocare un'API In questa sezione viene illustrato il modello di autorizzazioni per controllare l'accesso all'API utilizzando le autorizzazioni IAM. Quando l'autorizzazione IAM è abilitata, i client devono utilizzare Signature Version 4a (SigV4a) e Signature Version 4 (SigV4) per firmare le loro richieste con credenziali. AWS Per ulteriori informazioni, consultare [AWS Signature Version 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html). Questa sezione illustra un modello di istruzione di policy IAM e il riferimento all’istruzione di policy. Il riferimento all'istruzione di policy include i formati dei campi `Action` e `Resource` correlati al servizio di esecuzione dell'API. Si utilizzano questi riferimenti per creare l'istruzione di policy IAM. Quando si crea l'istruzione di policy IAM, è opportuno a volte considerare il modo in cui le policy delle risorse Gateway API influiscono sul flusso di lavoro di autorizzazione. Per ulteriori informazioni, consulta [Come le policy delle risorse API Gateway influiscono sul flusso di lavoro delle autorizzazioni](apigateway-authorization-flow.md). Per uso privato APIs, è necessario utilizzare una combinazione di una policy per le risorse di API Gateway e una policy per gli endpoint VPC. Per ulteriori informazioni, consulta i seguenti argomenti: + [Controllo degli accessi a una REST API con le policy delle risorse Gateway API](apigateway-resource-policies.md) + [Usa le policy degli endpoint VPC per uso privato APIs in API Gateway](apigateway-vpc-endpoint-policies.md) ## Controllo di chi può chiamare un metodo API di API Gateway con le policy IAM Per controllare chi può o non può chiamare un'API distribuita con le autorizzazioni IAM, crea un documento di policy IAM con le autorizzazioni richieste. Di seguito viene mostrato un modello per questo tipo di documento di policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Permission", "Action": [ "execute-api:Execution-operation" ], "Resource": [ "arn:aws:execute-api:region:123456789012:api-id/stage/METHOD_HTTP_VERB/Resource-path" ] } ] } ``` ------ Nell'esempio riportato `Permission` deve essere sostituito da `Allow` o da `Deny` a seconda che si desideri concedere o revocare le autorizzazioni incluse. `Execution-operation` deve essere sostituito dalle operazioni supportate dal servizio di esecuzione dell'API. `METHOD_HTTP_VERB` indica un verbo HTTP supportato dalle risorse specificate. `Resource-path` è il segnaposto per il percorso URL dell'istanza `[Resource](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html)` di un'API distribuita che supporta l'elemento `METHOD_HTTP_VERB` citato. Per ulteriori informazioni, consulta [Riferimento delle istruzioni delle policy IAM per l'esecuzione dell'API in API Gateway](#api-gateway-calling-api-permissions). **Nota** Affinché le policy IAM diventino effettive, devi avere abilitato l'autenticazione IAM sui metodi API impostando `AWS_IAM` per la proprietà `[authorizationType](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#authorizationType)` del metodo. In caso contrario, questi metodi API saranno accessibili pubblicamente. Ad esempio, per concedere a un utente l'autorizzazione per visualizzare un elenco di animali domestici esposti tramite un'API specificata, rifiutandogli tuttavia l'autorizzazione per aggiungere un animale domestico all'elenco, è possibile includere nella policy IAM l'istruzione seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/GET/pets" ] }, { "Effect": "Deny", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/*/POST/pets" ] } ] } ``` ------ Per concedere a un utente l'autorizzazione per visualizzare un animale domestico specifico esposto da un'API configurata come `GET /pets/{petId}`, è possibile includere nella policy IAM l'istruzione seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:111122223333:api-id/*/GET/pets/a1b2" ] } ] } ``` ------ ## Riferimento delle istruzioni delle policy IAM per l'esecuzione dell'API in API Gateway Le informazioni seguenti descrivono il formato Action e Resource delle istruzioni di policy IAM per le autorizzazioni di accesso per l'esecuzione di un'API. ### Formato dell'elemento Action delle autorizzazioni per l'esecuzione dell'API in API Gateway Il formato generale dell'espressione `Action` di esecuzione dell'API è il seguente: ``` execute-api:action ``` dove *action* è disponibile un'azione di esecuzione dell'API: + **\$1**, che rappresenta tutte le operazioni che seguono. + **Invoke**, utilizzato per invocare un'API su richiesta del client. + **InvalidateCache**, utilizzato per invalidare la cache dell'API su richiesta del client. ### Formato dell'elemento Resource delle autorizzazioni per l'esecuzione dell'API in API Gateway Il formato generale dell'espressione `Resource` di esecuzione dell'API è il seguente: ``` arn:aws:execute-api:region:account-id:api-id/stage-name/HTTP-VERB/resource-path-specifier ``` dove: + *region*è la AWS regione (come **us-east-1** o **\$1** per tutte le AWS regioni) che corrisponde all'API distribuita per il metodo. + *account-id*è l'ID dell' AWS account a 12 cifre del proprietario dell'API REST. + *api-id*è l'identificatore che API Gateway ha assegnato all'API per il metodo. + *stage-name*è il nome dello stadio associato al metodo. + *HTTP-VERB*è il verbo HTTP per il metodo. Può essere uno dei seguenti: GET, POST, PUT, DELETE, PATCH. + *resource-path-specifier*è il percorso del metodo desiderato. **Nota** Se specifichi un carattere jolly (`*`), l'espressione `Resource` applica il carattere jolly al resto dell'espressione. Alcuni esempi dell'espressione Resource includono: + **arn:aws:execute-api:\$1:\$1:\$1**per qualsiasi percorso di risorsa in qualsiasi fase, per qualsiasi API in qualsiasi AWS regione. + **arn:aws:execute-api:us-east-1:\$1:\$1**per qualsiasi percorso di risorsa in qualsiasi fase, per qualsiasi API nella AWS regione di`us-east-1`. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/\$1**per qualsiasi percorso di risorsa in qualsiasi fase, per l'API con l'identificatore di *api-id* nella AWS regione us-east-1. + **arn:aws:execute-api:us-east-1:\$1:*api-id*/`test`/\$1**per qualsiasi percorso di risorsa nella fase di`test`, per l'API con l'identificatore di *api-id* nella AWS regione us-east-1. Per ulteriori informazioni, consulta [Documentazione di riferimento Amazon Resource Name (ARN) API Gateway](arn-format-reference.md). # Esempi di policy IAM per le autorizzazioni di esecuzione API Per informazioni sui modelli di autorizzazioni e per altre informazioni di base, consulta [Controllo degli accessi per invocare un'API](api-gateway-control-access-using-iam-policies-to-invoke-api.md). L'istruzione di policy seguente concede all'utente l'autorizzazione di chiamare qualsiasi metodo POST nel percorso `mydemoresource`, nella fase `test`, per l'API con l'identificatore `a123456789`, presupponendo che l'API corrispondente sia stata distribuita nella regione AWS us-east-1: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:us-east-1:*:a123456789/test/POST/my-demo-resource-path/*" ] } ] } ``` ------ L'istruzione di policy di esempio seguente concede all'utente l'autorizzazione di chiamare qualsiasi metodo nel percorso di risorsa `petstorewalkthrough/pets`, in qualsiasi fase, per l'API con l'identificativo `a123456789`, in qualsiasi regione AWS in cui è stata distribuita l'API corrispondente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:aws:execute-api:*:*:a123456789/*/*/petstorewalkthrough/pets" ] } ] } ``` ------ # Usa le policy degli endpoint VPC per uso privato APIs in API Gateway È possibile creare una policy di endpoint VPC per migliorare la sicurezza dell'API privata. Una policy di endpoint VPC è una policy delle risorse IAM che è possibile allegare all'endpoint VPC. Per ulteriori informazioni, consulta [Controllo dell'accesso ai servizi con endpoint VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). È possibile creare una policy di endpoint VPC per eseguire le seguenti attività. + Consentire solo a determinate organizzazioni o risorse di accedere all'endpoint VPC e invocare l'API. + Utilizzare un'unica policy ed evitare le policy basate sulla sessione o sul ruolo per controllare il traffico verso l'API. + Rafforza il perimetro di sicurezza della tua applicazione durante la migrazione da locale a. AWS ## Considerazioni sulla policy degli endpoint VPC Di seguito sono riportate alcune considerazioni sulla policy di endpoint VPC: + L'identità dell'invoker viene valutata in base al valore dell'intestazione `Authorization`. La policy di endpoint VPC viene valutata per prima, quindi Gateway API valuta la richiesta, in base al tipo di autorizzazione configurato nella richiesta di metodo. La tabella seguente mostra come viene valutata la policy di endpoint VPC in base al contenuto del valore dell’intestazione `Authorization`. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-vpc-endpoint-policies.html) + Se il controllo degli accessi dipende dall’utilizzo di un token di connessione, come un sistema di autorizzazione Lambda o Amazon Cognito, è possibile controllare il perimetro di sicurezza utilizzando le [proprietà della risorsa](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties). + Se i controlli di autorizzazione utilizzano l’autorizzazione IAM, è possibile controllare il perimetro di sicurezza utilizzando le [proprietà della risorsa](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-properties) e le [proprietà del principale](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-resource-principal). + Le policy di endpoint VPC possono essere utilizzate insieme alle policy di risorse API Gateway. La policy delle risorse Gateway API specifica quali principali possono accedere all'API. La policy dell'endpoint specifica chi può accedere al VPC e chi APIs può essere chiamato dall'endpoint VPC. L'API privata richiede una policy delle risorse, ma non è necessario creare una policy di endpoint VPC personalizzata. ## Esempi di policy di endpoint VPC È possibile creare le policy degli endpoint Amazon Virtual Private Cloud per Gateway Amazon API in cui specificare quanto segue. + Il principale che può eseguire azioni. + Le operazioni che possono essere eseguite. + Le risorse su cui è possibile eseguire le operazioni. Ciò potrebbe dipendere dal contenuto dell’intestazione dell’autorizzazione. Per ulteriori informazioni, consulta [Considerazioni sulla policy degli endpoint VPC](#apigateway-vpc-endpoint-policies-considerations). Per ulteriori esempi di policy, consulta [Data perimeter](https://github.com/aws-samples/data-perimeter-policy-examples) policy examples sul sito web. GitHub Per collegare la policy all'endpoint VPC, è necessario utilizzare la console VPC. Per ulteriori informazioni, consulta [Controllo dell'accesso ai servizi con endpoint VPC](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-access.html). ## Esempio 1: policy degli endpoint VPC che concede l'accesso a due APIs La seguente policy di esempio concede l'accesso solo a due specifici APIs tramite l'endpoint VPC a cui è associata la policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": "*", "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*", "arn:aws:execute-api:us-east-1:123412341234:aaaaa11111/*" ] } ] } ``` ------ ## Esempio 2: policy di endpoint VPC che concede l'accesso a metodi GET L'esempio di policy seguente concede agli utenti l'accesso ai metodi `GET` per un'API specifica tramite l'endpoint VPC a cui è collegata l'API. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": "*", "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/stageName/GET/*" ] } ] } ``` ------ ## Esempio 3: policy di endpoint VPC che concede a un utente specifico l'accesso a un'API specifica L'esempio di policy seguente concede a un utente specifico l'accesso a un'API specifica tramite l'endpoint VPC a cui è collegata la policy. In questo caso, poiché la policy limita l'accesso a specifici principali IAM, è necessario impostare il valore di `authorizationType` del metodo su `AWS_IAM` o `NONE`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Principal": { "AWS": [ "arn:aws:iam::123412341234:user/MyUser" ] }, "Action": [ "execute-api:Invoke" ], "Effect": "Allow", "Resource": [ "arn:aws:execute-api:us-east-1:123412341234:a1b2c3d4e5/*" ] } ] } ``` ------ ## Esempio 4: policy di endpoint VPC che fornisce agli utenti l'accesso a uno specifico nome di dominio personalizzato e a tutte le API mappate al dominio La seguente politica di esempio consente agli utenti di accedere a uno specifico nome di dominio personalizzato per uso privato APIs tramite l'endpoint VPC a cui è allegata la policy. Con questa politica, purché un utente abbia creato un'associazione di accesso al nome di dominio tra l'endpoint VPC e il nome di dominio personalizzato e gli sia concesso l'accesso per richiamare il nome di dominio personalizzato e qualsiasi API privata mappata al nome di dominio personalizzato, l'utente può richiamare qualsiasi APIs mappato su questo nome di dominio personalizzato. Per ulteriori informazioni, consulta [Nomi di dominio personalizzati per uso privato APIs in API Gateway](apigateway-private-custom-domains.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "*" ], "Condition": { "ArnEquals": { "execute-api:viaDomainArn": "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6", } } } ] } ``` ------ ## Esempio 5: policy degli endpoint VPC che concede o nega l'accesso a risorse specifiche e di dominio APIs La seguente politica di esempio concede agli utenti l'accesso a risorse specifiche e di dominio. APIs Con questa politica, purché un utente abbia creato un'associazione di accesso al nome di dominio tra l'endpoint VPC e il nome di dominio personalizzato e gli sia concesso l'accesso per richiamare il nome di dominio personalizzato e qualsiasi API privata mappata al nome di dominio personalizzato, l'utente può richiamare le risorse private e di dominio consentite. APIs Per ulteriori informazioni, consulta [Nomi di dominio personalizzati per uso privato APIs in API Gateway](apigateway-private-custom-domains.md). ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:/domainnames/private.test.com+f4g5h6", "arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/*" ] }, { "Effect": "Deny", "Principal": { "AWS": "*" }, "Action": "execute-api:Invoke", "Resource": [ "arn:aws:execute-api:us-west-2:111122223333:a1b2c3d4e5/admin/*", "arn:aws:execute-api:us-west-2:111122223333:bcd123455/*" ] } ] } ``` ------ ## Esempio 6: policy di endpoint VPC che fornisce o nega l’accesso a principali e risorse di un’organizzazione La seguente policy di esempio fornisce l’accesso ai principali e alle risorse di un’organizzazione. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Condition": { "StringEquals": { "aws:ResourceOrgID": "o-abcd1234", "aws:PrincipalOrgID": "o-abcd1234" } }, "Action": "*", "Resource": "*", "Effect": "Allow", "Principal": { "AWS": "*" }, "Sid": "AllowRequestsByOrgsIdentitiesToOrgsResources" } ] } ``` ------ # Usa i tag per controllare l'accesso a REST APIs in API Gateway L'autorizzazione ad accedere a REST APIs può essere ottimizzata utilizzando il controllo degli accessi basato sugli attributi nelle policy IAM. Per ulteriori informazioni, consulta [Utilizzo dei tag per controllare l'accesso alle risorse REST API di Gateway API](apigateway-tagging-iam-policy.md). # Uso di autorizzazioni Lambda di API Gateway Usa un *sistema di autorizzazione Lambda* (noto in precedenza come *sistema di autorizzazione ad hoc*) per controllare l'accesso all'API. Quando un client effettua una richiesta al metodo dell’API, Gateway API chiama il sistema di autorizzazione Lambda. Il sistema di autorizzazione Lambda accetta l'identità del chiamante come input e restituisce una policy IAM come output. Usa un sistema di autorizzazione Lambda per implementare uno schema di autorizzazione personalizzato. Il tuo schema può utilizzare i parametri di richiesta per determinare l'identità del chiamante o utilizzare una strategia di autenticazione con token portatore come OAuth o SAML. Crea un autorizzatore Lambda nella console API REST di API Gateway, utilizzando o un AWS CLI SDK. AWS ## Flusso di lavoro di autorizzazione per il sistema di autorizzazione Lambda Il diagramma seguente mostra il flusso di lavoro di autorizzazione per un sistema di autorizzazione Lambda. ![\[Flusso di lavoro per le autorizzazioni Lambda di API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/custom-auth-workflow.png) **Flusso di lavoro per le autorizzazioni Lambda di API Gateway** 1. Il client chiama un metodo in un'API di Gateway API, passando un token di connessione o i parametri della richiesta. 1. Gateway API verifica se la richiesta di metodo è configurata con un sistema di autorizzazione Lambda. In tal caso, API Gateway chiama la funzione Lambda. 1. La funzione Lambda autentica il chiamante. La funzione può eseguire l'autenticazione nei modi seguenti: + Chiamando un OAuth provider per ottenere un OAuth token di accesso. + Chiamando un provider SAML per ottenere un'asserzione SAML. + Generando una policy IAM in base ai valori dei parametri della richiesta. + Recuperando le credenziali da un database. 1. La funzione Lambda restituisce una policy IAM e un identificatore principale. Se la funzione Lambda non restituisce tali informazioni, la chiamata ha esito negativo. 1. Gateway API valuta la policy IAM. + Se l'accesso viene negato, Gateway API restituisce un codice di stato HTTP appropriato, ad esempio `403 ACCESS_DENIED`. + Se l'accesso viene concesso, Gateway API invoca il metodo. Se si abilita il caching delle autorizzazioni, Gateway API memorizza la policy nella cache in modo che non venga invocata nuovamente la funzione del sistema di autorizzazione Lambda. È necessario assicurarsi che la policy sia applicabile a tutte le risorse e ai metodi dell’API. È possibile personalizzare le risposte `403 ACCESS_DENIED` o `401 UNAUTHORIZED` del gateway. Per ulteriori informazioni, consulta [Risposte gateway per REST APIs in API Gateway](api-gateway-gatewayResponse-definition.md). ## Scelta di un tipo di sistema di autorizzazione Lambda Esistono due tipi di autorizzazioni Lambda: **Sistema di autorizzazione Lambda basato sui parametri della richiesta (sistema di autorizzazione `REQUEST`)** Un sistema di autorizzazione `REQUEST` riceve l'identità del chiamante in una combinazione di intestazioni, parametri della stringa di query, [`stageVariables`](api-gateway-mapping-template-reference.md#stagevariables-template-reference) e variabili [`$context`](api-gateway-mapping-template-reference.md#context-variable-reference). È possibile utilizzare un sistema di autorizzazione `REQUEST` per creare policy dettagliate in base a informazioni provenienti da più origini di identità, ad esempio le variabili di contesto `$context.path` e `$context.httpMethod`. Se attivi il caching delle autorizzazioni per un sistema di autorizzazione `REQUEST`, Gateway API verifica che nella richiesta siano presenti tutte le origini di identità specificate. Se un'origine di identità specificata non è presente, è null o è vuota, Gateway API restituisce una risposta HTTP `401 Unauthorized` senza chiamare la funzione del sistema di autorizzazione Lambda. Quando sono definite più origini di identità, vengono utilizzate tutte per derivare la chiave cache del sistema di autorizzazione, mantenendo l'ordine. È possibile definire una chiave di cache dettagliata utilizzando più origini di identità. Se modifichi qualsiasi parte della chiave di cache, il sistema di autorizzazione rimuove il documento di policy memorizzato nella cache e ne generano uno nuovo. Se disattivi il caching delle autorizzazioni per un sistema di autorizzazione `REQUEST`, Gateway API passa direttamente la richiesta alla funzione Lambda. **Sistema di autorizzazione Lambda basato su token (sistema di autorizzazione `TOKEN`)** Un `TOKEN` autorizzatore riceve l'identità del chiamante in un token portante, ad esempio un JSON Web Token (JWT) o un token. OAuth Se attivi il caching delle autorizzazioni per un sistema di autorizzazione `TOKEN`, il nome dell'intestazione specificato nell'origine token diventa la chiave di cache. Inoltre, puoi utilizzare la convalida dei token per inserire una dichiarazione. RegEx Gateway API esegue la convalida iniziale del token di input per l'espressione e, se la convalida ha esito positivo, invoca la funzione del sistema di autorizzazione Lambda. Ciò aiuta a ridurre le chiamate all'API. La proprietà `IdentityValidationExpression` è supportata solo per i sistemi di autorizzazione `TOKEN`. Per ulteriori informazioni, consulta [x-amazon-apigateway-authorizer oggetto](api-gateway-swagger-extensions-authorizer.md). **Nota** È consigliabile utilizzare un sistema di autorizzazione `REQUEST` per controllare l'accesso all'API. Puoi controllare l'accesso all'API in base a più origini di identità quando usi un sistema di autorizzazione `REQUEST` e in base a una singola origine di identità quando usi un sistema di autorizzazione `TOKEN`. Inoltre, puoi separare le chiavi di cache utilizzando più origini di identità per un sistema di autorizzazione `REQUEST`. ## Esempio di funzione del sistema di autorizzazione `REQUEST` Lambda Il codice di esempio seguente crea una funzione del sistema di autorizzazione Lambda che consente una richiesta se l'intestazione `HeaderAuth1` fornita dal client, il parametro di query `QueryString1` e la variabile di fase di `StageVar1` corrispondono, rispettivamente, ai valori specificati di `headerValue1`, `queryValue1` e `stageValue1`. ------ #### [ Node.js ] ``` // A simple request-based authorizer example to demonstrate how to use request // parameters to allow or deny a request. In this example, a request is // authorized if the client-supplied HeaderAuth1 header, QueryString1 // query parameter, and stage variable of StageVar1 all match // specified values of 'headerValue1', 'queryValue1', and 'stageValue1', // respectively. export const handler = function(event, context, callback) { console.log('Received event:', JSON.stringify(event, null, 2)); // Retrieve request parameters from the Lambda function input: var headers = event.headers; var queryStringParameters = event.queryStringParameters; var pathParameters = event.pathParameters; var stageVariables = event.stageVariables; // Parse the input for the parameter values var tmp = event.methodArn.split(':'); var apiGatewayArnTmp = tmp[5].split('/'); var awsAccountId = tmp[4]; var region = tmp[3]; var restApiId = apiGatewayArnTmp[0]; var stage = apiGatewayArnTmp[1]; var method = apiGatewayArnTmp[2]; var resource = '/'; // root resource if (apiGatewayArnTmp[3]) { resource += apiGatewayArnTmp[3]; } // Perform authorization to return the Allow policy for correct parameters and // the 'Unauthorized' error, otherwise. if (headers.HeaderAuth1 === "headerValue1" && queryStringParameters.QueryString1 === "queryValue1" && stageVariables.StageVar1 === "stageValue1") { callback(null, generateAllow('me', event.methodArn)); } else { callback(null, generateDeny('me', event.methodArn)); } } // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { // Required output: var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; // default version policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; // default action statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } var generateAllow = function(principalId, resource) { return generatePolicy(principalId, 'Allow', resource); } var generateDeny = function(principalId, resource) { return generatePolicy(principalId, 'Deny', resource); } ``` ------ #### [ Python ] ``` # A simple request-based authorizer example to demonstrate how to use request # parameters to allow or deny a request. In this example, a request is # authorized if the client-supplied headerauth1 header, QueryString1 # query parameter, and stage variable of StageVar1 all match # specified values of 'headerValue1', 'queryValue1', and 'stageValue1', # respectively. def lambda_handler(event, context): print(event) # Retrieve request parameters from the Lambda function input: headers = event['headers'] queryStringParameters = event['queryStringParameters'] pathParameters = event['pathParameters'] stageVariables = event['stageVariables'] # Parse the input for the parameter values tmp = event['methodArn'].split(':') apiGatewayArnTmp = tmp[5].split('/') awsAccountId = tmp[4] region = tmp[3] restApiId = apiGatewayArnTmp[0] stage = apiGatewayArnTmp[1] method = apiGatewayArnTmp[2] resource = '/' if (apiGatewayArnTmp[3]): resource += apiGatewayArnTmp[3] # Perform authorization to return the Allow policy for correct parameters # and the 'Unauthorized' error, otherwise. if (headers['HeaderAuth1'] == "headerValue1" and queryStringParameters['QueryString1'] == "queryValue1" and stageVariables['StageVar1'] == "stageValue1"): response = generateAllow('me', event['methodArn']) print('authorized') return response else: print('unauthorized') response = generateDeny('me', event['methodArn']) return response # Help function to generate IAM policy def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } return authResponse def generateAllow(principalId, resource): return generatePolicy(principalId, 'Allow', resource) def generateDeny(principalId, resource): return generatePolicy(principalId, 'Deny', resource) ``` ------ In questo esempio, la funzione di autorizzazione Lambda controlla i parametri di input e si comporta nel modo seguente: + Se tutti i valori dei parametri richiesti corrispondono ai valori previsti, la funzione di autorizzazione restituisce una risposta HTTP `200 OK` e una policy IAM simile alla seguente e la richiesta del metodo ha esito positivo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ + In caso contrario, la funzione del sistema di autorizzazione restituisce una risposta HTTP `401 Unauthorized` e la richiesta di metodo ha esito negativo. Oltre a restituire una policy IAM, la funzione di autorizzazione Lambda deve restituire anche l'identificatore dell'entità principale dell'intermediario. Facoltativamente, può restituire un oggetto `context` contenente informazioni aggiuntive che possono essere passate al backend di integrazione. Per ulteriori informazioni, consulta [Output da un sistema di autorizzazione Lambda di Gateway API](api-gateway-lambda-authorizer-output.md). Nel codice di produzione può essere necessario autenticare l'utente prima di concedere l'autorizzazione. Puoi aggiungere una logica di autenticazione nella funzione Lambda chiamando un provider di autenticazione come indicato nella documentazione del provider. ## Esempio di funzione del sistema di autorizzazione `TOKEN` Lambda Il codice di esempio seguente crea una funzione di autorizzazione `TOKEN` Lambda che consente a un chiamante di invocare un metodo se il valore del token fornito dal client è `allow`. Al chiamante non è consentito invocare la richiesta se il valore del token è `deny`. Se il valore del token è `unauthorized` o una stringa vuota, la funzione del sistema di autorizzazione restituisce una risposta `401 UNAUTHORIZED`. ------ #### [ Node.js ] ``` // A simple token-based authorizer example to demonstrate how to use an authorization token // to allow or deny a request. In this example, the caller named 'user' is allowed to invoke // a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke // the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty // string, the authorizer function returns an HTTP 401 status code. For any other token value, // the authorizer returns an HTTP 500 status code. // Note that token values are case-sensitive. export const handler = function(event, context, callback) { var token = event.authorizationToken; switch (token) { case 'allow': callback(null, generatePolicy('user', 'Allow', event.methodArn)); break; case 'deny': callback(null, generatePolicy('user', 'Deny', event.methodArn)); break; case 'unauthorized': callback("Unauthorized"); // Return a 401 Unauthorized response break; default: callback("Error: Invalid token"); // Return a 500 Invalid token response } }; // Help function to generate an IAM policy var generatePolicy = function(principalId, effect, resource) { var authResponse = {}; authResponse.principalId = principalId; if (effect && resource) { var policyDocument = {}; policyDocument.Version = '2012-10-17'; policyDocument.Statement = []; var statementOne = {}; statementOne.Action = 'execute-api:Invoke'; statementOne.Effect = effect; statementOne.Resource = resource; policyDocument.Statement[0] = statementOne; authResponse.policyDocument = policyDocument; } // Optional output with custom properties of the String, Number or Boolean type. authResponse.context = { "stringKey": "stringval", "numberKey": 123, "booleanKey": true }; return authResponse; } ``` ------ #### [ Python ] ``` # A simple token-based authorizer example to demonstrate how to use an authorization token # to allow or deny a request. In this example, the caller named 'user' is allowed to invoke # a request if the client-supplied token value is 'allow'. The caller is not allowed to invoke # the request if the token value is 'deny'. If the token value is 'unauthorized' or an empty # string, the authorizer function returns an HTTP 401 status code. For any other token value, # the authorizer returns an HTTP 500 status code. # Note that token values are case-sensitive. import json def lambda_handler(event, context): token = event['authorizationToken'] if token == 'allow': print('authorized') response = generatePolicy('user', 'Allow', event['methodArn']) elif token == 'deny': print('unauthorized') response = generatePolicy('user', 'Deny', event['methodArn']) elif token == 'unauthorized': print('unauthorized') raise Exception('Unauthorized') # Return a 401 Unauthorized response return 'unauthorized' try: return json.loads(response) except BaseException: print('unauthorized') return 'unauthorized' # Return a 500 error def generatePolicy(principalId, effect, resource): authResponse = {} authResponse['principalId'] = principalId if (effect and resource): policyDocument = {} policyDocument['Version'] = '2012-10-17' policyDocument['Statement'] = [] statementOne = {} statementOne['Action'] = 'execute-api:Invoke' statementOne['Effect'] = effect statementOne['Resource'] = resource policyDocument['Statement'] = [statementOne] authResponse['policyDocument'] = policyDocument authResponse['context'] = { "stringKey": "stringval", "numberKey": 123, "booleanKey": True } authResponse_JSON = json.dumps(authResponse) return authResponse_JSON ``` ------ In questo esempio, quando l'API riceve una richiesta del metodo, API Gateway passa il token di origine alla funzione di autorizzazione Lambda nell'attributo `event.authorizationToken`. La funzione di autorizzazione Lambda legge il token e si comporta nel modo seguente: + Se il valore del token è `allow`, la funzione di autorizzazione restituisce una risposta HTTP `200 OK` e una policy IAM simile alla seguente e la richiesta del metodo ha esito positivo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ + Se il valore del token è `deny`, la funzione di autorizzazione restituisce una risposta HTTP `200 OK` e una policy IAM `Deny` simile alla seguente e la richiesta del metodo ha esito negativo: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-east-1:123456789012:ivdtdhp7b5/ESTestInvoke-stage/GET/" } ] } ``` ------ **Nota** Esternamente all'ambiente di test, Gateway API restituisce una risposta HTTP `403 Forbidden` e la richiesta di metodo ha esito negativo. + Se il valore del token è `unauthorized` o una stringa vuota, la funzione del provider di autorizzazione restituisce una risposta HTTP `401 Unauthorized` e la chiamata al metodo ha esito negativo. + Se il token ha un valore diverso dai precedenti, il client riceve una risposta `500 Invalid token` e la chiamata al metodo ha esito negativo. Oltre a restituire una policy IAM, la funzione di autorizzazione Lambda deve restituire anche l'identificatore dell'entità principale dell'intermediario. Facoltativamente, può restituire un oggetto `context` contenente informazioni aggiuntive che possono essere passate al backend di integrazione. Per ulteriori informazioni, consulta [Output da un sistema di autorizzazione Lambda di Gateway API](api-gateway-lambda-authorizer-output.md). Nel codice di produzione può essere necessario autenticare l'utente prima di concedere l'autorizzazione. Puoi aggiungere una logica di autenticazione nella funzione Lambda chiamando un provider di autenticazione come indicato nella documentazione del provider. ## Esempi aggiuntivi di funzioni del sistema di autorizzazione Lambda L'elenco seguente mostra altri esempi di funzioni del sistema di autorizzazione Lambda. Puoi creare una funzione Lambda nello stesso account o in un account diverso da quello da cui hai creato l'API. Per l'esempio precedente di funzioni Lambda, puoi utilizzare le funzioni integrate [AWSLambdaBasicExecutionRole](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html), poiché queste funzioni non chiamano altri AWS servizi. Se la tua funzione Lambda chiama altri AWS servizi, dovrai assegnare un ruolo di esecuzione IAM alla funzione Lambda. Per creare il ruolo, segui le istruzioni in [AWS Lambda Ruolo di esecuzione](https://docs.aws.amazon.com/lambda/latest/dg/lambda-intro-execution-role.html). **Esempi aggiuntivi di funzioni del sistema di autorizzazione Lambda** + Per un esempio di applicazione, vedere [Open Banking Brasile - Esempi di autorizzazione](https://github.com/aws-samples/openbanking-brazilian-auth-samples) GitHub su. + Per altri esempi di funzioni Lambda, vedi [ aws-apigateway-lambda-authorizer-blueprints](https://github.com/awslabs/aws-apigateway-lambda-authorizer-blueprints) on. GitHub + Puoi creare un sistema di autorizzazione Lambda che autentica gli utenti utilizzando i pool di utenti di Amazon Cognito e autorizza i chiamanti in base a un archivio di policy utilizzando Autorizzazioni verificate. Per ulteriori informazioni, consulta [Controllo dell'accesso in base agli attributi di un'identità con Autorizzazioni verificate](apigateway-lambda-authorizer-verified-permissions.md). + La console Lambda fornisce un blueprint Python, che puoi usare scegliendo **Usa un blueprint e scegliendo il blueprint**. **api-gateway-authorizer-python** # Configurazione di un sistema di autorizzazione Lambda di Gateway API Dopo aver creato una funzione Lambda, configuri la funzione Lambda come sistema di autorizzazione per la tua API. Quindi configuri il metodo per invocare il sistema di autorizzazione Lambda per stabilire se un chiamante può invocare il tuo metodo. Puoi creare una funzione Lambda nello stesso account o in un account diverso da quello da cui hai creato l'API. Puoi testare il sistema di autorizzazione Lambda utilizzando gli strumenti integrati nella console Gateway API o utilizzando [Postman](https://www.postman.com/). Per istruzioni su come utilizzare Postman per testare la funzione del sistema di autorizzazione Lambda, consulta [Chiamata di un'API con il sistema di autorizzazione Lambda di Gateway API](call-api-with-api-gateway-lambda-authorization.md). ## Configurazione di un sistema di autorizzazione Lambda (console) La procedura seguente illustra come creare un sistema di autorizzazione Lambda nella console REST API di Gateway API. Per ulteriori informazioni sui diversi tipi di sistemi di autorizzazione Lambda, consulta [Scelta di un tipo di sistema di autorizzazione Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-choose). ------ #### [ REQUEST authorizer ] **Configurazione di un sistema di autorizzazione Lambda `REQUEST`** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona un'API, quindi scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. In **Nome del provider di autorizzazioni**, immetti il nome di un provider di autorizzazioni. 1. In **Tipo di autorizzazione**, seleziona **Lambda**. 1. Per la **funzione Lambda**, seleziona il Regione AWS luogo in cui hai creato la funzione di autorizzazione Lambda, quindi inserisci il nome della funzione. 1. Non specificare nulla in **Ruolo di richiamo Lambda** per consentire alla console REST API di Gateway API di impostare una policy basata sulle risorse. La policy concede a Gateway API le autorizzazioni per invocare la funzione del sistema di autorizzazione Lambda. Puoi anche scegliere di immettere il nome di un ruolo IAM per consentire a Gateway API di invocare la funzione del sistema di autorizzazione Lambda. Per un ruolo di esempio, consulta [Creazione di un ruolo IAM prevedibile](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies). 1. In **Payload evento Lambda**, scegli **Richiesta**. 1. In **Tipo di origine identità**, seleziona un tipo di parametro. I tipi di parametri supportati sono `Header`, `Query string`, `Stage variable` e `Context`. Per aggiungere altre origini di identità, scegli **Aggiungi parametro**. 1. Per memorizzare nella cache la policy di autorizzazione generata dalla funzione di autorizzazione, attiva l'opzione **Autorizzazione caching**. Quando il caching delle policy è abilitato, puoi modificare il valore **TTL**. L'impostazione dell'opzione **TTL** su zero disabilita la memorizzazione nella cache delle policy. Per abilitare il caching, il sistema di autorizzazione deve restituire una policy applicabile a tutti i metodi di un'API. Per applicare una policy specifica del metodo, utilizza le variabili di contesto `$context.path` e `$context.httpMethod`. 1. Scegli **Crea autorizzazioni**. ------ #### [ TOKEN authorizer ] **Configurazione di un sistema di autorizzazione Lambda `TOKEN`** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona un'API, quindi scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. In **Nome del provider di autorizzazioni**, immetti il nome di un provider di autorizzazioni. 1. In **Tipo di autorizzazione**, seleziona **Lambda**. 1. Per la **funzione Lambda**, seleziona il Regione AWS luogo in cui hai creato la funzione di autorizzazione Lambda, quindi inserisci il nome della funzione. 1. Non specificare nulla in **Ruolo di richiamo Lambda** per consentire alla console REST API di Gateway API di impostare una policy basata sulle risorse. La policy concede a Gateway API le autorizzazioni per invocare la funzione del sistema di autorizzazione Lambda. Puoi anche scegliere di immettere il nome di un ruolo IAM per consentire a Gateway API di invocare la funzione del sistema di autorizzazione Lambda. Per un ruolo di esempio, consulta [Creazione di un ruolo IAM prevedibile](integrating-api-with-aws-services-lambda.md#api-as-lambda-proxy-setup-iam-role-policies). 1. In **Payload evento Lambda**, scegli **Token**. 1. In **Origine token**, immetti il nome dell'intestazione contenente il token di autorizzazione. Il client API deve includere un'intestazione con questo nome per inviare il token di autorizzazione al sistema di autorizzazione Lambda. 1. (Facoltativo) Per la **convalida del token**, inserisci una dichiarazione. RegEx API Gateway esegue la convalida iniziale del token di input per l'espressione e, se la convalida ha esito positivo, richiama l'autorizzazione. 1. Per memorizzare nella cache la policy di autorizzazione generata dalla funzione di autorizzazione, attiva l'opzione **Autorizzazione caching**. Quando la memorizzazione della policy nella cache è abilitata, il nome dell'intestazione specificato in **Origine token** diventa la chiave della cache. Quando il caching delle policy è abilitato, puoi modificare il valore **TTL**. L'impostazione dell'opzione **TTL** su zero disabilita la memorizzazione nella cache delle policy. Per abilitare il caching, il sistema di autorizzazione deve restituire una policy applicabile a tutti i metodi di un'API. Per applicare policy specifiche del metodo, puoi disattivare l'opzione **Memorizzazione nella cache dell'autorizzazione**. 1. Scegli **Crea autorizzazioni**. ------ Dopo aver creato il sistema di autorizzazione Lambda, puoi testarlo. La procedura seguente illustra come testare il sistema di autorizzazione Lambda. ------ #### [ REQUEST authorizer ] **Per testare un sistema di autorizzazione Lambda `REQUEST`** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona il nome del sistema di autorizzazione. 1. In **Testa autorizzazioni**, inserisci un valore per la tua origine di identità. Se utilizzi [Esempio di funzione del sistema di autorizzazione `REQUEST` Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-request-lambda-function-create), procedi nel modo seguente: 1. Seleziona **Intestazione** e immetti **headerValue1**, quindi scegli **Aggiungi parametro**. 1. In **Tipo di origine identità**, seleziona **Stringa di query** e immetti **queryValue1**, quindi scegli **Aggiungi parametro**. 1. In **Tipo di origine identità**, seleziona **Variabile di fase** e immetti **stageValue1**. Non puoi modificare le variabili di contesto per l'invocazione di test, ma puoi modificare il modello di evento di test **Sistema di autorizzazione di Gateway API** per la tua funzione Lambda. Quindi, puoi testare la funzione del sistema di autorizzazione Lambda con variabili di contesto modificate. Per ulteriori informazioni, consulta [Testing Lambda functions in the console](https://docs.aws.amazon.com/lambda/latest/dg/testing-functions.html) nella *Guida per gli sviluppatori di AWS Lambda *. 1. Scegli **Testa autorizzazioni**. ------ #### [ TOKEN authorizer ] **Per testare un sistema di autorizzazione Lambda `TOKEN`** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona il nome del sistema di autorizzazione. 1. In **Testa autorizzazioni**, inserisci un valore per il token. Se utilizzi [Esempio di funzione del sistema di autorizzazione `TOKEN` Lambda](apigateway-use-lambda-authorizer.md#api-gateway-lambda-authorizer-token-lambda-function-create), procedi nel modo seguente: 1. Per **authorizationToken**, inserisci **allow**. 1. Scegli **Testa autorizzazioni**. Se il sistema di autorizzazione Lambda nega correttamente una richiesta nell'ambiente di test, il test restituisce una risposta HTTP `200 OK`. Esternamente all'ambiente di test, invece, Gateway API restituisce una risposta HTTP `403 Forbidden` e la richiesta di metodo ha esito negativo. ------ ## Configurazione di un sistema di autorizzazione Lambda (AWS CLI) Il seguente comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) mostra come creare un sistema di autorizzazione Lambda tramite AWS CLI. ------ #### [ REQUEST authorizer ] Il comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) seguente crea un sistema di autorizzazione `REQUEST` e utilizza l’intestazione `Authorizer` e la variabile di contesto `accountId` come origini di identità: ``` aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Request_Custom_Authorizer' \ --type REQUEST \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization,context.accountId' \ --authorizer-result-ttl-in-seconds 300 ``` ------ #### [ TOKEN authorizer ] Il comando [create-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-authorizer.html) seguente crea un sistema di autorizzazione `TOKEN` e utilizza l’intestazione `Authorization` come origine di identità: ``` aws apigateway create-authorizer \ --rest-api-id 1234123412 \ --name 'First_Token_Custom_Authorizer' \ --type TOKEN \ --authorizer-uri 'arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123412341234:function:customAuthFunction/invocations' \ --identity-source 'method.request.header.Authorization' \ --authorizer-result-ttl-in-seconds 300 ``` ------ Dopo aver creato il sistema di autorizzazione Lambda, puoi testarlo. Il [test-invoke-authorizer](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-authorizer.html)comando seguente verifica un autorizzatore Lambda: ``` aws apigateway test-invoke-authorizer --rest-api-id 1234123412 \ --authorizer-id efg1234 \ --headers Authorization='Value' ``` ## Configurazione di un metodo per utilizzare un sistema di autorizzazione Lambda (console) Dopo aver configurato il sistema di autorizzazione Lambda, devi collegarlo a un metodo per l'API. Se il sistema di autorizzazione utilizza il caching delle autorizzazioni, è necessario aggiornare la policy per controllare l’accesso del metodo aggiuntivo. **Configurazione di un metodo API per utilizzare le autorizzazioni Lambda** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona un'API. 1. Seleziona **Risorse**, quindi scegli un nuovo metodo o scegline uno esistente. 1. Nella scheda **Richiesta metodo**, in **Impostazioni richiesta metodo**, scegli **Modifica**. 1. In **Autorizzazioni**, nel menu a discesa, seleziona la funzione di autorizzazione Lambda appena creata. 1. (Facoltativo) Se desideri passare il token di autorizzazione al back-end, scegli **Intestazioni di richiesta HTTP**. Scegli **Aggiungi intestazione**, quindi aggiungi il nome dell'intestazione di autorizzazione. In **Nome** immetti il nome dell'intestazione corrispondente al nome specificato in **Origine token** al momento della creazione della funzione di autorizzazione Lambda per l'API. Questo passaggio non si applica alle autorizzazioni `REQUEST`. 1. Scegli **Save** (Salva). 1. Seleziona **Deploy API (Distribuisci API)** per distribuire l'API in una fase. Per una funzione di autorizzazione basata su `REQUEST` che usa variabili di fase, devi anche definire le variabili di fase richieste e specificare i relativi valori in **Fasi**. ## Configurazione di un metodo per utilizzare un sistema di autorizzazione Lambda (AWS CLI) Dopo aver configurato il sistema di autorizzazione Lambda, devi collegarlo a un metodo per l'API. Puoi creare un nuovo metodo o utilizzare un'operazione di patch per collegare un sistema di autorizzazione a un metodo esistente. Se il sistema di autorizzazione utilizza il caching delle autorizzazioni, è necessario aggiornare la policy per controllare l’accesso del metodo aggiuntivo. Il comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) seguente crea un nuovo metodo che utilizza un sistema di autorizzazione Lambda: ``` aws apigateway put-method --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --authorization-type CUSTOM \ --authorizer-id efg1234 ``` Il comando [update-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-method.html) seguente aggiorna un metodo esistente in modo da utilizzare un sistema di autorizzazione Lambda: ``` aws apigateway update-method \ --rest-api-id 1234123412 \ --resource-id a1b2c3 \ --http-method PUT \ --patch-operations op="replace",path="/authorizationType",value="CUSTOM" op="replace",path="/authorizerId",value="efg1234" ``` # Input per un sistema di autorizzazione Lambda di Gateway API La sezione seguente illustra il formato di input da Gateway API a un sistema di autorizzazione Lambda. ## Formato di input `TOKEN` Per l'autorizzazione Lambda (nota in precedenza come autorizzazione ad hoc) di tipo `TOKEN`, devi specificare un'intestazione personalizzata in **Token Source (Origine token)** al momento della configurazione dell'autorizzazione per l'API. Il client API deve passare il token di autorizzazione richiesto nell'intestazione nella richiesta in ingresso. Quando riceve la richiesta del metodo in entrata, API Gateway estrae il token dall'intestazione personalizzata. Passa quindi il token come proprietà `authorizationToken` dell'oggetto `event` della funzione Lambda, in aggiunta all'ARN del metodo come proprietà `methodArn`: ``` { "type":"TOKEN", "authorizationToken":"{caller-supplied-token}",     "methodArn":"arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ``` In questo esempio la proprietà `type` specifica il tipo di autorizzazioni, ovvero `TOKEN`. L'oggetto `{caller-supplied-token}` deriva dall'intestazione di autorizzazioni in una richiesta client e può essere qualsiasi valore di stringa. `methodArn` è l'ARN della richiesta del metodo in entrata e viene popolato da API Gateway in base alla configurazione dell'autorizzazione Lambda. ## Formato di input `REQUEST` Per un'autorizzazione per Lambda di tipo `REQUEST`, API Gateway passa i parametri della richiesta alla funzione di autorizzazione Lambda come parte dell'oggetto `event`. I parametri della richiesta includono intestazioni, parametri di percorso, parametri della stringa di query, variabili di fase e alcune variabili di contesto della richiesta. L'autore della chiamata API può impostare parametri di percorso, intestazioni e parametri della stringa di query. Lo sviluppatore dell'API deve impostare le variabili di fase durante la distribuzione dell'API e API Gateway fornisce il contesto della richiesta in fase di runtime. **Nota** I parametri di percorso possono essere passati come parametri della richiesta alla funzione di autorizzazione Lambda, ma non possono essere utilizzati come origini di identità. L'esempio seguente mostra un input per le autorizzazioni `REQUEST` per un metodo API (`GET /request`) con integrazione proxy: ``` { "type": "REQUEST", "methodArn": "arn:aws:execute-api:us-east-1:123456789012:abcdef123/test/GET/request", "resource": "/request", "path": "/request", "httpMethod": "GET", "headers": { "X-AMZ-Date": "20170718T062915Z", "Accept": "*/*", "HeaderAuth1": "headerValue1", "CloudFront-Viewer-Country": "US", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Is-Mobile-Viewer": "false", "User-Agent": "..." }, "queryStringParameters": { "QueryString1": "queryValue1" }, "pathParameters": {}, "stageVariables": { "StageVar1": "stageValue1" }, "requestContext": { "path": "/request", "accountId": "123456789012", "resourceId": "05c7jb", "stage": "test", "requestId": "...", "identity": { "apiKey": "...", "sourceIp": "...", "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "resourcePath": "/request", "httpMethod": "GET", "apiId": "abcdef123" } } ``` `requestContext` è una mappa di coppie chiave/valore e corrisponde alla variabile [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference). Il suo risultato dipende dall'API. Gateway API potrebbe aggiungere nuove chiavi alla mappa. Per ulteriori informazioni sull'input della funzione Lambda nell'integrazione proxy Lambda, consulta [Formato di input di una funzione Lambda per l'integrazione proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). # Output da un sistema di autorizzazione Lambda di Gateway API L'output di una funzione di autorizzazione Lambda è un oggetto simile a un dizionario che deve includere l'identificatore dell'entità principale (`principalId`) e un documento di policy (`policyDocument`) contenente un elenco di dichiarazioni di policy. L'output può includere anche una mappa `context` contenente coppie chiave-valore. Se l'API utilizza un piano di utilizzo ([https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apiKeySource) è impostato su `AUTHORIZER`), la funzione di autorizzazione Lambda deve restituire una delle chiavi API del piano di utilizzo come il valore della proprietà `usageIdentifierKey`. Di seguito è illustrato un esempio di output. ------ #### [ JSON ] **** ``` {   "principalId": "yyyyyyyy", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Allow|Deny", "Resource": "arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]" } ] }, "context": { "stringKey": "value", "numberKey": "1", "booleanKey": "true" }, "usageIdentifierKey": "{api-key}" } ``` ------ In questo caso, una dichiarazione di policy specifica se permettere o rifiutare (`Effect`) al servizio di esecuzione API Gateway di richiamare (`Action`) il metodo API specificato (`Resource`). Potrebbe essere necessario controllare l’accesso a più risorse in base al sistema di autorizzazione. Per specificare un tipo di risorsa (metodo), è possibile usare un carattere jolly (`*`). Per informazioni sull'impostazione di policy valide per chiamare un'API, consulta [Riferimento delle istruzioni delle policy IAM per l'esecuzione dell'API in API Gateway](api-gateway-control-access-using-iam-policies-to-invoke-api.md#api-gateway-calling-api-permissions). Per un ARN di metodo abilitato per le autorizzazioni, ad esempio `arn:aws:execute-api:{regionId}:{accountId}:{apiId}/{stage}/{httpVerb}/[{resource}/[{child-resources}]]`, la lunghezza massima è 1600 byte. A causa dei valori dei parametri del percorso, la cui dimensione viene determinata al momento dell'esecuzione, l'ARN può superare il limite di lunghezza impostato. In questo caso, il client API riceverà una risposta `414 Request URI too long`. Per l'ARN di risorsa, inoltre, come illustrato nell'output della dichiarazione di policy da parte delle autorizzazioni, è attualmente previsto un limite di 512 caratteri. Per questo motivo, non devi usare un URI con un token JWT di lunghezza significativa in un URI di richiesta. Puoi invece passare senza problemi il token JWT in un'intestazione di richiesta. Puoi accedere al valore di `principalId` in un modello di mappatura usando la variabile `$context.authorizer.principalId`. Ciò è utile se desideri passare il valore al back-end. Per ulteriori informazioni, consulta [Variabili di contesto per le trasformazioni dei dati](api-gateway-mapping-template-reference.md#context-variable-reference). Puoi accedere al valore di `stringKey`, `numberKey` o `booleanKey` (ad esempio `"value"`, `"1"` o `"true"`) della mappa `context` in un modello di mappatura chiamando, rispettivamente, `$context.authorizer.stringKey`, `$context.authorizer.numberKey` o `$context.authorizer.booleanKey`. I valori restituiti sono tutti in formato stringa. Non è possibile impostare una matrice o un oggetto JSON come valore valido di una chiave nella mappa `context`. È possibile usare la mappa `context` per restituire le credenziali memorizzate nella cache dalle autorizzazioni al back-end, usando un modello di mappatura di richiesta di integrazione. In questo modo, il back-end può offrire un'esperienza utente migliore usando le credenziali memorizzate nella cache per ridurre la necessità di accesso alle chiavi segrete e di apertura dei token di autorizzazione per ogni richiesta. Per l'integrazione proxy Lambda, API Gateway passa l'oggetto `context` da un'autorizzazione Lambda direttamente alla funzione Lambda back-end come parte dell'input `event`. È possibile recuperare la coppia chiave/valore `context` nella funzione Lambda chiamando `$event.requestContext.authorizer.key`. `{api-key}` indica una chiave API nel piano di utilizzo della fase API. Per ulteriori informazioni, consulta [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md). Di seguito è illustrato l'output dell'autorizzazione Lambda di esempio. L'output di esempio contiene un'istruzione politica per bloccare (`Deny`) le chiamate al `GET` metodo per la `dev` fase di un'API (`ymy8tbxw7b`) di un AWS account (). `123456789012` ------ #### [ JSON ] **** ``` { "principalId": "user", "policyDocument": { "Version":"2012-10-17", "Statement": [ { "Action": "execute-api:Invoke", "Effect": "Deny", "Resource": "arn:aws:execute-api:us-west-2:123456789012:ymy8tbxw7b/dev/GET/" } ] } } ``` ------ # Chiamata di un'API con il sistema di autorizzazione Lambda di Gateway API Dopo aver configurato l'autorizzazione Lambda (nota in precedenza come autorizzazione ad hoc) e aver distribuito l'API, devi testare l'API con l'autorizzazione Lambda abilitata. A tale scopo, è necessario un client REST, ad esempio cURL o [Postman](https://www.postman.com/). Per gli esempi seguenti usiamo Postman. **Nota** **Quando si chiama un metodo abilitato all'autorizzazione, API Gateway non registra la chiamata CloudWatch se il token richiesto per l'`TOKEN`autorizzatore non è impostato, è nullo o è invalidato dall'espressione di convalida Token specificata.** Allo stesso modo, API Gateway non registra la chiamata CloudWatch se una delle fonti di identità richieste per l'`REQUEST`autorizzatore non è impostata, è nulla o è vuota. Di seguito viene illustrato come usare Postman per chiamare o testare un'API con l'autorizzazione Lambda `TOKEN`. Il metodo può essere applicato alla chiamata a un'API con l'autorizzazione Lambda `REQUEST` specificando in modo esplicito i parametri di stringa di query, percorso o intestazione richiesti. **Per chiamare un'API con autorizzazioni ad hoc `TOKEN`** 1. Apri **Postman**, scegli il metodo **GET** e incolla il valore di **Invoke URL (URL chiamata)** dell'API nel campo URL adiacente. Aggiungi l'intestazione del token di autorizzazione Lambda e imposta il valore su `allow`. Scegliere **Send (Invia)**. ![\[Chiamata di un'API con il token di autorizzazione Lambda allow\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/custom-auth-call-api-with-allow-token.png) Come illustrato, l'autorizzazione Lambda di API Gateway restituisce una risposta **200 OK** e autorizza la chiamata per l'accesso all'endpoint HTTP (http://httpbin.org/get) integrato con il metodo. 1. Sempre in Postman, modifica il valore dell'intestazione del token di autorizzazione Lambda impostandolo su `deny`. Scegliere **Send (Invia)**. ![\[Chiamata di un'API con il token di autorizzazione Lambda Deny\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/custom-auth-call-api-with-deny-token.png) La risposta mostra che l'autorizzazione Lambda di API Gateway restituisce una risposta **403 Forbidden (403 Non consentito)** senza autorizzare la chiamata per l'accesso all'endpoint HTTP. 1. In Postman, modifica il valore dell'intestazione del token di autorizzazione Lambda impostandolo su `unauthorized` e seleziona **Send (Invia)**. ![\[Chiamata di un'API con il token di autorizzazione Lambda unauthorized\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/custom-auth-call-api-with-unauthorized-token.png) La risposta indica che API Gateway restituisce una risposta **401 Unauthorized (401 Non autorizzato)** senza autorizzare la chiamata per l'accesso all'endpoint HTTP. 1. Modifica quindi il valore dell'intestazione del token di autorizzazione Lambda impostandolo su `fail`. Scegliere **Send (Invia)**. ![\[Chiamata di un'API con il token di autorizzazione Lambda fail\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/custom-auth-call-api-with-fail-token.png) La risposta indica che API Gateway restituisce una risposta **500 Internal Server Error (500 Errore interno del server)** senza autorizzare la chiamata per l'accesso all'endpoint HTTP. # Configurazione di un sistema di autorizzazione Lambda di Gateway API multi-account Ora puoi anche utilizzare una AWS Lambda funzione di un altro AWS account come funzione di autorizzazione dell'API. Ogni account può trovarsi in qualsiasi regione in cui è disponibile Amazon API Gateway. La funzione di autorizzazione Lambda può utilizzare strategie di autenticazione con token portatori come o SAML. OAuth Ciò semplifica la gestione e la condivisione centralizzate di una funzione di autorizzazione Lambda centrale su più API Gateway. APIs In questa sezione, viene illustrato come configurare un'autorizzazione Lambda tra account tramite la console Amazon API Gateway. Queste istruzioni presuppongono che tu abbia già un'API API Gateway in un AWS account e una funzione di autorizzazione Lambda in un altro account. ## Configurazione di un'autorizzazione Lambda tra account tramite la console API Gateway Accedi alla console Gateway Amazon API con l'account contenente la tua API e quindi procedi come descritto di seguito: 1. Scegli la tua API, quindi nel pannello di navigazione principale, scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. In **Nome del provider di autorizzazioni**, immetti il nome di un provider di autorizzazioni. 1. In **Tipo di autorizzazione**, seleziona **Lambda**. 1. In **Funzione Lambda**, copia e incolla l'ARN completo della funzione di autorizzazione Lambda nel secondo account. **Nota** Nella console Lambda, puoi trovare l'ARN della funzione nell'angolo in alto a destra. 1. Verrà visualizzato un avviso con una stringa del comando `aws lambda add-permission`. La policy concede a Gateway API l'autorizzazione per richiamare la funzione di autorizzazione Lambda. Copiare il comando e salvarlo per un secondo momento. È possibile eseguire il comando dopo aver creato l'autorizzatore. 1. In **Payload evento Lambda**, scegli **Token** per una funzione di autorizzazione basata su `TOKEN` o **Richiesta** per una funzione di autorizzazione basata su `REQUEST`. 1. A seconda dell'opzione scelta in precedenza, esegui una di queste operazioni: 1. Per l'opzione **Token** esegui le operazioni indicate di seguito: + In **Origine token**, immetti il nome dell'intestazione contenente il token di autorizzazione. Il client API deve includere un'intestazione con questo nome per inviare il token di autorizzazione all'autorizzazione Lambda. + Facoltativamente, per la **convalida del token**, inserisci una dichiarazione. RegEx API Gateway esegue la convalida iniziale del token di input per l'espressione e, se la convalida ha esito positivo, richiama l'autorizzazione. Ciò aiuta a ridurre le chiamate all'API. + Per memorizzare nella cache la policy di autorizzazione generata dalla funzione di autorizzazione, attiva l'opzione **Autorizzazione caching**. Quando la memorizzazione nella cache delle policy è abilitata, è possibile scegliere di modificare il valore **TTL**. L'impostazione dell'opzione **TTL** su zero disabilita la memorizzazione nella cache delle policy. Quando la memorizzazione della policy nella cache è abilitata, il nome dell'intestazione specificato in **Origine token** diventa la chiave della cache. Se nella richiesta vengono passati più valori a questa intestazione, tutti i valori diventeranno la chiave della cache, con l'ordine mantenuto. **Nota** Il valore **TTL** predefinito è 300 secondi. Il valore massimo è 3600 secondi e non è possibile aumentare questo limite. 1. Per l'opzione **Request (Richiesta)**, esegui queste operazioni: + In **Tipo di origine identità**, seleziona un tipo di parametro. I tipi di parametri supportati sono `Header`, `Query string`, `Stage variable` e `Context`. Per aggiungere altre origini di identità, scegli **Aggiungi parametro**. + Per memorizzare nella cache la policy di autorizzazione generata dalla funzione di autorizzazione, attiva l'opzione **Autorizzazione caching**. Quando la memorizzazione nella cache delle policy è abilitata, è possibile scegliere di modificare il valore **TTL**. L'impostazione dell'opzione **TTL** su zero disabilita la memorizzazione nella cache delle policy. API Gateway usa le origini di identità specificate come chiave di caching delle autorizzazioni della richiesta. Quando il caching è abilitato, API Gateway chiama la funzione di autorizzazione Lambda solo dopo aver verificato che tutte le origini di identità specificate siano presenti in fase di runtime. Se un’origine di identità specificata non è presente, è null o è vuota, Gateway API restituisce una risposta `401 Unauthorized` senza chiamare la funzione Lambda del sistema di autorizzazione. Quando sono definite più origini di identità, vengono utilizzate tutte per derivare la chiave cache delle autorizzazioni. Se vengono modificate parti della chiave cache, le autorizzazioni rimuovono il documento di policy memorizzato nella cache e ne generano uno nuovo. Se nella richiesta viene passata un'intestazione con più valori, tutti i valori diventeranno la chiave della cache, con l'ordine mantenuto. + Quando la memorizzazione nella cache è disattivata, non è necessario specificare un'origine di identità. **Nota** Per abilitare il caching, le autorizzazioni devono restituire una policy applicabile a tutti i metodi di un'API. Per applicare policy specifiche del metodo, puoi disattivare l'opzione **Autorizzazione caching**. 1. Scegli **Crea autorizzazioni**. 1. Incolla la stringa di `aws lambda add-permission` comando che hai copiato nel passaggio precedente in una AWS CLI finestra configurata per il tuo secondo account. Sostituire `AUTHORIZER_ID` con l'ID del proprio autorizzatore. In questo modo, al primo account verrà concesso l'accesso alla funzione di autorizzazione Lambda del secondo account. # Controllo dell'accesso in base agli attributi di un'identità con Autorizzazioni verificate Utilizza Autorizzazioni verificate da Amazon per controllare l'accesso alla tua API di Gateway API. Quando utilizzi Gateway API con Autorizzazioni verificate, Autorizzazioni verificate crea un sistema di autorizzazione Lambda che utilizza decisioni di autorizzazione granulari per controllare l'accesso alla tua API. Autorizzazioni verificate autorizza i chiamanti sulla base di uno schema di archivio di policy e di policy che utilizzano il linguaggio di policy Cedar per definire autorizzazioni granulari per gli utenti dell'applicazione. Per ulteriori informazioni, consulta [Creare un archivio di policy con un'API e un provider di identità connessi](https://docs.aws.amazon.com/verifiedpermissions/latest/userguide/getting-started-api-policy-store.html) nella *Guida per l'utente di Autorizzazioni verificate da Amazon*. Autorizzazioni verificate supporta i pool di utenti di Amazon Cognito o i provider di identità OpenID Connect (OIDC) come origini di identità. Autorizzazioni verificate presuppone che il principale sia stato precedentemente identificato e autenticato. Le autorizzazioni verificate sono supportate solo per REST regionali e ottimizzate per i dispositivi periferici. APIs ## Creazione di un sistema di autorizzazione Lambda con Autorizzazioni verificate Autorizzazioni verificate crea un sistema di autorizzazione Lambda per determinare se un principale è autorizzato a eseguire un'operazione sulla tua API. La policy Cedar utilizzata da Autorizzazioni verificate per eseguire le sue attività di autorizzazione viene creata da te. Di seguito è riportato un esempio di policy Cedar che consente l'accesso per invocare un'API in base al pool di utenti di Amazon Cognito`us-east-1_ABC1234`, per il gruppo `developer` sulla risorsa `GET /users` di un'API. Autorizzazioni verificate determina l'appartenenza al gruppo analizzando l'identità del chiamante nel token di connessione. ``` permit( principal in MyAPI::UserGroup::"us-east-1_ABC1234|developer", action in [ MyAPI::Action::"get /users" ], resource ); ``` Facoltativamente, Autorizzazioni verificate può collegare il sistema di autorizzazione ai metodi dell'API. Nelle fasi di produzione dell'API, è consigliabile non consentire ad Autorizzazioni verificate di collegare automaticamente il sistema di autorizzazione. L'elenco seguente mostra come configurare Autorizzazioni verificate per collegare o non collegare il sistema di autorizzazione Lambda alla richiesta di metodo dei metodi dell'API. **Sistema di autorizzazione collegato automaticamente (Console di gestione AWS)** Quando scegli **Crea archivio di policy** nella console Autorizzazioni verificate, nella pagina **Implementa integrazione app** scegli **Ora**. **Sistema di autorizzazione non collegato automaticamente (Console di gestione AWS)** Quando scegli **Crea archivio di policy** nella console Autorizzazioni verificate, nella pagina **Implementa integrazione app** scegli **Più tardi**. Autorizzazioni verificate crea comunque automaticamente un sistema di autorizzazione Lambda. Il sistema di autorizzazione Lambda inizia con `AVPAuthorizerLambda-`. Per ulteriori indicazioni su come collegare il sistema di autorizzazione per un metodo, consulta [Configurazione di un metodo per utilizzare un sistema di autorizzazione Lambda (console)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-console). **Sistema di autorizzazione collegato automaticamente (CloudFormation)** Nel CloudFormation modello generato da Autorizzazioni verificate, nella sezione, imposta su. `Conditions` `"Ref": "shouldAttachAuthorizer"` `true` **Sistema di autorizzazione non collegato automaticamente (CloudFormation)** Nel CloudFormation modello generato da Autorizzazioni verificate, nella sezione, imposta su. `Conditions` `"Ref": "shouldAttachAuthorizer"` `false` Autorizzazioni verificate crea comunque automaticamente un sistema di autorizzazione Lambda. Il sistema di autorizzazione Lambda inizia con `AVPAuthorizerLambda-`. Per ulteriori indicazioni su come collegare il sistema di autorizzazione per un metodo, consulta [Configurazione di un metodo per utilizzare un sistema di autorizzazione Lambda (AWS CLI)](configure-api-gateway-lambda-authorization.md#configure-api-gateway-lambda-authorization-method-cli). ## Chiamata di un sistema di autorizzazione Lambda con Autorizzazioni verificate Puoi chiamare il tuo sistema di autorizzazione Lambda specificando un'identità o un token di accesso nell'intestazione `Authorization`. Per ulteriori informazioni, consulta [Chiamata di un'API con il sistema di autorizzazione Lambda di Gateway API](call-api-with-api-gateway-lambda-authorization.md). Gateway API memorizza nella cache la policy restituita dal sistema di autorizzazione Lambda per 120 secondi. È possibile modificare il TTL nella console Gateway API o tramite AWS CLI. # Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore In alternativa all'utilizzo di [ruoli e policy IAM](permissions.md) o [autorizzazioni Lambda](apigateway-use-lambda-authorizer.md) (note in precedenza come autorizzazioni ad hoc), puoi utilizzare un [pool di utenti di Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-identity-pools.html) per controllare chi può accedere all'API in Amazon API Gateway. Per usare un pool di utenti di Amazon Cognito con l'API, devi prima creare l'autorizzazione di tipo `COGNITO_USER_POOLS` e quindi configurare un metodo API per usare tale autorizzazione. Una volta distribuita l'API, il client deve innanzitutto registrare l'utente nel pool di utenti, ottenere un [token di identità o di accesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) per l'utente e quindi chiamare il metodo API con uno dei token, che sono in genere impostati sull'intestazione `Authorization` della richiesta. La chiamata API riesce solo se viene fornito il token necessario e se questo è valido. In caso contrario, il client non è autorizzato ad effettuare la chiamata perché non ha credenziali che è stato possibile autorizzare. Il token di identità viene usato per autorizzare chiamate API in base alle richieste di identità dell'utente connesso. Il token di accesso viene usato per autorizzare chiamate API in base agli ambiti personalizzati di risorse con accesso protetto specificate. Per ulteriori informazioni, consulta [Utilizzo di token con pool di utenti](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) e la pagina relativa a [server di risorse e ambiti personalizzati](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Per creare e configurare un pool di utenti di Amazon Cognito per l'API, esegui le attività seguenti: + Usa la console Amazon Cognito, CLI/SDK o API per creare un pool di utenti o usane uno di proprietà di un altro account. AWS + Usa la console, l'interfaccia a riga di comando/SDK o l'API di API Gateway, per creare autorizzazioni API Gateway con il pool di utenti scelto. + Usa la console, l'interfaccia a riga di comando/SDK o l'API di API Gateway, per abilitare le autorizzazioni per i metodi API selezionati. Per chiamare qualsiasi metodo API con un pool di utenti abilitato, i client API eseguono le attività seguenti: + Usa Amazon Cognito CLI/SDK o l'API per far accedere un utente al pool di utenti scelto e ottenere un token di identità o un token di accesso. Per ulteriori informazioni sull'utilizzo di SDKs, consulta [Esempi di codice per l'utilizzo di Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/service_code_examples.html). AWS SDKs + Utilizzano un framework specifico del client per chiamare l'API di API Gateway distribuita e specificare il token appropriato nell'intestazione `Authorization`. In quanto sviluppatore dell'API, devi fornire agli sviluppatori client l'ID pool di utenti, un ID client e possibilmente i segreti client definiti come parte del pool di utenti. **Nota** Per permettere a un utente di accedere usando credenziali Amazon Cognito e anche di ottenere credenziali temporanee da usare con le autorizzazioni di un ruolo IAM, usa [identità federate di Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html). Per ogni metodo HTTP dell'endpoint della risorsa API, imposta il tipo di autorizzazione, la categoria `Method Execution`, su `AWS_IAM`. In questa sezione descriveremo come creare un pool di utenti, come integrare un'API di API Gateway con il pool di utenti e come richiamare un'API integrata con il pool di utenti. **Topics** + [Creazione di un pool di utenti di Amazon Cognito per un'API REST](apigateway-create-cognito-user-pool.md) + [Integrazione di un'API REST con un pool di utenti di Amazon Cognito](apigateway-enable-cognito-user-pool.md) + [Chiamata di un'API REST integrata con un pool di utenti di Amazon Cognito](apigateway-invoke-api-integrated-with-cognito-user-pool.md) + [Configurazione dell'autorizzazione Amazon Cognito tra account per un'API REST tramite la console API Gateway](apigateway-cross-account-cognito-authorizer.md) + [Crea un autorizzatore Amazon Cognito per un'API REST utilizzando CloudFormation](apigateway-cognito-authorizer-cfn.md) # Creazione di un pool di utenti di Amazon Cognito per un'API REST Prima di integrare l'API con un pool di utenti, devi creare il pool di utenti in Amazon Cognito. La configurazione del pool di utenti deve rispettare tutte le [quote di risorse per Amazon Cognito](https://docs.aws.amazon.com/cognito/latest/developerguide/limits.html). Tutte le variabili Amazon Cognito definite dall'utente, come gruppi, utenti e ruoli, devono utilizzare solo caratteri alfanumerici. Per istruzioni su come creare un pool di utenti, consulta [Tutorial: Creazione di un bacino d'utenza](https://docs.aws.amazon.com/cognito/latest/developerguide/tutorial-create-user-pool.html) nella *Guida per gli sviluppatori di Amazon Cognito*. Prendi nota dell'ID pool di utenti, dell'ID client e di qualsiasi segreto client. Il client dovrà fornirli ad Amazon Cognito perché l'utente possa registrarsi con il pool di utenti, accedere al pool di utenti e ottenere un token di identità o di accesso da includere nelle richieste per chiamare metodi API configurati con il pool di utenti. Inoltre, devi specificare il nome del pool di utenti quando configuri il pool di utenti come autorizzazioni in API Gateway, come descritto nella prossima sezione. Se stai usando token di accesso per autorizzare le chiamate di metodi API, assicurati di configurare l'integrazione dell'app con il pool di utenti per configurare gli ambiti personalizzati che desideri in un determinato server di risorse. Per ulteriori informazioni sull'utilizzo di token con pool di utenti di Amazon Cognito, consulta [Utilizzo di token con pool di utenti](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Per ulteriori informazioni sui server di risorse, consulta [Definizione dei server di risorse per il pool di utenti](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-user-pools-define-resource-servers.html). Annota gli identificatori dei server di risorse configurati e i nomi degli ambiti personalizzati. Ti servono per creare i nomi completi dell'ambito di accesso per **OAuth Scopes**, che viene utilizzato dall'autorizzatore. `COGNITO_USER_POOLS` ![\[Server di risorse e ambiti del pool di utenti di Amazon Cognito\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/cognito-user-pool-custom-scopes-new-console.png) # Integrazione di un'API REST con un pool di utenti di Amazon Cognito Dopo aver creato un pool di utenti di Amazon Cognito in API Gateway, devi creare un'autorizzazione `COGNITO_USER_POOLS` che usa il pool di utenti. La procedura seguente illustra come eseguire questa operazione tramite la console API Gateway. **Nota** Puoi utilizzare l'operazione [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html) per creare un'autorizzazione `COGNITO_USER_POOLS` che utilizzi più pool di utenti. Puoi utilizzare fino a 1.000 pool di utenti per un unica autorizzazione `COGNITO_USER_POOLS`. Questo limite non può essere aumentato. **Importante** Dopo aver eseguito una delle procedure di seguito, è necessario distribuire o ridistribuire l'API per la propagazione delle modifiche. Per ulteriori informazioni sulla distribuzione della tua API, vedi [Implementazione di REST API in Gateway API](how-to-deploy-api.md). **Per creare un'autorizzazione `COGNITO_USER_POOLS` tramite la console API Gateway** 1. Crea una nuova API oppure selezionane una esistente in API Gateway. 1. Nel riquadro di navigazione principale, scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. Per configurare la nuova autorizzazione per usare un pool di utenti, esegui queste operazioni: 1. In **Nome del provider di autorizzazioni**, immetti un nome. 1. In **Tipo di autorizzazione**, seleziona **Cognito**. 1. Per il **pool di utenti Cognito**, scegli Regione AWS dove hai creato Amazon Cognito e seleziona un pool di utenti disponibile. Per definire il pool di utenti è possibile usare una variabile di fase. Utilizza il seguente formato per il pool di utenti: `arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. In **Origine token**, immetti **Authorization** come nome di intestazione da passare al token di identità o di accesso restituito da Amazon Cognito quando un utente accede correttamente. 1. (Facoltativo) Immetti un'espressione regolare nel campo **Convalida del token** per convalidare il campo `aud` (Audience, Destinatari) del token di identità prima che la richiesta venga autorizzata con Amazon Cognito. Si noti che quando si utilizza un token di accesso questa convalida rifiuta la richiesta poiché il token di accesso non contiene il campo `aud`. 1. Scegli **Crea autorizzazioni**. 1. Dopo aver creato il sistema di autorizzazione `COGNITO_USER_POOLS`, è possibile testarne l’invocazione specificando un token di identità allocato dal pool di utenti. Non è possibile utilizzare un token di accesso per testare l’invocazione del sistema di autorizzazione. Puoi ottenere questo token di identità chiamando l'[SDK Amazon Cognito Identity](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) per eseguire l'accesso dell'utente. È anche possibile usare l'operazione [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html). Se in **Ambiti di autorizzazione** non configuri alcun valore, Gateway API considera il token fornito come un token di identità. La procedura precedente crea un'autorizzazione `COGNITO_USER_POOLS` che utilizza il nuovo pool di utenti di Amazon Cognito appena creato. A seconda del modo in cui abiliti l'autorizzazione per un metodo API, puoi usare un token di identità o un token di accesso assegnato dal pool di utenti integrato. **Per configurare un'autorizzazione `COGNITO_USER_POOLS` per i metodi** 1. Scegliere **Resources** (Risorse). Seleziona un nuovo metodo o scegline uno esistente. Se necessario, crea una risorsa. 1. Nella scheda **Richiesta metodo**, in **Impostazioni richiesta metodo**, scegli **Modifica**. 1. In **Autorizzazioni**, nel menu a discesa, seleziona **Autorizzazioni del gruppo di utenti di Cognito**. 1. Per usare un token di identità, esegui queste operazioni: 1. Non specificare alcun valore in **Ambiti di autorizzazione**. 1. Se necessario, in **Richiesta di integrazione**, aggiungi le espressioni `$context.authorizer.claims['property-name']` o `$context.authorizer.claims.property-name` in un modello di mappatura del corpo per passare la proprietà delle richieste di identità specificata dal pool di utenti al back-end. Per i nomi di proprietà semplici, come `sub` o `custom-sub`, le due notazioni sono identiche. Per i nomi di proprietà complessi, come `custom:role`, non puoi usare la notazione punto. Ad esempio, le espressioni di mappatura seguenti passano i [campi standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) `sub` e `email` della richiesta al back-end: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` Se hai dichiarato un campo di richiesta personalizzato quando hai configurato un pool di utenti, puoi seguire lo stesso modello per accedere ai campi personalizzati. L'esempio seguente ottiene un campo `role` personalizzato di una richiesta: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` Se il campo personalizzato della richiesta viene dichiarato come `custom:role`, usa l'esempio seguente per ottenere le proprietà della richiesta: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. Per usare un token di accesso, esegui queste operazioni: 1. In **Ambiti di autorizzazione**, immetti uno o più nomi completi di un ambito configurato quando è stato creato il pool di utenti di Amazon Cognito. Ad esempio, seguendo l'esempio fornito in [Creazione di un pool di utenti di Amazon Cognito per un'API REST](apigateway-create-cognito-user-pool.md), uno degli ambiti è `https://my-petstore-api.example.com/cats.read`. In fase di runtime, la chiamata del metodo riesce se qualsiasi ambito specificato nel metodo in questa fase corrisponde a un ambito richiesto nel token in ingresso. Altrimenti, la chiamata non riesce e restituisce una risposta `401 Unauthorized`. 1. Scegli **Save** (Salva). 1. Ripeti queste fasi per gli altri metodi scelti. Con l'`COGNITO_USER_POOLS`authorizer, se l'opzione **OAuthScopes** non è specificata, API Gateway tratta il token fornito come un token di identità e verifica l'identità dichiarata rispetto a quella del pool di utenti. Altrimenti, API Gateway considera il token specificato un token di accesso e verifica gli ambiti di accesso richiesti nel token rispetto agli ambiti di autorizzazione dichiarati nel metodo. Invece di usare la console API Gateway, puoi anche abilitare un pool di utenti di Amazon Cognito in un metodo specificando un file di definizione OpenAPI e importando la definizione API in API Gateway. **Per importare un'autorizzazione COGNITO\$1USER\$1POOLS con un file di definizione OpenAPI** 1. Crea (o esporta) un file di definizione OpenAPI per l'API. 1. Specificare la definizione JSON dell'autorizzazione `COGNITO_USER_POOLS` (`MyUserPool`) come parte della sezione `securitySchemes` OpenAPI 3.0 o della sezione `securityDefinitions` in OpenAPI 2.0, nel seguente modo as follows: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. Per usare il token di identità per l'autorizzazione del metodo, aggiungi `{ "MyUserPool": [] }` alla definizione `security` del metodo, come mostrato nel metodo GET seguente nella risorsa root. ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Per usare il token di accesso per l'autorizzazione del metodo, modifica la definizione di sicurezza precedente in `{ "MyUserPool": [resource-server/scope, ...] }`: ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Se necessario, è possibile definire altre impostazioni di configurazione dell'API utilizzando le definizioni o estensioni OpenAPI appropriate. Per ulteriori informazioni, consulta [Estensioni OpenAPI per Gateway API](api-gateway-swagger-extensions.md). # Chiamata di un'API REST integrata con un pool di utenti di Amazon Cognito Per chiamare un metodo con un'autorizzazione del pool di utenti configurata, il client deve eseguire queste operazioni: + Permettere all'utente di iscriversi al pool di utenti. + Permettere all'utente di accedere al pool di utenti. + Ottenere un [token di identità o di accesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html) per l'utente che ha effettuato l'accesso dal pool di utenti. + Includere il token nell'intestazione `Authorization` (o in un'altra intestazione specificata durante la creazione dell'autorizzazione). È possibile utilizzare [AWS Amplify]() per eseguire queste attività. Per maggiori informazioni, consulta [Integrazione di Amazon Cognito con le app Web e per dispositivi mobili](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html). + Per Android, consulta [Nozioni di base su Amplify per Android](https://docs.amplify.aws/android/build-a-backend/auth/). + Per usare iOS, consulta [Nozioni di base su Amplify per iOS](https://docs.amplify.aws/swift/build-a-backend/auth/). + Per utilizzarlo JavaScript, consulta [Getting Started with Amplify for Javascript](https://docs.amplify.aws/javascript/build-a-backend/auth/). # Configurazione dell'autorizzazione Amazon Cognito tra account per un'API REST tramite la console API Gateway Ora puoi anche utilizzare un pool di utenti Amazon Cognito di un altro AWS account come autorizzatore API. Il pool di utenti di Amazon Cognito può utilizzare strategie di autenticazione con token portatori come OAuth o SAML. Ciò semplifica la gestione e la condivisione centralizzata di un autorizzatore del pool di utenti Amazon Cognito centrale su più API Gateway. APIs In questa sezione, viene illustrato come configurare un pool di utenti di Amazon Cognito tra account tramite la console Amazon API Gateway. Queste istruzioni presuppongono che tu abbia già un'API API Gateway in un AWS account e un pool di utenti Amazon Cognito in un altro account. ## Creazione di un sistema di autorizzazione di Amazon Cognito multi-account per una REST API Accedi alla console Gateway Amazon API con l'account contenente la tua API e quindi procedi come descritto di seguito: 1. Crea una nuova API oppure selezionane una esistente in API Gateway. 1. Nel riquadro di navigazione principale, scegli **Autorizzazioni**. 1. Scegli **Crea autorizzazioni**. 1. Per configurare la nuova autorizzazione per usare un pool di utenti, esegui queste operazioni: 1. In **Nome del provider di autorizzazioni**, immetti un nome. 1. In **Tipo di autorizzazione**, seleziona **Cognito**. 1. Per **Gruppo di utenti di Cognito**, copia e incolla l'ARN completo del pool di utenti nel secondo account. **Nota** Nella console Amazon Cognito, puoi trovare l'ARN del pool di utenti nel campo **Pool ARN (ARN pool)** del riquadro **General Settings (Impostazioni generali)**. 1. In **Origine token**, immetti **Authorization** come nome di intestazione da passare al token di identità o di accesso restituito da Amazon Cognito quando un utente accede correttamente. 1. (Facoltativo) Immetti un'espressione regolare nel campo **Convalida del token** per convalidare il campo `aud` (Audience, Destinatari) del token di identità prima che la richiesta venga autorizzata con Amazon Cognito. Si noti che quando si utilizza un token di accesso questa convalida rifiuta la richiesta poiché il token di accesso non contiene il campo `aud`. 1. Scegli **Crea autorizzazioni**. # Crea un autorizzatore Amazon Cognito per un'API REST utilizzando CloudFormation Puoi utilizzarlo CloudFormation per creare un pool di utenti Amazon Cognito e un autorizzatore Amazon Cognito. Il CloudFormation modello di esempio esegue le seguenti operazioni: + Crea un pool di utenti di Amazon Cognito. Il client deve prima far accedere l'utente al pool di utenti e ottenere [un'identità o un token di accesso](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-with-identity-providers.html). Se stai usando token di accesso per autorizzare le chiamate di metodi API, assicurati di configurare l'integrazione dell'app con il pool di utenti per configurare gli ambiti personalizzati che desideri in un determinato server di risorse. + Crea un'API Gateway API con un metodo `GET`. + Crea un'autorizzazione Amazon Cognito che utilizza l'intestazione `Authorization` come origine del token. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: UserPool: Type: AWS::Cognito::UserPool Properties: AccountRecoverySetting: RecoveryMechanisms: - Name: verified_phone_number Priority: 1 - Name: verified_email Priority: 2 AdminCreateUserConfig: AllowAdminCreateUserOnly: true EmailVerificationMessage: The verification code to your new account is {####} EmailVerificationSubject: Verify your new account SmsVerificationMessage: The verification code to your new account is {####} VerificationMessageTemplate: DefaultEmailOption: CONFIRM_WITH_CODE EmailMessage: The verification code to your new account is {####} EmailSubject: Verify your new account SmsMessage: The verification code to your new account is {####} UpdateReplacePolicy: Retain DeletionPolicy: Retain CogAuthorizer: Type: AWS::ApiGateway::Authorizer Properties: Name: CognitoAuthorizer RestApiId: Ref: Api Type: COGNITO_USER_POOLS IdentitySource: method.request.header.Authorization ProviderARNs: - Fn::GetAtt: - UserPool - Arn Api: Type: AWS::ApiGateway::RestApi Properties: Name: MyCogAuthApi ApiDeployment: Type: AWS::ApiGateway::Deployment Properties: RestApiId: Ref: Api DependsOn: - CogAuthorizer - ApiGET ApiDeploymentStageprod: Type: AWS::ApiGateway::Stage Properties: RestApiId: Ref: Api DeploymentId: Ref: ApiDeployment StageName: prod ApiGET: Type: AWS::ApiGateway::Method Properties: HttpMethod: GET ResourceId: Fn::GetAtt: - Api - RootResourceId RestApiId: Ref: Api AuthorizationType: COGNITO_USER_POOLS AuthorizerId: Ref: CogAuthorizer Integration: IntegrationHttpMethod: GET Type: HTTP_PROXY Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets Outputs: ApiEndpoint: Value: Fn::Join: - "" - - https:// - Ref: Api - .execute-api. - Ref: AWS::Region - "." - Ref: AWS::URLSuffix - / - Ref: ApiDeploymentStageprod - / ``` # Integrazioni per REST APIs in API Gateway Dopo aver impostato un metodo API, devi integrarlo con un endpoint nel back-end. Un endpoint di backend viene anche definito endpoint di integrazione e può essere una funzione Lambda, una pagina Web HTTP o un'azione di servizio. AWS Come nel caso del metodo API, l'integrazione dell'API presenta una richiesta e una risposta di integrazione. Una richiesta di integrazione comprende una richiesta HTTP ricevuta dal back-end. Potrebbe o non potrebbe essere diversa dalla richiesta di metodo inviata dal cliente. Una risposta di integrazione è una risposta HTTP contenente l'output restituito dal back-end. La configurazione di una richiesta di integrazione comporta le seguenti operazioni: configurare come passare le richieste di metodo inviate dal client al back-end; configurare come trasformare i dati della richiesta, se necessario, in dati della richiesta di integrazione; specificare quale funzione Lambda chiamare; specificare a quale server HTTP inoltrare la richiesta in arrivo o specificare l'azione del servizio AWS da chiamare. La configurazione di una risposta di integrazione (applicabile solo alle integrazioni non proxy) implica le seguenti operazioni: come passare il risultato restituito dal back-end alla risposta di un metodo di un dato codice di stato, definire come trasformare parametri di risposta di integrazione specifici in base a parametri di risposta dei metodi pre-configurati e configurare come mappare il corpo della risposta di integrazione al corpo della risposta del metodo in base a modelli specifici di mappatura del corpo. A livello di programmazione, una richiesta di integrazione viene incapsulata dalla risorsa [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html), mentre la risposta di integrazione dalla risorsa [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) di API Gateway. Per configurare una richiesta di integrazione, è necessario creare una risorsa [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) e usarla per configurare l'URL dell'endpoint di integrazione. Successivamente, devi impostare le autorizzazioni IAM per accedere al back-end e specificare le mappature per trasformare i dati di richiesta in entrata prima di passarli al back-end. Per configurare una risposta di integrazione per un'integrazione non proxy, è necessario creare una risorsa [https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) e usarla per configurare la relativa risposta del metodo target. Successivamente, devi configurare la mappatura dell'output di back-end alla risposta del metodo. **Topics** + [Configurazione di una richiesta di integrazione in API Gateway](api-gateway-integration-settings-integration-request.md) + [Configurazione di una risposta di integrazione in API Gateway](api-gateway-integration-settings-integration-response.md) + [Integrazioni Lambda per REST APIs in API Gateway](set-up-lambda-integrations.md) + [Integrazioni HTTP per REST APIs in API Gateway](setup-http-integrations.md) + [Trasmetti in streaming la risposta di integrazione per le integrazioni proxy in API Gateway](response-transfer-mode.md) + [Integrazioni private per REST APIs in API Gateway](private-integration.md) + [Integrazioni fittizie per REST APIs in API Gateway](how-to-mock-integration.md) # Configurazione di una richiesta di integrazione in API Gateway Per configurare una richiesta di integrazione, è necessario completare i seguenti task obbligatori e opzionali: 1. Seleziona un tipo di integrazione che stabilisca in che modo i dati di richiesta del metodo vengano passati al back-end. 1. Per le integrazioni non fittizie, specifica un metodo HTTP e l'URI dell'endpoint di integrazione target, eccetto per l'integrazione `MOCK`. 1. Per le integrazioni con le funzioni Lambda e AWS altre azioni di servizio, imposta un ruolo IAM con le autorizzazioni necessarie affinché API Gateway chiami il backend per tuo conto. 1. Per integrazioni non-proxy, imposta le mappature dei parametri necessari per mappare i parametri delle richieste di metodo predefinite ai parametri di richiesta di integrazione più appropriati. 1. Per integrazioni non-proxy, imposta le mappature dei corpi necessari per mappare il corpo delle richieste di metodo in entrata di un tipo di contenuto specifico in base al modello di mappatura designato. 1. Per le integrazioni non-proxy, specifica la condizione in base alla quale i dati della richiesta di metodo in entrata vengano passati attraverso il back-end inalterati. 1. A scelta, specifica come gestire una conversione dei tipi per un payload binario. 1. A scelta, dichiara il nome del namespace cache e i parametri della chiave cache per abilitare il caching delle API. L'esecuzione di queste attività implica la creazione di una risorsa [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) di API Gateway e la configurazione di valori di proprietà adeguati. Puoi farlo utilizzando la console API Gateway, AWS CLI i comandi, un AWS SDK o l'API REST di API Gateway. **Topics** + [Task di base di una richiesta di integrazione API](integration-request-basic-setup.md) + [Scegliere un tipo di integrazione API Gateway API](api-gateway-api-integration-types.md) + [Configurazione di un'integrazione proxy mediante una risorsa proxy](api-gateway-set-up-simple-proxy.md) + [Configurazione di una richiesta di integrazione API tramite la console API Gateway](how-to-method-settings-console.md) # Task di base di una richiesta di integrazione API Una richiesta di integrazione è una richiesta HTTP che API Gateway invia al back-end, passando i dati della richiesta inviata dal client e trasformandoli, se necessario. Il metodo HTTP (o verbo) e l'URI della richiesta di integrazione sono determinati dal back-end (l'endpoint dell'integrazione). Possono essere diversi o uguali, rispettivamente, al metodo HTTP e all'URI della richiesta di metodo. Ad esempio, quando una funzione Lambda restituisce un file proveniente da Amazon S3, puoi esporre intuitivamente questa operazione al client come una richiesta del metodo `GET`, anche se la corrispondente richiesta di integrazione richiede l'uso di una richiesta `POST` per chiamare la funzione Lambda. Per un endpoint HTTP, è probabile che la richiesta di metodo e la richiesta di integrazione corrispondente utilizzino entrambi lo stesso verbo HTTP. Tuttavia, non è obbligatorio. Puoi integrare la seguente richiesta di metodo: ``` GET /{var}?query=value Host: api.domain.net ``` Con la seguente richiesta di integrazione: ``` POST / Host: service.domain.com Content-Type: application/json Content-Length: ... { path: "{var}'s value", type: "value" } ``` Come sviluppatore di API, puoi utilizzare qualunque verbo HTTP e URI per una richiesta di metodo che soddisfino i tuoi requisiti. Tuttavia, devi soddisfare i requisiti dell'endpoint di integrazione. Quando i dati della richiesta di metodo sono diversi dai dati della richiesta di integrazione, puoi eliminare la differenza tramite mappature dei dati della richiesta di metodo ai dati della richiesta di integrazione. Negli esempi precedenti, la mappatura traduce i valori della variabile di percorso (`{var}`) e dei parametri di query (`query`) della richiesta di metodo `GET` nei valori delle proprietà del payload della richiesta di integrazione di `path` e `type`. Tra gli altri dati di richiesta mappabili figurano il corpo e le intestazioni della richiesta. Tali dati sono descritti in [Mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping.md). Quando configuri la richiesta HTTP o di integrazione proxy HTTP, assegni l'URL dell'endpoint HTTP del back-end come valore URI della richiesta di integrazione. Ad esempio, nell' PetStoreAPI, la richiesta del metodo per ottenere una pagina di animali domestici ha il seguente URI di richiesta di integrazione: ``` http://petstore-demo-endpoint.execute-api.com/petstore/pets ``` Quando configuri Lambda o l'integrazione proxy Lambda, assegni l'Amazon Resource Name (ARN) per chiamare la funzione Lambda come valore URI della richiesta di integrazione. Questo ARN ha il seguente formato: ``` arn:aws:apigateway:api-region:lambda:path//2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations ``` La parte dopo `arn:aws:apigateway:api-region:lambda:path/`, ovvero `/2015-03-31/functions/arn:aws:lambda:lambda-region:account-id:function:lambda-function-name/invocations`, è il percorso URI dell'API REST dell'azione Lambda [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html). Se utilizzi la console API Gateway per configurare l'integrazione Lambda, API Gateway crea l'ARN e lo assegna all'URI di integrazione dopo avere chiesto di selezionare il `lambda-function-name` da una regione. Quando si imposta la richiesta di integrazione con un'altra azione di AWS servizio, anche l'URI della richiesta di integrazione è un ARN, simile all'integrazione con l'azione Lambda. `Invoke` Ad esempio, per l'integrazione con l'[GetBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjects.html)azione di Amazon S3, l'URI della richiesta di integrazione è un ARN del seguente formato: ``` arn:aws:apigateway:api-region:s3:path/{bucket} ``` L'URI della richiesta di integrazione è la convenzione del percorso che specifica l'operazione, dove `{bucket}` è il segnaposto del nome di un bucket. In alternativa, è possibile fare riferimento a un'azione di AWS servizio tramite il relativo nome. Utilizzando il nome dell'operazione, l'URI della richiesta di integrazione per l'operazione `GetBucket` di Amazon S3; diventa il seguente: ``` arn:aws:apigateway:api-region:s3:action/GetBucket ``` Con l'URI della richiesta di integrazione basata sull'operazione, il nome del bucket (`{bucket}`) deve essere specificato nel corpo della richiesta di integrazione (`{ Bucket: "{bucket}" }`), seguito dal formato di input dell'operazione `GetBucket`. Per AWS le integrazioni, devi anche configurare le [credenziali](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#credentials) per consentire ad API Gateway di richiamare le azioni integrate. Puoi creare un ruolo IAM o sceglierne uno esistente per consentire ad API Gateway di chiamare l'operazione, quindi specificare il ruolo utilizzando il proprio ARN. Di seguito è illustrato un esempio di questo ARN: ``` arn:aws:iam::account-id:role/iam-role-name ``` Tale ruolo IAM deve contenere una policy che consenta di eseguire l'operazione. API Gateway deve inoltre essere dichiarata (nella relazione di fiducia del ruolo) come entità affidabile per l'assunzione del ruolo. Tali autorizzazioni possono essere assegnate per l'operazione stessa. Si tratta di autorizzazioni basate sulle risorse. Per l'integrazione Lambda, puoi chiamare l'operazione Lambda [addPermission](https://docs.aws.amazon.com/lambda/latest/dg/API_AddPermission.html) per impostare le autorizzazioni basate sulle risorse, quindi configurare `credentials` su null nella richiesta di integrazione di API Gateway. Abbiamo illustrato la configurazione di integrazione di base. Le impostazioni avanzate prevedono la mappatura dei dati della richiesta di metodo ai dati della richiesta di integrazione. Per ulteriori informazioni, consulta [Trasformazioni dei dati per REST APIs in API Gateway](rest-api-data-transformations.md). # Scegliere un tipo di integrazione API Gateway API Seleziona un tipo di integrazione API in base ai tipi di endpoint di integrazione con cui lavori e alla quantità di dati che transitano nell'endpoint di integrazione. Per una funzione Lambda, puoi avere l'integrazione proxy di Lambda o l'integrazione personalizzata di Lambda. Per un endpoint HTTP, puoi avere l'integrazione proxy di HTTP o l'integrazione personalizzata di HTTP. Per un'azione AWS di servizio, è disponibile l' AWS integrazione solo del tipo non proxy. API Gateway supporta anche l'integrazione fittizia, in cui API Gateway serve come endpoint di integrazione per rispondere a una richiesta del metodo. L'integrazione personalizzata Lambda è un caso speciale di integrazione, in cui AWS l'endpoint di integrazione corrisponde all'[azione di richiamo della funzione del servizio Lambda](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html). A livello di programmazione, è possibile scegliere un tipo di integrazione configurando la proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#type) della risorsa [https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Per l'integrazione proxy Lambda, il valore è `AWS_PROXY`. Per l'integrazione personalizzata Lambda e per tutte le altre integrazioni AWS , è `AWS`. Per l'integrazione proxy HTTP e l'integrazione HTTP, il valore è, rispettivamente, `HTTP_PROXY` e `HTTP`. Per l'integrazione fittizia, il valore `type` è `MOCK`. L'integrazione proxy Lambda supporta una configurazione di integrazione semplificata con una singola funzione Lambda. La configurazione è semplice e può evolvere con il back-end senza annullare le impostazioni esistenti. Per questi motivi, è altamente consigliata per l'integrazione con una funzione Lambda. Al contrario, l'integrazione personalizzata Lambda consente il riutilizzo di modelli di mappatura configurati per vari endpoint di integrazione che presentano requisiti simili in termini di formato di dati di input e di output. La configurazione è più complessa ed è consigliata per scenari applicativi più avanzati. Analogamente, l'integrazione proxy HTTP ha una configurazione di integrazione più semplice e può evolvere con il back-end senza annullare le impostazioni esistenti. L'integrazione personalizzata HTTP è più complessa da configurare, ma consente il riutilizzo di modelli di mappatura configurati per altri endpoint di integrazione. L'elenco che segue riepiloga i tipi di integrazione supportati: + `AWS`: questo tipo di integrazione consente a un'API di esporre le operazioni dei servizi AWS . Nell'integrazione `AWS`, devi configurare la richiesta e la risposta di integrazione, oltre a impostare le mappature di dati necessarie dalla richiesta di metodo alla richiesta di integrazione e dalla risposta di integrazione alla risposta di metodo. + `AWS_PROXY`: questo tipo di integrazione consente l'integrazione di un metodo API con un'operazione di chiamata della funzione Lambda tramite una configurazione di integrazione semplificata, flessibile e versatile. Questa integrazione si basa su interazioni dirette tra il client e la funzione Lambda integrata. Con questo tipo di integrazione, noto anche come integrazione proxy Lambda, non devi configurare la richiesta o la risposta di integrazione. API Gateway trasferisce la richiesta in entrata dal client come input alla funzione Lambda back-end. La funzione Lambda integrata prende l'[input di questo formato](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format) e analizza l'input di tutte le fonti disponibili, incluse le intestazioni delle richieste, le variabili di percorso dell'URL, i parametri delle stringhe di query e il corpo applicabile. La funzione restituisce il risultato seguendo questo [formato di output](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format). Questo è il tipo di integrazione preferito per chiamare una funzione Lambda tramite API Gateway e non è applicabile ad altre azioni di AWS servizio, incluse le azioni Lambda diverse dall'azione di richiamo della funzione. + `HTTP`: questo tipo di integrazione consente a un'API di esporre gli endpoint HTTP nel back-end. Con l'integrazione `HTTP`, nota anche come integrazione HTTP personalizzata, devi configurare l richiesta e la risposta di integrazione. Devi configurare le mappature di dati necessarie dalla richiesta di metodo alla richiesta di integrazione e dalla risposta di integrazione alla risposta di metodo. + `HTTP_PROXY`: l'integrazione proxy HTTP consente a un cliente di accedere agli endpoint HTTP di back-end con una configurazione di integrazione semplificata e un singolo metodo API. Non devi configurare la richiesta o la risposta di integrazione. API Gateway trasferisce la richiesta in entrata dal client all'endpoint HTTP e la risposta in uscita dall'endpoint HTTP al client. + `MOCK`: questo tipo di integrazione consente ad API Gateway di restituire una risposta senza inviare la richiesta fino al back-end. Si tratta di un'opzione utile per il test di API, poiché può essere utilizzata per testare la configurazione di integrazione senza sostenere costi per l'utilizzo del back-end e per favorire uno sviluppo collaborativo di un'API. In uno sviluppo collaborativo, un team può isolare la propria attività di sviluppo impostando simulazioni di componenti API di proprietà di altri team utilizzando le integrazioni `MOCK`. Questa opzione viene anche utilizzata per restituire intestazioni relative alla configurazione CORS per verificare che il metodo API ne consenta l'accesso. Di fatto, la console API Gateway integra il metodo `OPTIONS` per supportare la configurazione CORS con un'integrazione fittizia. [Le risposte del gateway](api-gateway-gatewayResponse-definition.md#customize-gateway-responses) sono altri esempi di integrazioni fittizie. # Configurazione di un'integrazione proxy mediante una risorsa proxy Per configurare un'integrazione proxy in un'API di API Gateway mediante una [risorsa proxy](api-gateway-method-settings-method-request.md#api-gateway-proxy-resource), completa le attività seguenti: + Crea una risorsa proxy con una variabile di percorso greedy `{proxy+}`. + Imposta il metodo `ANY` sulla risorsa proxy. + Integra la risorsa e il metodo con un back-end utilizzando il tipo di integrazione HTTP o Lambda. **Nota** Anche se normalmente vengono utilizzati insieme, i metodi `ANY`, i tipi di integrazione proxy e le variabili di percorso greedy sono caratteristiche indipendenti. È possibile configurare un metodo HTTP specifico per una risorsa greedy o applicare tipi di integrazione non proxy a una risorsa proxy. In API Gateway la gestione dei metodi prevede restrizioni e limitazioni specifiche per entrambi tipi di integrazione proxy, Lambda e HTTP. Per informazioni dettagliate, vedi [Note importanti Amazon API Gateway](api-gateway-known-issues.md). **Nota** Quando si utilizza l'integrazione proxy con un passthrough, API Gateway restituisce l'intestazione `Content-Type:application/json` di default, se non è specificato il tipo di contenuto di un payload. Una risorsa proxy è più efficace se integrata con un back-end tramite l'integrazione proxy HTTP o l'[integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) proxy Lambda. ## Integrazione proxy HTTP mediante una risorsa proxy L'integrazione proxy HTTP, designata da `HTTP_PROXY` nell'API REST API Gateway, consente di integrare una richiesta del metodo con un endpoint HTTP di back-end. Con questo tipo di integrazione, API Gateway si limita a trasferire richiesta e risposta complete tra il front-end e il back-end, seguendo [restrizioni e limitazioni](api-gateway-known-issues.md) specifiche. **Nota** L'integrazione proxy HTTP supporta le intestazioni multi-valore e le stringhe di query. Quando si applica l'integrazione proxy HTTP a una risorsa proxy, è possibile configurare l'API in modo che esponga una parte di un'intera gerarchia di endpoint del back-end HTTP con un'unica configurazione di integrazione. Supponi ad esempio che il back-end del sito Web sia organizzato in più rami dei nodi di struttura del nodo radice (`/site`) come: `/site/a0/a1/.../aN`, `/site/b0/b1/.../bM` e così via. Se integri il metodo `ANY` di una risorsa proxy `/api/{proxy+}` con gli endpoint del back-end con percorsi URL `/site/{proxy}`, una singola richiesta di integrazione può supportare qualsiasi operazione HTTP (GET, POST e così via) ovunque in `[a0, a1, ..., aN, b0, b1, ...bM, ...]`. Se invece applichi un'integrazione proxy a un metodo HTTP specifico, ad esempio `GET`, la richiesta di integrazione risultante supporta le operazioni specificate (`GET`) su qualsiasi nodo di back-end. ## Integrazione proxy Lambda mediante una risorsa proxy L'integrazione proxy Lambda, designata da `AWS_PROXY` nell'API REST API Gateway, consente di integrare una richiesta del metodo con una funzione Lambda nel back-end. Con questo tipo di integrazione, API Gateway applica un modello di mappatura predefinito per inviare l'intera richiesta alla funzione Lambda e trasforma l'output di tale funzione in risposte HTTP. Analogamente, puoi applicare l'integrazione proxy Lambda a una risorsa proxy di `/api/{proxy+}` per configurare una sola integrazione e fare in modo che una funzione Lambda back-end reagisca individualmente alle modifiche apportate in una delle risorse API in `/api`. # Configurazione di una richiesta di integrazione API tramite la console API Gateway La configurazione di un metodo API definisce il metodo e descrive i suoi comportamenti. Per configurare un metodo, è necessario specificare una risorsa su cui il metodo è esposto, inclusa la root ("/"), un metodo HTTP (`GET`, `POST` e così via) e il modo in cui sarà integrato con il relativo back-end. La richiesta e la risposta di metodo specificano il contratto con l'app di chiamata e stipulano i parametri che l'API può ricevere e l'aspetto della risposta. Le seguenti procedure descrivono come utilizzare la console Gateway API per creare una richiesta di integrazione. **Topics** + [Configurazione di un'integrazione Lambda](#how-to-method-settings-console-lambda) + [Configurazione di un'integrazione HTTP](#how-to-method-settings-console-http) + [Configura un'integrazione AWS di servizi](#how-to-method-settings-console-aws) + [Configurazione di un'integrazione fittizia](#how-to-method-settings-console-mock) ## Configurazione di un'integrazione Lambda L'integrazione della funzione Lambda si utilizza per integrare l'API con una funzione Lambda. A livello di API, sarà un tipo di integrazione `AWS` se si crea un'integrazione non proxy o un tipo di integrazione `AWS_PROXY` se si crea un'integrazione proxy. **Per configurare l'integrazione Lambda** 1. Nel riquadro **Risorse** scegli **Crea metodo**. 1. Per **Tipo di metodo** seleziona un metodo HTTP. 1. Per **Integration type (Tipo di integrazione)**, scegli **Lambda Function (Funzione Lambda)**. 1. Per utilizzare un'integrazione proxy Lambda, attiva **Integrazione proxy Lambda**. Per ulteriori informazioni sulle integrazioni proxy Lambda, consulta [Informazioni sull'integrazione proxy Lambda di API Gateway](set-up-lambda-proxy-integrations.md#api-gateway-create-api-as-simple-proxy). 1. Per **Funzione Lambda** immetti il nome della funzione Lambda. Se utilizzi una funzione Lambda in una regione diversa da quella dell'API, seleziona la regione dal menu a discesa e inserisci il nome della funzione Lambda. Se usi una funzione Lambda tra diversi account immetti il nome della risorsa Amazon (ARN) della funzione. 1. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione **Timeout predefinito**. Per impostare un timeout personalizzato, scegli **Timeout predefinito** e immetti un valore di timeout compreso tra `50` e `29000` millisecondi. 1. (Facoltativo) È possibile configurare le impostazioni di richiesta del metodo utilizzando i seguenti menu a discesa. Scegli **Impostazioni della richiesta del metodo** e configura la richiesta del metodo. Per ulteriori informazioni, consulta il passaggio 3 di [Modifica di una richiesta del metodo di Gateway API nella console Gateway API](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). È possibile configurare le impostazioni della richiesta del metodo anche dopo aver creato il metodo. 1. Scegli **Crea metodo**. ## Configurazione di un'integrazione HTTP L'integrazione HTTP si utilizza per integrare l'API con un endpoint HTTP. A livello di API, questa è un'integrazione di tipo `HTTP`. **Per configurare un'integrazione HTTP** 1. Nel riquadro **Risorse** scegli **Crea metodo**. 1. Per **Tipo di metodo** seleziona un metodo HTTP. 1. Per **Tipo di integrazione** scegli **Fittizio**. 1. Per utilizzare un'integrazione proxy HTTP, attiva **Integrazione proxy HTTP**. Per ulteriori informazioni sulle integrazioni proxy HTTP, consulta [Configurazione di integrazioni proxy HTTP in API Gateway](setup-http-integrations.md#api-gateway-set-up-http-proxy-integration-on-proxy-resource). 1. Per **HTTP method (Metodo HTTP)** scegliere il tipo di metodo HTTP che corrisponde maggiormente al metodo nel back-end HTTP. 1. Per **URL endpoint** immetti l'URL del back-end HTTP che desideri venga utilizzato dal metodo. 1. Per **Gestione contenuti** seleziona un comportamento di gestione dei contenuti. 1. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione **Timeout predefinito**. Per impostare un timeout personalizzato, scegli **Timeout predefinito** e immetti un valore di timeout compreso tra `50` e `29000` millisecondi. 1. (Facoltativo) È possibile configurare le impostazioni di richiesta del metodo utilizzando i seguenti menu a discesa. Scegli **Impostazioni della richiesta del metodo** e configura la richiesta del metodo. Per ulteriori informazioni, consulta il passaggio 3 di [Modifica di una richiesta del metodo di Gateway API nella console Gateway API](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). È possibile configurare le impostazioni della richiesta del metodo anche dopo aver creato il metodo. 1. Scegli **Crea metodo**. ## Configura un'integrazione AWS di servizi Utilizza un'integrazione AWS di servizi per integrare la tua API direttamente con un AWS servizio. A livello di API, questa è un'integrazione di tipo `AWS`. Per configurare un'API Gateway API procedi come segue: + Crea una nuova funzione Lambda. + Imposta l'autorizzazione per le risorse alla funzione Lambda. + Esegui qualsiasi altra azione del servizio Lambda. È necessario scegliere **Servizio AWS **. **Per configurare un'integrazione AWS di servizi** 1. Nel riquadro **Risorse** scegli **Crea metodo**. 1. Per **Tipo di metodo** seleziona un metodo HTTP. 1. Per **Tipo di integrazione** scegli **Servizio AWS **. 1. Per **AWS Regione**, scegli la AWS regione che desideri utilizzare questo metodo per avviare l'azione. 1. Per l'**AWS assistenza**, scegli il AWS servizio che desideri chiamare con questo metodo. 1. Per **AWS sottodominio**, inserisci il sottodominio utilizzato dal AWS servizio. In genere, questo spazio rimane vuoto. Alcuni servizi AWS supportano i sottodomini come parte degli host. Consulta la documentazione relativa al servizio per la disponibilità e, se disponibili, ulteriori dettagli. 1. In **HTTP method (Metodo HTTP)** scegliere il tipo di metodo HTTP che corrisponde all'operazione. **Per il tipo di metodo HTTP, consulta la documentazione di riferimento dell'API per il AWS servizio che hai scelto per AWS il servizio.** 1. Per **Tipo di operazione** seleziona **Usa nome operazione** per utilizzare un'operazione API o **Utilizza sostituzione percorso** per usare un percorso personalizzato della risorsa. Per le azioni disponibili e i percorsi di risorse personalizzati, consulta la documentazione di riferimento dell'API per il AWS servizio che hai scelto per il **AWS servizio**. 1. Inserisci il **Nome azione** o la **Sostituzione percorso**. 1. In **Ruolo di esecuzione** immetti il nome della risorsa Amazon (ARN) del ruolo IAM utilizzato dal metodo per chiamare l'operazione. Per creare il ruolo IAM puoi adattare le istruzioni disponibili in [Fase 1: creare il ruolo di esecuzione del proxy del AWS servizio](getting-started-aws-proxy.md#getting-started-aws-proxy-add-roles). Specifica una policy di accesso con il numero desiderato di dichiarazioni di risorse e azioni: Per ulteriori informazioni, consulta [Come funziona Amazon API Gateway con IAM](security_iam_service-with-iam.md). Per la sintassi dell'istruzione relativa alle azioni e alle risorse, consulta la documentazione del AWS servizio che hai scelto per il **AWS servizio**. Per la relazione di fiducia del ruolo IAM, specificare quanto segue, in modo da consentire ad API Gateway di intervenire per conto dell'account AWS : ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": "apigateway.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ 1. Per utilizzare il valore di timeout predefinito di 29 secondi, mantieni attiva l'opzione **Timeout predefinito**. Per impostare un timeout personalizzato, scegli **Timeout predefinito** e immetti un valore di timeout compreso tra `50` e `29000` millisecondi. 1. (Facoltativo) È possibile configurare le impostazioni di richiesta del metodo utilizzando i seguenti menu a discesa. Scegli **Impostazioni della richiesta del metodo** e configura la richiesta del metodo. Per ulteriori informazioni, consulta il passaggio 3 di [Modifica di una richiesta del metodo di Gateway API nella console Gateway API](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). È possibile configurare le impostazioni della richiesta del metodo anche dopo aver creato il metodo. 1. Scegli **Crea metodo**. ## Configurazione di un'integrazione fittizia L'integrazione fittizia si utilizza affinché Gateway API agisca come backend e restituisca risposte statiche. A livello di API, questa è un'integrazione di tipo `MOCK`. In genere, puoi utilizzare l'integrazione `MOCK` quando la tua API non è ancora quella definitiva, ma vuoi generare risposte API per liberare i team relativi e dedicarli al test. Per il metodo `OPTION`, API Gateway imposta l'integrazione `MOCK` come predefinita per restituire intestazioni abilitate a CORS per la risorsa API applicata. **Per configurare un'integrazione fittizia** 1. Nel riquadro **Risorse** scegli **Crea metodo**. 1. Per **Tipo di metodo** seleziona un metodo HTTP. 1. Per **Tipo di integrazione** scegli **Fittizio**. 1. (Facoltativo) È possibile configurare le impostazioni di richiesta del metodo utilizzando i seguenti menu a discesa. Scegli **Impostazioni della richiesta del metodo** e configura la richiesta del metodo. Per ulteriori informazioni, consulta il passaggio 3 di [Modifica di una richiesta del metodo di Gateway API nella console Gateway API](how-to-set-up-method-using-console.md#how-to-method-settings-callers-console). È possibile configurare le impostazioni della richiesta del metodo anche dopo aver creato il metodo. 1. Scegli **Crea metodo**. # Configurazione di una risposta di integrazione in API Gateway Per un'integrazione non-proxy, devi impostare almeno una risposta di integrazione come predefinita, per trasmettere il risultato restituito dal back-end al client. Puoi scegliere di trasmettere il risultato invariato o di trasformare i dati della risposta di integrazione in dati della risposta di metodo se i formati sono diversi. Per un'integrazione proxy, API Gateway passa automaticamente l'output del back-end al client come risposta HTTP. Non devi configurare la risposta del metodo o la risposta di integrazione. Per configurare una risposta di integrazione, è necessario completare le seguenti attività obbligatorie e facoltative: 1. Specifica un codice di stato HTTP di una risposta di metodo su cui sono mappati i dati della risposta di integrazione. Questo dato è obbligatorio. 1. Definisci un'espressione regolare per scegliere che l'output del back-end sia rappresentato da questa risposta di integrazione. Se questo spazio rimane vuoto, la risposta corrisponde a quella predefinita utilizzata per cogliere qualsiasi risposta non ancora configurata. 1. Se necessario, dichiara le mappature che consistono di coppie chiave-valore per mappare parametri di risposta di integrazione specifici su parametri di risposta di metodo. 1. Se necessario, aggiungi modelli di mappatura del corpo per trasformare i payload di risposte di integrazione specifiche in payload di risposta di metodo. 1. Se necessario, specifica come gestire una conversione dei tipi per un payload binario. Una risposta di integrazione è una risposta HTTP contenente la risposta del back-end. Per un endpoint HTTP, la risposta del back-end è una risposta HTTP. Il codice di stato della risposta di integrazione può riferirsi al codice di stato restituito dal back-end, mentre il corpo della risposta di integrazione coincide con il payload restituito dal back-end. Per un endpoint Lambda, la risposta del back-end è l'output restituito dalla funzione Lambda. Con l'integrazione Lambda, l'output della funzione Lambda viene restituito come risposta `200 OK`. Il payload può contenere il risultato come dati JSON, incluso una stringa o un oggetto JSON, o un messaggio di errore come oggetto JSON. Puoi assegnare un'espressione regolare alla proprietà [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) per mappare una risposta di errore a una risposta di errore HTTP adeguata. Per ulteriori informazioni sulle risposte di errore della funzione Lambda, consulta [Gestione degli errori Lambda in API Gateway](handle-errors-in-lambda-integration.md). Con l'integrazione proxy di Lambda, la funzione Lambda deve restituire l'output nel formato seguente: ``` { statusCode: "...", // a valid HTTP status code headers: { custom-header: "..." // any API-specific custom header }, body: "...", // a JSON string. isBase64Encoded: true|false // for binary support } ``` Non è necessario mappare la risposta della funzione Lambda alla risposta HTTP appropriata. Per restituire il risultato al client, configura la risposta di integrazione per trasmettere la risposta invariata dell'endpoint alla risposta di metodo corrispondente. Oppure puoi mappare i dati di risposta dell'endpoint ai dati di risposta del metodo. Tra i dati di risposta che possono essere mappati figurano il codice di stato della risposta, i parametri di intestazione della risposta e il corpo della risposta. Se per il codice di stato restituito non è stata definita una risposta del metodo, API Gateway restituisce l'errore 500. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). # Integrazioni Lambda per REST APIs in API Gateway Puoi integrare un metodo API con una funzione Lambda tramite l'integrazione proxy Lambda o l'integrazione non proxy (personalizzata) Lambda. Nell'integrazione proxy Lambda la configurazione richiesta è semplice. Impostare il metodo HTTP dell'integrazione su POST, l'URI dell'endpoint di integrazione sull'ARN dell'operazione di chiamata di una specifica funzione Lambda e la credenziale su un ruolo IAM con autorizzazioni per permettere ad API Gateway di chiamare la funzione Lambda per conto tuo. Nell'integrazione non proxy Lambda, oltre alla procedura di configurazione dell'integrazione proxy, devi specificare anche il modo in cui i dati della richiesta in entrata vengono mappati alla richiesta di integrazione e il modo in cui i dati della risposta di integrazione risultante vengono mappati alla risposta del metodo. **Topics** + [Integrazioni proxy Lambda in Gateway API](set-up-lambda-proxy-integrations.md) + [Configurazione di integrazioni personalizzate Lambda in API Gateway](set-up-lambda-custom-integrations.md) + [Configurazione della chiamata asincrona della funzione Lambda back-end](set-up-lambda-integration-async.md) + [Gestione degli errori Lambda in API Gateway](handle-errors-in-lambda-integration.md) # Integrazioni proxy Lambda in Gateway API La sezione seguente illustra come utilizzare un'integrazione proxy Lambda. **Topics** + [Informazioni sull'integrazione proxy Lambda di API Gateway](#api-gateway-create-api-as-simple-proxy) + [Supporto per le intestazioni multi-valore e i parametri di stringa di query](#apigateway-multivalue-headers-and-parameters) + [Formato di input di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-input-format) + [Formato di output di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-output-format) + [Configura l'integrazione del proxy Lambda per API Gateway utilizzando il AWS CLI](set-up-lambda-proxy-integration-using-cli.md) + [Configurazione di una risorsa proxy con l'integrazione proxy Lambda con una definizione OpenAPI](api-gateway-set-up-lambda-proxy-integration-on-proxy-resource.md) ## Informazioni sull'integrazione proxy Lambda di API Gateway L'integrazione proxy Lambda di Amazon API Gateway è un sistema semplice, potente e agile per creare un'API con una configurazione di un singolo metodo API. Permette al client di chiamare una singola funzione Lambda nel back-end. La funzione accede a molte risorse o funzionalità di altri AWS servizi, inclusa la chiamata ad altre funzioni Lambda. Nell'integrazione proxy Lambda, quando un client invia una richiesta API, API Gateway passa alla funzione Lambda integrata un [oggetto evento](#api-gateway-simple-proxy-for-lambda-input-format), ad eccezione del fatto che non viene mantenuto l'ordine dei parametri della richiesta. Questi [dati di richiesta](#api-gateway-simple-proxy-for-lambda-input-format) includono intestazioni di richiesta, parametri delle stringhe di query, variabili di percorso URL, payload e dati di configurazione API. I dati di configurazione possono includere il nome della fase di distribuzione corrente, variabili di fasi, identità utente o contesto di autorizzazione (se presente). La funzione Lambda back-end analizza i dati delle richieste in entrata per stabilire la risposta da restituire. Perché API Gateway possa passare l'output Lambda come risposta API al client, la funzione Lambda deve restituire il risultato in [questo formato](#api-gateway-simple-proxy-for-lambda-output-format). Poiché API Gateway non interviene in modo significativo tra il client e la funzione Lambda back-end per l'integrazione proxy Lambda, il client e la funzione Lambda integrata possono adattarsi alle modifiche reciproche senza alterare la configurazione di integrazione esistente dell'API. Per consentirlo, il client deve seguire i protocolli di applicazione attuati dalla funzione Lambda back-end. Puoi configurare un'integrazione proxy Lambda per qualsiasi metodo API. Tuttavia un'integrazione proxy Lambda è più potente quando viene configurata per un metodo API che coinvolge una risorsa proxy generica. La risorsa proxy generica può essere indicata dalla speciale variabile di percorso preconfigurata `{proxy+}`, dal segnaposto del metodo catch-all `ANY` o da entrambi. Il client può passare l'input alla funzione Lambda back-end nella richiesta in entrata come parametri di richiesta o payload applicabile. I parametri di richiesta includono intestazioni, variabili di percorso URL, parametri delle stringhe di query e il payload applicabile. La funzione Lambda integrata verifica tutte le sorgenti di input prima di elaborare la richiesta e rispondere al client con messaggi di errore significativi, se manca qualcuno degli input richiesti. Quando si chiama un metodo API integrato con il metodo HTTP generico `ANY` e la risorsa generica `{proxy+}`, il client invia una richiesta con un metodo HTTP specifico al posto di `ANY`. Il client inoltre specifica un particolare percorso URL al posto di `{proxy+}` e include eventuali intestazioni, parametri delle stringhe di query o payload applicabile necessari. L'elenco di seguito riepiloga i comportamenti di runtime di diversi metodi API con l'integrazione proxy Lambda: + `ANY /{proxy+}`: per passare i dati come input alla funzione Lambda integrata, il client deve scegliere un metodo HTTP specifico, deve impostare una determinata gerarchia di percorso di risorsa e può impostare qualsiasi intestazione, parametro di stringa di query e payload applicabile. + `ANY /res`: per passare i dati come input alla funzione Lambda integrata, il client deve scegliere un metodo HTTP specifico e può impostare qualsiasi intestazione, parametro di stringa di query e payload applicabile. + `GET|POST|PUT|... /{proxy+}`: per passare i dati come input alla funzione Lambda integrata, il client può impostare una specifica gerarchia di percorso di risorsa, qualsiasi intestazione, parametro di stringa di query e payload applicabile. + `GET|POST|PUT|... /res/{path}/...`: per passare i dati di input alla funzione Lambda integrata, il client deve scegliere un segmento di percorso specifico (per la variabile `{path}`) e può impostare qualsiasi intestazione di richiesta, parametro di stringa di query e payload applicabile. + `GET|POST|PUT|... /res`: per passare i dati di input alla funzione Lambda integrata, il client può scegliere qualsiasi intestazione di richiesta, parametro di stringa di query e payload applicabile. La risorsa proxy `{proxy+}` e quella personalizzata `{custom}` sono entrambe espresse come variabili di percorso preconfigurate. Tuttavia `{proxy+}` può fare riferimento a qualsiasi risorsa in una gerarchia di percorso, mentre `{custom}` fa riferimento solo a un segmento di percorso specifico. Ad esempio, un negozio di generi alimentari potrebbe organizzare il proprio inventario di prodotti online in base ai nomi dei reparti, alle categorie di produzione e ai tipi di prodotto. Il sito Web del negozio potrebbe quindi rappresentare i prodotti disponibili in base alle seguenti variabili di percorso preconfigurate di risorse personalizzate: `/{department}/{produce-category}/{product-type}`. Ad esempio le mele sono rappresentate da `/produce/fruit/apple` e le carote da `/produce/vegetables/carrot`. Può anche usare `/{proxy+}` per rappresentare qualsiasi reparto, categoria di produzione o tipo di prodotto che un cliente può cercare quando fa acquisti nel negozio online. Ad esempio, `/{proxy+}` può fare riferimento a uno qualsiasi degli articoli seguenti: + `/produce` + `/produce/fruit` + `/produce/vegetables/carrot` Per permettere ai clienti di cercare i prodotti disponibili, la categoria di produzione e il reparto del negozio associato, puoi esporre un singolo metodo `GET /{proxy+}` con autorizzazioni di sola lettura. Allo stesso modo, per consentire a un supervisore di aggiornare l'inventario del `produce` reparto, puoi impostare un altro metodo unico di utilizzo delle `PUT /produce/{proxy+}` autorizzazioni. read/write Per consentire a un cassiere di aggiornare il totale corrente di un ortaggio, puoi impostare un `POST /produce/vegetables/{proxy+}` metodo con autorizzazioni. read/write Per consentire al gestore del negozio di eseguire qualsiasi azione possibile su qualsiasi prodotto disponibile, lo sviluppatore del negozio online può esporre il metodo con le `ANY /{proxy+}` autorizzazioni. read/write In ogni caso, al runtime il cliente o il dipendente deve selezionare un prodotto specifico di un determinato tipo in un reparto scelto, una particolare categoria di produzione in un reparto scelto o un reparto specifico. Per ulteriori informazioni sull'impostazione delle integrazioni proxy di API Gateway, consulta [Configurazione di un'integrazione proxy mediante una risorsa proxy](api-gateway-set-up-simple-proxy.md). Per l'integrazione proxy è necessario che il client abbia una conoscenza più dettagliata dei requisiti del back-end. Pertanto, per garantire prestazioni dell'app e un'esperienza utente ottimali, lo sviluppatore di back-end deve comunicare chiaramente allo sviluppatore del client i requisiti del back-end e fornire un sistema solido di notifica degli errori quando i requisiti non vengono soddisfatti. ## Supporto per le intestazioni multi-valore e i parametri di stringa di query API Gateway ora supporta più intestazioni e parametri di stringa di query con lo stesso nome. Le intestazioni multi-valore, quelle con valore singolo e le intestazioni di valore e parametri possono essere combinati nelle stesse richieste e risposte. Per ulteriori informazioni, consultare [Formato di input di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-input-format) e [Formato di output di una funzione Lambda per l'integrazione proxy](#api-gateway-simple-proxy-for-lambda-output-format). ## Formato di input di una funzione Lambda per l'integrazione proxy Con l'integrazione proxy Lambda, API Gateway mappa l'intera richiesta client al parametro di input `event` della funzione Lambda di back-end. Nell'esempio seguente viene illustrata la struttura di un evento che API Gateway invia a un'integrazione proxy Lambda. In questo esempio si presuppone che l’invocazione a Gateway API sia la seguente: ``` curl 'https://a1b2c3.execute-api.us-east-1.amazonaws.com/my/path?parameter1=value1¶meter2=value1¶meter2=value2¶meter3=value1,value2' -H 'header1: value1' -H 'header2: value1' -H 'header2: value2' -H 'header3: value1,value2' ``` L'output sarà simile al seguente: ``` { "resource": "/my/path", "path": "/my/path", "httpMethod": "GET", "headers": { "header1": "value1", "header2": "value2", "header3": "value1,value2" }, "multiValueHeaders": { "header1": ["value1"], "header2": ["value1","value2"], "header3": ["value1,value2"] }, "queryStringParameters": { "parameter1": "value1", "parameter2": "value2", "parameter3": "value1,value2" }, "multiValueQueryStringParameters": { "parameter1": ["value1"], "parameter2": ["value1","value2"], "parameter3": ["value1,value2"] }, "requestContext": { "accountId": "123456789012", "apiId": "id", "authorizer": { "claims": null, "scopes": null }, "domainName": "id.execute-api.us-east-1.amazonaws.com", "domainPrefix": "id", "extendedRequestId": "request-id", "httpMethod": "GET", "identity": { "accessKey": null, "accountId": null, "caller": null, "cognitoAuthenticationProvider": null, "cognitoAuthenticationType": null, "cognitoIdentityId": null, "cognitoIdentityPoolId": null, "principalOrgId": null, "sourceIp": "IP", "user": null, "userAgent": "user-agent", "userArn": null, "clientCert": { "clientCertPem": "CERT_CONTENT", "subjectDN": "www.example.com", "issuerDN": "Example issuer", "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", "validity": { "notBefore": "May 28 12:30:02 2019 GMT", "notAfter": "Aug 5 09:36:04 2021 GMT" } } }, "path": "/my/path", "protocol": "HTTP/1.1", "requestId": "id=", "requestTime": "04/Mar/2020:19:15:17 +0000", "requestTimeEpoch": 1583349317135, "resourceId": null, "resourcePath": "/my/path", "stage": "$default" }, "pathParameters": null, "stageVariables": null, "body": "Hello from Lambda!", "isBase64Encoded": false } ``` **Nota** Nell'input: La chiave `headers` può contenere solo una decina di intestazioni di valore. La chiave `multiValueHeaders` può contenere intestazioni multi-valore e il valore di una decina di intestazioni. Se si specificano valori sia per `headers` che per `multiValueHeaders`, API Gateway li unisce in un unico elenco. Se la stessa coppia chiave-valore viene specificata in entrambi, solo i valori di `multiValueHeaders` verranno visualizzati nell'elenco risultante. Nell'input per la funzione Lambda back-end l'oggetto `requestContext` è una mappa di coppie chiave/valore. In ogni coppia la chiave è il nome di una proprietà della variabile [\$1context](api-gateway-mapping-template-reference.md#context-variable-reference) e il valore è il valore della proprietà. Gateway API potrebbe aggiungere nuove chiavi alla mappa. A seconda delle funzionalità abilitate, la mappa `requestContext` può variare in base all'API. Ad esempio, nell'esempio precedente non è specificato alcun tipo di autorizzazione e di conseguenza non è presente alcuna proprietà `$context.authorizer.*` o `$context.identity.*`. Quando è specificato un tipo di autorizzazione, API Gateway passa informazioni sugli utenti autorizzati all'endpoint di integrazione in un oggetto `requestContext.identity` nel modo seguente: + Quando il tipo di autorizzazione è `AWS_IAM`, le informazioni sugli utenti autorizzati includono proprietà `$context.identity.*`. + Quando il tipo di autorizzazione è `COGNITO_USER_POOLS` (autorizzazione di Amazon Cognito), le informazioni sugli utenti autorizzati includono le proprietà `$context.identity.cognito*` e `$context.authorizer.claims.*`. + Quando il tipo di autorizzazione è `CUSTOM` (autorizzazione Lambda), le informazioni sugli utenti autorizzati includono `$context.authorizer.principalId` e altre proprietà `$context.authorizer.*` applicabili. ## Formato di output di una funzione Lambda per l'integrazione proxy Nell'integrazione proxy Lambda, API Gateway richiede la funzione Lambda back-end per restituire l'output in base al seguente formato JSON: ``` { "isBase64Encoded": true|false, "statusCode": httpStatusCode, "headers": { "headerName": "headerValue", ... }, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "body": "..." } ``` Nell'output: + Le chiavi `headers` e `multiValueHeaders` possono non essere specificate se non devono essere restituite intestazioni di risposta aggiuntive. + La chiave `headers` può contenere solo una decina di intestazioni di valore. + La chiave `multiValueHeaders` può contenere intestazioni multi-valore e il valore di una decina di intestazioni. È possibile utilizzare la chiave `multiValueHeaders` per specificare tutte le intestazioni aggiuntive, incluse quelle con valore singolo. + Se si specificano valori sia per `headers` che per `multiValueHeaders`, API Gateway li unisce in un unico elenco. Se la stessa coppia chiave-valore viene specificata in entrambi, solo i valori di `multiValueHeaders` verranno visualizzati nell'elenco risultante. Per abilitare CORS per l'integrazione proxy Lambda, devi aggiungere `Access-Control-Allow-Origin:domain-name` all'output `headers`. `domain-name` può essere `*` per qualsiasi nome di dominio. Viene eseguito il marshalling del parametro `body` di output al front-end come payload di risposta del metodo. Se `body` è un BLOB binario, puoi codificarlo come stringa con codifica Base64 impostando `isBase64Encoded` su `true` e configurando `*/*` come **Binary Media Type (Tipo multimediale binario)**. In caso contrario, puoi impostarlo su `false` o lasciarlo non specificato. **Nota** Per ulteriori informazioni sull'abilitazione del supporto binario, consulta [Abilitazione del supporto binario tramite la console API Gateway](api-gateway-payload-encodings-configure-with-console.md). Per un esempio di funzione Lambda, consulta [Restituzione di supporti binari da un'integrazione proxy Lambda in Gateway API](lambda-proxy-binary-media.md). Se l'output della funzione ha un formato diverso, API Gateway restituisce una risposta di errore `502 Bad Gateway`. Per restituire una risposta in una funzione Lambda in Node.js, è possibile utilizzare comandi come i seguenti: + Per ottenere un buon risultato, effettuare la chiamata a `callback(null, {"statusCode": 200, "body": "results"})`. + Per generare un'eccezione, chiama `callback(new Error('internal server error'))`. + Per un errore lato client (se, ad esempio, un parametro obbligatorio è mancante), puoi chiamare `callback(null, {"statusCode": 400, "body": "Missing parameters of ..."})` per restituire l'errore senza generare un'eccezione. In una funzione Lambda `async` in Node.js, la sintassi equivalente è la seguente: + Per ottenere un buon risultato, effettuare la chiamata a `return {"statusCode": 200, "body": "results"}`. + Per generare un'eccezione, chiama `throw new Error("internal server error")`. + Per un errore lato client (se, ad esempio, un parametro obbligatorio è mancante), puoi chiamare `return {"statusCode": 400, "body": "Missing parameters of ..."}` per restituire l'errore senza generare un'eccezione. # Configura l'integrazione del proxy Lambda per API Gateway utilizzando il AWS CLI In questa sezione viene illustrato come usare AWS CLI per configurare un'API con l'integrazione proxy Lambda. Per istruzioni dettagliate sull'uso della console API Gateway per configurare una risorsa proxy con l'integrazione proxy Lambda, consulta [Tutorial: creazione di una REST API con un'integrazione proxy Lambda](api-gateway-create-api-as-simple-proxy-for-lambda.md). Per questo scenario useremo la funzione Lambda di esempio seguente come back-end dell'API: ``` export const handler = async(event, context) => { console.log('Received event:', JSON.stringify(event, null, 2)); var res ={ "statusCode": 200, "headers": { "Content-Type": "*/*" } }; var greeter = 'World'; if (event.greeter && event.greeter!=="") { greeter = event.greeter; } else if (event.body && event.body !== "") { var body = JSON.parse(event.body); if (body.greeter && body.greeter !== "") { greeter = body.greeter; } } else if (event.queryStringParameters && event.queryStringParameters.greeter && event.queryStringParameters.greeter !== "") { greeter = event.queryStringParameters.greeter; } else if (event.multiValueHeaders && event.multiValueHeaders.greeter && event.multiValueHeaders.greeter != "") { greeter = event.multiValueHeaders.greeter.join(" and "); } else if (event.headers && event.headers.greeter && event.headers.greeter != "") { greeter = event.headers.greeter; } res.body = "Hello, " + greeter + "!"; return res }; ``` Rispetto alla configurazione dell'integrazione personalizzata Lambda riportata in [Configurazione di integrazioni personalizzate Lambda in API Gateway](set-up-lambda-custom-integrations.md), l'input per questa funzione Lambda può essere espresso nei parametri e nel corpo della richiesta. Avrai maggiore libertà per permettere al client di passare gli stessi dati di input. Qui il client può passare il nome del mittente della formula di saluto come parametro della stringa di query, intestazione o proprietà del corpo. La funzione può anche supportare l'integrazione personalizzata Lambda. La configurazione dell'API è più semplice. Non devi configurare la risposta del metodo o la risposta di integrazione. **Per configurare un'integrazione con proxy Lambda utilizzando il AWS CLI** 1. Usa il seguente [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando per creare un'API: ``` aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' ``` L'output sarà simile al seguente: ``` { "name": "HelloWorldProxy (AWS CLI)", "id": "te6si5ach7", "rootResourceId" : "krznpq9xpg", "createdDate": 1508461860 } ``` In questo esempio si utilizza `id` dell’API (`te6si5ach7`) e `rootResourceId` (`krznpq9xpg`). 1. Utilizza il seguente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) per creare una [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` di Gateway API: ``` aws apigateway create-resource \ --rest-api-id te6si5ach7 \ --parent-id krznpq9xpg \ --path-part {proxy+} ``` L'output sarà simile al seguente: ``` { "path": "/{proxy+}", "pathPart": "{proxy+}", "id": "2jf6xt", "parentId": "krznpq9xpg" } ``` Nel passaggio successivo si utilizza il valore `id` (`2jf6xt`) della risorsa `{proxy+}` per creare un metodo sulla risorsa `/{proxy+}`. 1. Utilizza il seguente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) per creare una richiesta di metodo `ANY` come `ANY /{proxy+}`: ``` aws apigateway put-method --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method ANY \ --authorization-type "NONE" ``` L'output sarà simile al seguente: ``` { "apiKeyRequired": false, "httpMethod": "ANY", "authorizationType": "NONE" } ``` Questo metodo API permette al client di ricevere o inviare formule di saluto dalla funzione Lambda nel back-end. 1. Utilizza il seguente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) per configurare l’integrazione del metodo `ANY /{proxy+}` con una funzione Lambda denominata `HelloWorld`. Questa funzione risponde alla richiesta con un messaggio `"Hello, {name}!"` se è specificato il parametro `greeter`, altrimenti con un messaggio `"Hello, World!"` se il parametro della stringa di query non è impostato. ``` aws apigateway put-integration \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method ANY \ --type AWS_PROXY \ --integration-http-method POST \ --uri arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:123456789012:function:HelloWorld/invocations \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole ``` **Importante** Per le integrazioni Lambda, devi usare il metodo HTTP `POST` per la richiesta di integrazione, secondo la [specifica dell'operazione del servizio Lambda per le chiamate della funzione](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Il ruolo IAM `apigAwsProxyRole` deve includere policy che permettono al servizio `apigateway` di richiamare funzioni Lambda. Per ulteriori informazioni sulle autorizzazioni IAM, consultare [Modello di autorizzazione API Gateway per invocare un'API](permissions.md#api-gateway-control-access-iam-permissions-model-for-calling-api). L'output sarà simile al seguente: ``` { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-west-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-west-2:1234567890:function:HelloWorld/invocations", "httpMethod": "POST", "cacheNamespace": "vvom7n", "credentials": "arn:aws:iam::1234567890:role/apigAwsProxyRole", "type": "AWS_PROXY" } ``` Invece di specificare un ruolo IAM per `credentials`, è possibile utilizzare il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) per aggiungere autorizzazioni basate su risorse. Questo è ciò che fa la console API Gateway. 1. Utilizza il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per distribuire l’API in una fase `test`. ``` aws apigateway create-deployment \ --rest-api-id te6si5ach7 \ --stage-name test ``` 1. Testa l'API usando i comandi cURL seguenti in un terminale. Chiamata dell'API con il parametro della stringa di query `?greeter=jane`: ``` curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=jane' ``` Chiamata dell'API con un parametro di intestazione `greeter:jane`: ``` curl -X GET https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'content-type: application/json' \ -H 'greeter: jane' ``` Chiamata dell'API con un corpo `{"greeter":"jane"}`: ``` curl -X POST https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/hi \ -H 'content-type: application/json' \ -d '{ "greeter": "jane" }' ``` In tutti i casi, l'output è una risposta 200 con il corpo seguente: ``` Hello, jane! ``` # Configurazione di una risorsa proxy con l'integrazione proxy Lambda con una definizione OpenAPI Per configurare una risorsa proxy con il tipo di integrazione proxy Lambda, crea una risorsa API con un parametro di percorso greedy, ad esempio `/parent/{proxy+}`, e integra la risorsa con il back-end di una funzione Lambda , ad esempio `arn:aws:lambda:us-west-2:123456789012:function:SimpleLambda4ProxyResource`, nel metodo `ANY`. Il parametro di percorso greedy deve trovarsi alla fine del percorso della risorsa API. Come per una risorsa non proxy, puoi configurare la risorsa proxy usando la console API Gateway, importando un file di definizione OpenAPI o chiamando direttamente l'API REST di API Gateway. Il file di definizione API OpenAPI mostra un esempio di API con una risorsa proxy integrata con una funzione Lambda denominata `SimpleLambda4ProxyResource`. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "parameters": [ { "name": "proxy", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } }, "servers": [ { "url": "https://gy415nuibc.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/testStage" } } } ] } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-09-12T17:50:37Z", "title": "ProxyIntegrationWithLambda" }, "host": "gy415nuibc.execute-api.us-east-1.amazonaws.com", "basePath": "/testStage", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:SimpleLambda4ProxyResource/invocations", "passthroughBehavior": "when_no_match", "httpMethod": "POST", "cacheNamespace": "roq9wj", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "aws_proxy" } } } } } ``` ------ Nell'integrazione proxy Lambda, in fase di esecuzione, API Gateway mappa una richiesta in entrata nel parametro di input `event` della funzione Lambda. L'input include il metodo della richiesta, il percorso, le intestazioni, qualsiasi parametro della stringa di query, qualsiasi payload, il contesto associato e qualsiasi variabile di fase definita. Il formato di input viene descritto in [Formato di input di una funzione Lambda per l'integrazione proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Perché API Gateway possa mappare correttamente l'output di Lambda a risposte HTTP, la funzione Lambda deve restituire il risultato nel formato descritto in [Formato di output di una funzione Lambda per l'integrazione proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-output-format). Con l'integrazione proxy Lambda di una risorsa proxy tramite il metodo `ANY`, la singola funzione Lambda back-end funge da gestore eventi per tutte le richieste attraverso la risorsa proxy. Ad esempio, per registrare i modelli di traffico, puoi fare in modo che un dispositivo mobile invii le informazioni di posizione relative a stato, città, indirizzo ed edificio inviando una richiesta con `/state/city/street/house` nel percorso URL della risorsa proxy. La funzione Lambda back-end può quindi analizzare il percorso URL e inserire le tuple di posizione in una tabella DynamoDB. # Configurazione di integrazioni personalizzate Lambda in API Gateway Per mostrare come si configura l’integrazione personalizzata, o non proxy, Lambda, si crea un’API di Gateway API per esporre il metodo `GET /greeting?greeter={name}` in modo da invocare una funzione Lambda. Usa uno dei seguenti esempi di funzioni Lambda per l'API. Usa uno dei seguenti esempi di funzioni Lambda: ------ #### [ Node.js ] ``` 'use strict'; var days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']; var times = ['morning', 'afternoon', 'evening', 'night', 'day']; export const handler = async(event) => { console.log(event); // Parse the input for the name, city, time and day property values let name = event.name === null || event.name === undefined || event.name === "" ? 'you' : event.name; let city = event.city === undefined ? 'World' : event.city; let time = times.indexOf(event.time)<0 ? 'day' : event.time; let day = days.indexOf(event.day)<0 ? null : event.day; // Generate a greeting let greeting = 'Good ' + time + ', ' + name + ' of ' + city + '. '; if (day) greeting += 'Happy ' + day + '!'; // Log the greeting to CloudWatch console.log('Hello: ', greeting); // Return a greeting to the caller return greeting; }; ``` ------ #### [ Python ] ``` import json def lambda_handler(event, context): print(event) res = { "statusCode": 200, "headers": { "Content-Type": "*/*" } } if event['greeter'] == "": res['body'] = "Hello, World" elif (event['greeter']): res['body'] = "Hello, " + event['greeter'] + "!" else: raise Exception('Missing the required greeter parameter.') return res ``` ------ Questa funzione risponde con un messaggio `"Hello, {name}!"` se il valore del parametro `greeter` è una stringa non vuota. La funzione restituisce un messaggio `"Hello, World!"` se il valore di `greeter` è una stringa vuota. La funzione restituisce un messaggio di errore `"Missing the required greeter parameter."` se il parametro greeter non è impostato nella richiesta in ingresso. Denominiamo la funzione `HelloWorld`. Puoi crearla nella console Lambda o tramite la AWS CLI. In questa sezione faremo riferimento alla funzione usando l'ARN seguente: ``` arn:aws:lambda:us-east-1:123456789012:function:HelloWorld ``` Con la funzione Lambda impostata nel back-end, procedi a configurare l'API. **Per configurare l'integrazione personalizzata Lambda utilizzando il AWS CLI** 1. Usa il seguente [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando per creare un'API: ``` aws apigateway create-rest-api --name 'HelloWorld (AWS CLI)' ``` L'output sarà simile al seguente: ``` { "name": "HelloWorld (AWS CLI)", "id": "te6si5ach7", "rootResourceId" : "krznpq9xpg", "createdDate": 1508461860 } ``` In questo esempio si utilizza `id` dell’API (`te6si5ach7`) e `rootResourceId` (`krznpq9xpg`). 1. Utilizza il seguente comando [create-resource](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-resource.html) per creare una [risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_Resource.html) `/greeting` di Gateway API: ``` aws apigateway create-resource \ --rest-api-id te6si5ach7 \ --parent-id krznpq9xpg \ --path-part greeting ``` L'output sarà simile al seguente: ``` { "path": "/greeting", "pathPart": "greeting", "id": "2jf6xt", "parentId": "krznpq9xpg" } ``` Nel passaggio successivo si utilizza il valore `id` (`2jf6xt`) della risorsa `greeting` per creare un metodo sulla risorsa `/greeting`. 1. Utilizza il seguente comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) per creare una richiesta di metodo API `GET /greeting?greeter={name}`: ``` aws apigateway put-method --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --authorization-type "NONE" \ --request-parameters method.request.querystring.greeter=false ``` L'output sarà simile al seguente: ``` { "apiKeyRequired": false, "httpMethod": "GET", "authorizationType": "NONE", "requestParameters": { "method.request.querystring.greeter": false } } ``` Questo metodo API permette al client di ricevere una formula di saluto dalla funzione Lambda nel back-end. Il parametro `greeter` è facoltativo perché il back-end deve gestire un chiamante anonimo o un chiamante autoidentificato. 1. Utilizzate il seguente [put-method-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method-response.html)comando per impostare la `200 OK` risposta alla richiesta del metodo di`GET /greeting?greeter={name}`: ``` aws apigateway put-method-response \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --status-code 200 ``` 1. Utilizza il seguente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) per configurare l’integrazione del metodo `GET /greeting?greeter={name}` con una funzione Lambda denominata `HelloWorld`. La funzione risponde alla richiesta con un messaggio `"Hello, {name}!"` se è specificato il parametro `greeter`, altrimenti con `"Hello, World!"` se il parametro della stringa di query non è impostato. ``` aws apigateway put-integration \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --type AWS \ --integration-http-method POST \ --uri arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations \ --request-templates '{"application/json":"{\"greeter\":\"$input.params('greeter')\"}"}' \ --credentials arn:aws:iam::123456789012:role/apigAwsProxyRole ``` Il modello di mappatura fornito qui traduce il parametro della stringa di query `greeter` nella proprietà `greeter` del payload JSON. Questo è necessario perché l'input di una funzione Lambda deve essere espresso nel corpo. **Importante** Per le integrazioni Lambda, devi usare il metodo HTTP `POST` per la richiesta di integrazione, secondo la [specifica dell'operazione del servizio Lambda per le chiamate della funzione](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html). Il parametro `uri` è l'ARN dell'operazione di chiamata della funzione. L'output sarà simile al seguente: ``` { "passthroughBehavior": "WHEN_NO_MATCH", "cacheKeyParameters": [], "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:HelloWorld/invocations", "httpMethod": "POST", "requestTemplates": { "application/json": "{\"greeter\":\"$input.params('greeter')\"}" }, "cacheNamespace": "krznpq9xpg", "credentials": "arn:aws:iam::123456789012:role/apigAwsProxyRole", "type": "AWS" } ``` Il ruolo IAM `apigAwsProxyRole` deve includere policy che permettono al servizio `apigateway` di richiamare funzioni Lambda. Invece di specificare un ruolo IAM per `credentials`, puoi chiamare il comando [add-permission](https://docs.aws.amazon.com/cli/latest/reference/lambda/add-permission.html) per aggiungere autorizzazioni basate su risorse. Questo è il modo in cui la console API Gateway aggiunge queste autorizzazioni. 1. Utilizzate il [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)comando seguente per impostare la risposta di integrazione per passare l'output della funzione Lambda al client come risposta del `200 OK` metodo: ``` aws apigateway put-integration-response \ --rest-api-id te6si5ach7 \ --resource-id 2jf6xt \ --http-method GET \ --status-code 200 \ --selection-pattern "" ``` Impostando il modello di selezione su una stringa vuota, la risposta predefinita è `200 OK`. L'output sarà simile al seguente: ``` { "selectionPattern": "", "statusCode": "200" } ``` 1. Utilizza il seguente comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) per distribuire l’API in una fase `test`. ``` aws apigateway create-deployment \ --rest-api-id te6si5ach7 \ --stage-name test ``` 1. Testa l'API usando il comando cURL seguente in un terminale: ``` curl -X GET 'https://te6si5ach7.execute-api.us-west-2.amazonaws.com/test/greeting?greeter=me' \ -H 'authorization: AWS4-HMAC-SHA256 Credential={access_key}/20171020/us-west-2/execute-api/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=f327...5751' ``` # Configurazione della chiamata asincrona della funzione Lambda back-end Nell'integrazione non proxy (personalizzata) Lambda la funzione Lambda back-end viene richiamata in modo sincrono per impostazione predefinita. Questo è il comportamento desiderato per la maggior parte delle operazioni API REST. Alcune applicazioni, tuttavia, richiedono che la chiamata venga effettuata in modo asincrono, ad esempio un'operazione batch o una con latenza elevata, in genere da un componente di back-end separato. In questo caso, la funzione Lambda back-end viene richiamata in modo asincrono e il metodo API REST front-end non restituisce il risultato. Puoi configurare la funzione Lambda affinché un'integrazione non proxy Lambda venga richiamata in modo asincrono specificando `'Event'` come [tipo di chiamata Lambda](https://docs.aws.amazon.com/lambda/latest/dg/lambda-invocation.html). Questo avviene così: ## Configurazione della chiamata asincrona Lambda nella console API Gateway Affinché tutte le invocazioni siano asincrone: + In **Richiesta di integrazione** aggiungi un'intestazione `X-Amz-Invocation-Type` con un valore statico `'Event'`. Affinché i client decidano se le invocazioni sono asincrone o sincrone: 1. In **Richiesta metodo** aggiungi un'intestazione `InvocationType`. 1. In **Richiesta di integrazione** aggiungi un'intestazione `X-Amz-Invocation-Type` con un'espressione di mappatura `method.request.header.InvocationType`. 1. I client possono includere l'intestazione `InvocationType: Event` nelle richieste API per le invocazioni asincrone o `InvocationType: RequestResponse` per le invocazioni sincrone. ## Configurazione della chiamata asincrona Lambda utilizzando OpenAPI Affinché tutte le invocazioni siano asincrone: + Aggiungi l'`X-Amz-Invocation-Type`intestazione alla **x-amazon-apigateway-integration**sezione. ``` "x-amazon-apigateway-integration" : { "type" : "aws", "httpMethod" : "POST", "uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.X-Amz-Invocation-Type" : "'Event'" }, "passthroughBehavior" : "when_no_match", "contentHandling" : "CONVERT_TO_TEXT" } ``` Affinché i client decidano se le invocazioni sono asincrone o sincrone: 1. Aggiungi la seguente intestazione su qualsiasi [oggetto OpenAPI Path Item](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#pathItemObject). ``` "parameters" : [ { "name" : "InvocationType", "in" : "header", "schema" : { "type" : "string" } } ] ``` 1. Aggiungi l'`X-Amz-Invocation-Type`intestazione alla sezione. **x-amazon-apigateway-integration** ``` "x-amazon-apigateway-integration" : { "type" : "aws", "httpMethod" : "POST", "uri" : "arn:aws:apigateway:us-east-2:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-2:123456789012:function:my-function/invocations", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.X-Amz-Invocation-Type" : "method.request.header.InvocationType" }, "passthroughBehavior" : "when_no_match", "contentHandling" : "CONVERT_TO_TEXT" } ``` 1. I client possono includere l'intestazione `InvocationType: Event` nelle richieste API per le invocazioni asincrone o `InvocationType: RequestResponse` per le invocazioni sincrone. ## Configurare la chiamata asincrona Lambda utilizzando CloudFormation I seguenti CloudFormation modelli mostrano come configurare le chiamate asincrone. `AWS::ApiGateway::Method` Affinché tutte le invocazioni siano asincrone: ``` AsyncMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref AsyncResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS RequestParameters: integration.request.header.X-Amz-Invocation-Type: "'Event'" IntegrationResponses: - StatusCode: '200' IntegrationHttpMethod: POST Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations MethodResponses: - StatusCode: '200' ``` Affinché i client decidano se le invocazioni sono asincrone o sincrone: ``` AsyncMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref AsyncResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE RequestParameters: method.request.header.InvocationType: false Integration: Type: AWS RequestParameters: integration.request.header.X-Amz-Invocation-Type: method.request.header.InvocationType IntegrationResponses: - StatusCode: '200' IntegrationHttpMethod: POST Uri: !Sub arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${myfunction.Arn}$/invocations MethodResponses: - StatusCode: '200' ``` I client possono includere l'intestazione `InvocationType: Event` nelle richieste API per le invocazioni asincrone o `InvocationType: RequestResponse` per le invocazioni sincrone. # Gestione degli errori Lambda in API Gateway Per le integrazioni personalizzate Lambda, devi mappare gli errori restituiti da Lambda nella risposta di integrazione alle risposte di errore HTTP standard per i client. Altrimenti, gli errori Lambda vengono restituiti come risposte `200 OK` per impostazione predefinita e il risultato non è intuitivo per gli utenti dell'API. Esistono due tipi di errore che Lambda può restituire: errori standard ed errori personalizzati. Nella tua API, devi gestirli in modo diverso. Con l'integrazione proxy Lambda, Lambda deve restituire un output nel formato seguente: ``` { "isBase64Encoded" : "boolean", "statusCode": "number", "headers": { ... }, "body": "JSON string" } ``` In questo output, `statusCode` è in genere `4XX` per un errore del client e `5XX` per un errore del server. API Gateway gestisce questi errori mappando l'errore Lambda a una risposta di errore HTTP, in base al `statusCode` specificato. Affinché API Gateway passi il tipo di errore (ad esempio, `InvalidParameterException`), come parte della risposta al client, la funzione Lambda deve includere un'intestazione (ad esempio, `"X-Amzn-ErrorType":"InvalidParameterException"`) nella proprietà `headers`. **Topics** + [Gestione degli errori Lambda standard in API Gateway](#handle-standard-errors-in-lambda-integration) + [Gestione degli errori Lambda personalizzati in API Gateway](#handle-custom-errors-in-lambda-integration) ## Gestione degli errori Lambda standard in API Gateway Un AWS Lambda errore standard ha il seguente formato: ``` { "errorMessage": "string", "errorType": "string", "stackTrace": [ "string", ... ] } ``` Qui, `errorMessage` è un'espressione della stringa dell'errore. `errorType` è un tipo di eccezione o di errore dipendente dal linguaggio. `stackTrace` è un elenco di espressioni delle stringhe che mostrano la traccia dello stack che porta al verificarsi dell'errore. Ad esempio, si consideri la seguente JavaScript funzione Lambda (Node.js). ``` export const handler = function(event, context, callback) { callback(new Error("Malformed input ...")); }; ``` Questa funzione restituisce il seguente errore Lambda standard, contenente `Malformed input ...` come messaggio di errore: ``` { "errorMessage": "Malformed input ...", "errorType": "Error", "stackTrace": [ "export const handler (/var/task/index.js:3:14)" ] } ``` Allo stesso modo, considera la seguente funzione Python Lambda che genera un'eccezione `Exception` con lo stesso messaggio di errore `Malformed input ...`. ``` def lambda_handler(event, context): raise Exception('Malformed input ...') ``` La funzione restituisce il seguente errore Lambda standard: ``` { "stackTrace": [ [ "/var/task/lambda_function.py", 3, "lambda_handler", "raise Exception('Malformed input ...')" ] ], "errorType": "Exception", "errorMessage": "Malformed input ..." } ``` Da notare che i valori delle proprietà `errorType` e `stackTrace` dipendono dal linguaggio. L'errore standard si applica anche a qualsiasi oggetto di errore che è un'estensione dell'oggetto `Error` o una sottoclasse della classe `Exception`. Per mappare l'errore Lambda standard a una risposta del metodo, devi prima stabilire il codice di stato HTTP per un dato errore Lambda. Quindi impostate un modello di espressione regolare sulla `[selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern)` proprietà del codice di stato HTTP [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)associato al dato codice di stato HTTP. Nella console Gateway API, questo `selectionPattern` è indicato come **Espressione regolare errore Lambda** sotto ogni risposta di integrazione nella sezione **Risposta di integrazione**. **Nota** API Gateway usa le espressioni regolari basate sullo stile del modello Java per la mappatura della risposta. Per ulteriori informazioni, consulta [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) nella documentazione Oracle. Ad esempio, utilizzate quanto segue [put-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration-response.html)per impostare una nuova `selectionPattern` espressione: ``` aws apigateway put-integration-response --rest-api-id z0vprf0mdh --resource-id x3o5ih --http-method GET --status-code 400 --selection-pattern "Malformed.*" --region us-west-2 ``` Accertati di configurare anche il codice di errore corrispondente (`400`) sulla [risposta del metodo](api-gateway-method-settings-method-response.md#setup-method-response-status-code). Altrimenti, API Gateway restituisce una risposta di errore di configurazione non valida al runtime. **Nota** Al runtime, API Gateway abbina l'elemento `errorMessage` dell'errore Lambda al modello dell'espressione regolare per la proprietà `selectionPattern`. Se c'è una corrispondenza, API Gateway restituisce l'errore Lambda come risposta HTTP del codice di stato HTTP corrispondente. Se non c'è corrispondenza, API Gateway restituisce l'errore come risposta predefinita oppure genera un'eccezione di configurazione non valida se non è stata configurata una risposta predefinita. Impostare il valore `selectionPattern` su `.*` per una data risposta significa reimpostare questa risposta come risposta predefinita. Questo succede perché tale modello di selezione corrisponderà a tutti i messaggi di errore, incluso null, come, ad esempio, messaggi di errore non specificati. La mappatura che ne deriva sovrascrive la mappatura predefinita. Se si usa `.+` come modello di selezione per filtrare le risposte, potrebbe non corrispondere a una risposta contenente un carattere di nuova riga (’`\n`). Per aggiornare un `selectionPattern` valore esistente utilizzando AWS CLI, chiamate l'[update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)operazione per sostituire il valore del `/selectionPattern` percorso con l'espressione regex specificata del `Malformed*` pattern. Per impostare l'espressione `selectionPattern` tramite la console Gateway API, immetti l'espressione nella casella di testo **Espressione regolare errore Lambda** quando configuri o aggiorni una risposta di integrazione di un codice di stato HTTP specifico. ## Gestione degli errori Lambda personalizzati in API Gateway Invece dell'errore standard descritto nella sezione precedente, AWS Lambda consente di restituire un oggetto di errore personalizzato come stringa JSON. L'errore può essere qualsiasi oggetto JSON valido. Ad esempio, la seguente funzione Lambda JavaScript (Node.js) restituisce un errore personalizzato: ``` export const handler = (event, context, callback) => { ... // Error caught here: var myErrorObj = { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } callback(JSON.stringify(myErrorObj)); }; ``` Devi trasformare l'oggetto `myErrorObj` in una stringa JSON prima di chiamare `callback` per uscire dalla funzione. In caso contrario, viene restituito `myErrorObj` come stringa di `"[object Object]"`. Quando un metodo dell'API è integrato con la precedente funzione Lambda, API Gateway riceve una risposta di integrazione con il seguente payload: ``` { "errorMessage": "{\"errorType\":\"InternalServerError\",\"httpStatus\":500,\"requestId\":\"e5849002-39a0-11e7-a419-5bb5807c9fb2\",\"trace\":{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}}" } ``` Come nel caso delle risposte di integrazione, puoi passare questa risposta di errore invariata alla risposta di metodo. Oppure puoi avere un modello di mappatura per trasformare il payload in un formato diverso. Ad esempio, considera il seguente modello di mappatura del corpo per la risposta di un metodo del codice di stato `500`: ``` { errorMessage: $input.path('$.errorMessage'); } ``` Questo modello traduce il corpo della risposta di integrazione che contiene la stringa JSON di errore personalizzato nel corpo di risposta del metodo seguente. Questo corpo di risposta del metodo contiene un oggetto JSON di errore personalizzato: ``` { "errorMessage" : { errorType : "InternalServerError", httpStatus : 500, requestId : context.awsRequestId, trace : { "function": "abc()", "line": 123, "file": "abc.js" } } }; ``` In base ai tuoi requisiti API, potresti aver bisogno di passare alcune o tutte le proprietà degli errori personalizzati come parametri dell'intestazione della risposta di metodo. Puoi farlo applicando le mappature degli errori personalizzati dal corpo della risposta di integrazione alle intestazioni della risposta di metodo. Ad esempio, la seguente estensione OpenAPI definisce una mappatura dalle proprietà `errorMessage.errorType`, `errorMessage.httpStatus`, `errorMessage.trace.function` ed `errorMessage.trace` alle intestazioni `error_type`, `error_status`, `error_trace_function` ed `error_trace`, rispettivamente. ``` "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.error_trace_function": "integration.response.body.errorMessage.trace.function", "method.response.header.error_status": "integration.response.body.errorMessage.httpStatus", "method.response.header.error_type": "integration.response.body.errorMessage.errorType", "method.response.header.error_trace": "integration.response.body.errorMessage.trace" }, ... } } } ``` Al runtime, API Gateway deserializza il parametro `integration.response.body` nel corso delle mappature delle intestazioni. Tuttavia, questa deserializzazione si applica solo alle body-to-header mappature per le risposte di errore personalizzate Lambda e non si applica alle mappature che utilizzano. body-to-body `$input.body` Con queste mappature custom-error-body-to -header, il client riceve le seguenti intestazioni come parte della risposta del metodo, a condizione che,, e le intestazioni siano dichiarate nella richiesta del `error_status` metodo. `error_trace` `error_trace_function` `error_type` ``` "error_status":"500", "error_trace":"{\"function\":\"abc()\",\"line\":123,\"file\":\"abc.js\"}", "error_trace_function":"abc()", "error_type":"InternalServerError" ``` La proprietà `errorMessage.trace` del corpo della risposta di integrazione è una proprietà complessa. Viene mappata all'intestazione `error_trace` come una stringa JSON. # Integrazioni HTTP per REST APIs in API Gateway Puoi integrare un metodo API con un endpoint HTTP tramite l'integrazione proxy di HTTP o l'integrazione personalizzata di HTTP. API Gateway supporta le seguenti porte dell'endpoint: 80, 443 e 1024-65535. Con l'integrazione proxy la configurazione è semplice. Devi solo impostare il metodo HTTP e l'URI dell'endpoint HTTP, in base ai requisiti del back-end, se non sei interessato alla codifica o al caching dei contenuti. Con l'integrazione personalizzata la configurazione è più complessa. Oltre alla procedura di configurazione dell'integrazione proxy, devi specificare come verranno mappati i dati della richiesta in ingresso alla richiesta di integrazione e i dati della risposta di integrazione risultante alla risposta del metodo. **Topics** + [Configurazione di integrazioni proxy HTTP in API Gateway](#api-gateway-set-up-http-proxy-integration-on-proxy-resource) + [Configurazione di integrazioni personalizzate HTTP in API Gateway](#set-up-http-custom-integrations) ## Configurazione di integrazioni proxy HTTP in API Gateway Per configurare una risorsa proxy con il tipo di integrazione proxy HTTP, crea una risorsa API con un parametro di percorso greedy, ad esempio `/parent/{proxy+}`, e integra la risorsa con un endpoint di back-end HTTP, ad esempio `https://petstore-demo-endpoint.execute-api.com/petstore/{proxy}`, nel metodo `ANY`. Il parametro di percorso greedy deve trovarsi alla fine del percorso della risorsa. Come per una risorsa non proxy, puoi configurare una risorsa proxy con l'integrazione proxy HTTP usando la console API Gateway, importando un file di definizione OpenAPI o chiamando direttamente l'API REST di API Gateway. Per istruzioni dettagliate sull'uso della console API Gateway per configurare una risorsa proxy con l'integrazione HTTP, consulta [Tutorial: creazione di una REST API con l'integrazione proxy HTTP](api-gateway-create-api-as-simple-proxy-for-http.md). Il seguente file di definizione OpenAPI mostra un esempio di API con una risorsa proxy integrata con il [PetStore](http://petstore-demo-endpoint.execute-api.com/petstore/pets)sito Web. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "parameters": [ { "name": "proxy", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } }, "servers": [ { "url": "https://4z9giyi2c1.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/test" } } } ] } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-09-12T23:19:28Z", "title": "PetStoreWithProxyResource" }, "host": "4z9giyi2c1.execute-api.us-east-1.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/{proxy+}": { "x-amazon-apigateway-any-method": { "produces": [ "application/json" ], "parameters": [ { "name": "proxy", "in": "path", "required": true, "type": "string" } ], "responses": {}, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.proxy": "method.request.path.proxy" }, "uri": "http://petstore-demo-endpoint.execute-api.com/petstore/{proxy}", "passthroughBehavior": "when_no_match", "httpMethod": "ANY", "cacheNamespace": "rbftud", "cacheKeyParameters": [ "method.request.path.proxy" ], "type": "http_proxy" } } } } } ``` ------ In questo esempio, viene dichiarata una chiave cache nel parametro del percorso `method.request.path.proxy` della risorsa proxy. Questa è l'impostazione predefinita quando crei l'API tramite la console API Gateway. Il percorso di base dell'API (`/test`corrispondente a una fase) è mappato alla PetStore pagina del sito Web (`/petstore`). La singola richiesta di integrazione rispecchia l'intero PetStore sito Web utilizzando la variabile greedy path dell'API e il metodo `ANY` catch-all. Negli esempi seguenti viene illustrato questo mirroring. + **Imposta `ANY` come `GET` e `{proxy+}` come `pets`** Richiesta di metodo iniziata dal front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 ``` Richiesta di integrazione inviata al back-end: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 ``` Le istanze run-time del metodo `ANY` e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta `200 OK` con il payload contenente il primo batch di animali, nel modo in cui viene restituito dal back-end. + **Imposta `ANY` come `GET` e `{proxy+}` come `pets?type=dog`** ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets?type=dog HTTP/1.1 ``` Richiesta di integrazione inviata al back-end: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets?type=dog HTTP/1.1 ``` Le istanze run-time del metodo `ANY` e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta `200 OK` con il payload contenente il primo batch di cani specifici, nel modo in cui viene restituito dal back-end. + **Imposta `ANY` come `GET` e `{proxy+}` come `pets/{petId}`** Richiesta di metodo iniziata dal front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/1 HTTP/1.1 ``` Richiesta di integrazione inviata al back-end: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/1 HTTP/1.1 ``` Le istanze run-time del metodo `ANY` e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta `200 OK` con il payload contenente l'animale specificato, nel modo in cui viene restituito dal back-end. + **Imposta `ANY` come `POST` e `{proxy+}` come `pets`** Richiesta di metodo iniziata dal front-end: ``` POST https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 } ``` Richiesta di integrazione inviata al back-end: ``` POST http://petstore-demo-endpoint.execute-api.com/petstore/pets HTTP/1.1 Content-Type: application/json Content-Length: ... { "type" : "dog", "price" : 1001.00 } ``` Le istanze run-time del metodo `ANY` e le risorse proxy sono entrambe valide. La chiamata restituisce una risposta `200 OK` con il payload contenente il nuovo animale creato, nel modo in cui viene restituito dal back-end. + **Imposta `ANY` come `GET` e `{proxy+}` come `pets/cat`** Richiesta di metodo iniziata dal front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test/pets/cat ``` Richiesta di integrazione inviata al back-end: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets/cat ``` L'istanza run-time del percorso della risorsa del proxy non corrisponde all'endpoint di un back-end e la relativa richiesta non è valida. Di conseguenza, viene restituita una risposta `400 Bad Request` con il seguente messaggio di errore. ``` { "errors": [ { "key": "Pet2.type", "message": "Missing required field" }, { "key": "Pet2.price", "message": "Missing required field" } ] } ``` + **Imposta `ANY` come `GET` e `{proxy+}` come `null`** Richiesta di metodo iniziata dal front-end: ``` GET https://4z9giyi2c1.execute-api.us-west-2.amazonaws.com/test ``` Richiesta di integrazione inviata al back-end: ``` GET http://petstore-demo-endpoint.execute-api.com/petstore/pets ``` La risorsa di destinazione è il padre della risorsa del proxy, ma l'istanza run-time del metodo `ANY` non è definita nell'API di quella risorsa. Di conseguenza, la richiesta `GET` restituisce una risposta `403 Forbidden` con il messaggio di errore `Missing Authentication Token` restituito da API Gateway. Se l'API espone il metodo `ANY` o `GET` alla risorsa padre (`/`), la chiamata restituisce una risposta `404 Not Found` con il messaggio `Cannot GET /petstore` restituito dal back-end. Per qualsiasi richiesta del client, se l'URL dell'endpoint di destinazione non è valido o il verbo HTTP è valido ma non è supportato, il back-end restituisce una risposta `404 Not Found`. Per un metodo HTTP non supportato, viene restituita una risposta `403 Forbidden`. ## Configurazione di integrazioni personalizzate HTTP in API Gateway Con l’integrazione HTTP personalizzata, conosciuta anche come integrazione non proxy, si ha più controllo su quali dati passare tra un metodo API e un’integrazione API e su come passarli. Puoi fare questo utilizzando le mappature dei dati. Come parte della configurazione della richiesta del metodo, imposti la proprietà [requestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html#requestParameters) su una risorsa [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html). Questo dichiara quali parametri della richiesta di metodo, forniti dal client, devono essere mappati ai parametri di richiesta di integrazione o alle proprietà del corpo applicabili prima di essere inviati al back-end. Quindi, come parte della configurazione della richiesta di integrazione, impostate la proprietà [RequestParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestParameters) sulla risorsa di [integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) corrispondente per specificare le parameter-to-parameter mappature. Imposti inoltre la proprietà [requestTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#requestTemplates) per specificare i modelli di mappatura, uno per ogni tipo di contenuto supportato. I modelli di mappatura mappano i parametri della richiesta di metodo, o il corpo, al corpo della richiesta di integrazione. Analogamente, come parte della configurazione della risposta del metodo, impostate la proprietà [ResponseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html#responseParameters) sulla risorsa. [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) Questo dichiara quali parametri della risposta di metodo, da inviare al client, devono essere mappati dai parametri della risposta di integrazione o da alcune proprietà del corpo applicabili restituite dal back-end. Quindi si configura [selectionPattern](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#selectionPattern) per scegliere una risposta di integrazione basata sulla risposta del backend. Per un’integrazione HTTP non proxy, si tratta di un’espressione regolare. Ad esempio, per mappare tutti i codici di stato delle risposte HTTP 2xx da un endpoint HTTP a questa mappatura di output, si usa `2\d{2}`. **Nota** API Gateway usa le espressioni regolari basate sullo stile del modello Java per la mappatura della risposta. Per ulteriori informazioni, consulta [Pattern](https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) nella documentazione Oracle. Quindi, come parte della configurazione della risposta di integrazione, impostate la proprietà [ResponseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseParameters) sulla risorsa [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)corrispondente per specificare le mappature. parameter-to-parameter Imposti inoltre la mappa [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html#responseTemplates) per specificare i modelli di mappatura, uno per ogni tipo di contenuto supportato. I modelli di mappatura mappano i parametri della risposta di integrazione, o le proprietà del corpo della risposta di integrazione, al corpo della risposta del metodo. Per ulteriori informazioni sulla configurazione dei modelli di mappatura, consulta [Trasformazioni dei dati per REST APIs in API Gateway](rest-api-data-transformations.md). # Trasmetti in streaming la risposta di integrazione per le integrazioni proxy in API Gateway Puoi configurare l’integrazione del proxy per controllare in che modo API Gateway restituisce la tua risposta di integrazione. Per impostazione predefinita, API Gateway attende di ricevere la risposta completa prima di iniziare la trasmissione. Tuttavia, se imposti la modalità di trasferimento delle risposte dell'integrazione su`STREAM`, API Gateway non attende che una risposta sia completamente calcolata prima di inviarla al client. Lo streaming di risposte funziona per tutti i tipi di endpoint di REST API. Utilizza lo streaming di risposte per i seguenti casi d'uso: + Riduci il time-to-first-byte valore (TTFB) per le applicazioni di intelligenza artificiale generativa come i chatbot. + Trasmetti in streaming immagini, video o file musicali di grandi dimensioni senza utilizzare un URL prefirmato S3. + Esegui operazioni di lunga durata segnalando progressi incrementali come gli eventi inviati dal server (SSE). + Supera il limite di payload di risposta di 10 MB di API Gateway. + Supera il limite di timeout di 29 secondi di API Gateway senza richiedere un aumento del limite di timeout di integrazione. + Ricevi un payload binario senza configurare i tipi di supporti binari. ## Considerazioni sullo streaming del payload di risposta Le seguenti considerazioni potrebbero influire sull'utilizzo dello streaming di payload di risposta: + È possibile utilizzare lo streaming di payload di risposta solo per i `HTTP_PROXY` tipi di integrazione. `AWS_PROXY` Ciò include le integrazioni proxy Lambda e le integrazioni private che utilizzano integrazioni. `HTTP_PROXY` + L'impostazione predefinita della modalità di trasferimento è. `BUFFERED` Per utilizzare lo streaming di risposta, è necessario modificare la modalità di trasferimento della risposta in`STREAM`. + Lo streaming di risposte è supportato solo per REST APIs. + Lo streaming delle richieste non è supportato. + Puoi trasmettere in streaming la tua risposta per un massimo di 15 minuti. + I tuoi stream sono soggetti a timeout di inattività. Per gli endpoint regionali o privati, il timeout è di 5 minuti. Per gli endpoint ottimizzati per l'edge, il timeout è di 30 secondi. + Se utilizzi lo streaming di risposta per un'API REST regionale con la tua CloudFront distribuzione, puoi ottenere un timeout di inattività superiore a 30 secondi aumentando il timeout di risposta della tua distribuzione. CloudFront Per ulteriori informazioni, consulta Timeout di [risposta](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/DownloadDistValuesOrigin.html#DownloadDistValuesOriginResponseTimeout). + Quando la modalità di trasferimento della risposta è impostata su`STREAM`, API Gateway non può supportare funzionalità che richiedono il buffering dell'intera risposta di integrazione. Per questo motivo, le seguenti funzionalità non sono supportate con lo streaming di risposta: + Memorizzazione nella cache degli endpoint + Codifica dei contenuti. Se desideri comprimere la tua risposta di integrazione, esegui questa operazione nella tua integrazione. + Trasformazione della risposta con VTL + All'interno di ogni risposta in streaming, i primi 10 MB di payload di risposta non sono soggetti ad alcuna restrizione di larghezza di banda. I dati di payload di risposta superiori a 10 MB sono limitati a 2 MB/s. + Quando la connessione tra il client e API Gateway o tra API Gateway e Lambda viene chiusa a causa di un timeout, la funzione Lambda potrebbe continuare a essere eseguita. Per ulteriori informazioni, consulta [Configurare il timeout della funzione Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + Lo streaming delle risposte comporta un costo. Per ulteriori informazioni, consulta [Prezzi di API Gateway](https://aws.amazon.com/api-gateway/pricing/). # Configura un'integrazione proxy HTTP con lo streaming di risposta del payload in API Gateway Quando si configura lo streaming del payload di risposta, si specifica la modalità di trasferimento della risposta nella richiesta di integrazione del metodo. Queste impostazioni vengono configurate nella richiesta di integrazione per controllare il comportamento di API Gateway prima e durante la risposta di integrazione. Quando utilizzi lo streaming di risposte, puoi configurare il timeout di integrazione fino a 15 minuti. Quando utilizzi lo streaming di risposta del payload con un'`HTTP_PROXY`integrazione, API Gateway non invia il codice di stato della risposta HTTP o alcuna intestazione di risposta HTTP finché non riceve completamente tutte le intestazioni. ## Crea un'integrazione proxy HTTP con lo streaming di risposta del payload La procedura seguente mostra come importare una nuova API con l'`responseTransferMode`impostazione su. `STREAM` Se disponi di un'API di integrazione esistente e desideri modificarla`responseTransferMode`, consulta[Aggiorna la modalità di trasferimento delle risposte per un'integrazione con proxy HTTP](#response-streaming-http-update). ------ #### [ Console di gestione AWS ] **Per creare un'integrazione proxy HTTP con lo streaming di risposta del payload** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegli **Crea risorsa**. 1. Per **Resource Name (Nome risorsa)** immetti **streaming**. 1. Scegli **Crea risorsa**. 1. **Con la risorsa **/streaming** selezionata, scegli il metodo Create.** 1. Per **Tipo di metodo**, scegliete **QUALSIASI**. 1. Per **Tipo di integrazione** scegli **Fittizio**. 1. Scegli l'**integrazione con il proxy HTTP**. 1. Per la **modalità di trasferimento Response**, scegli **Stream**. 1. Per il **metodo HTTP**, scegliete un metodo. 1. Per **Endpoint URL**, inserisci un endpoint di integrazione. Assicurati di scegliere un endpoint che produca un payload di grandi dimensioni da trasmettere in streaming. 1. Scegli **Crea metodo**. Dopo aver creato il metodo, implementa l'API. **Per distribuire l'API** 1. Seleziona **Deploy API (Distribuisci API)**. 1. In **Fase**, seleziona **Nuova fase**. 1. In **Stage name (Nome fase)** immettere **prod**. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. Seleziona **Implementa**. ------ #### [ AWS CLI ] **Per creare una nuova API con streaming di risposta al payload** 1. Copia il seguente file Open API, quindi salvalo con nome. `ResponseStreamDemoSwagger.yaml` In questo file, `responseTransferMode` è impostato su`STREAM`. L'endpoint di integrazione è impostato su`https://example.com`, ma ti consigliamo di modificarlo su un endpoint che produca un payload di grandi dimensioni da trasmettere in streaming. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /streaming: get: x-amazon-apigateway-integration: httpMethod: "GET" uri: "https://example.com" type: "http_proxy" timeoutInMillis: 900000 responseTransferMode: "STREAM" ``` 1. Usa il seguente `import-rest-api` comando per importare la tua definizione OpenAPI: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Usa il seguente `create-deployment` comando per distribuire la tua nuova API in una fase: ``` aws apigateway create-deployment \ --rest-api-id a1b2c3 \ --stage-name prod \ --region us-west-1 ``` ------ ## Aggiorna la modalità di trasferimento delle risposte per un'integrazione con proxy HTTP La procedura seguente mostra come aggiornare la modalità di trasferimento della risposta per un'integrazione con proxy HTTP. ------ #### [ Console di gestione AWS ] **Per aggiornare la modalità di trasferimento delle risposte per un'integrazione con proxy HTTP** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere un metodo. 1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**. 1. **Per la **modalità di trasferimento Response**, scegli Stream.** 1. Scegli **Save** (Salva). Dopo aver aggiornato il metodo, distribuisci l'API. **Per distribuire l'API** 1. Seleziona **Deploy API (Distribuisci API)**. 1. In **Fase**, seleziona **Nuova fase**. 1. In **Stage name (Nome fase)** immettere **prod**. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. Seleziona **Implementa**. ------ #### [ AWS CLI ] Il `update-integration` comando seguente aggiorna la modalità di trasferimento di un'integrazione da `BUFFERED` a`STREAM`. Per tutte le integrazioni esistenti APIs, la modalità di trasferimento della risposta per tutte le integrazioni è impostata su. `BUFFERED` ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=STREAM" \ --region us-west-1 ``` È necessario ridistribuire l'API per rendere effettive le modifiche. Se hai personalizzato il timeout di integrazione, questo valore di timeout viene rimosso, poiché API Gateway trasmette la tua risposta per un massimo di 5 minuti. Il `update-integration` comando seguente aggiorna la modalità di trasferimento di un'integrazione da a: `STREAM` `BUFFERED` ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method GET \ --patch-operations "op='replace',path='/responseTransferMode',value=BUFFERED" \ --region us-west-1 ``` È necessario ridistribuire l'API per rendere effettive le modifiche. ------ # Configura l'integrazione di un proxy Lambda con lo streaming della risposta del payload in API Gateway Puoi trasmettere in streaming la risposta di una funzione Lambda per migliorare le prestazioni del time-to-first byte (TTFB) e inviare risposte parziali al client non appena diventano disponibili. API Gateway richiede l'utilizzo dell'API [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)Lambda per richiamare la funzione Lambda. API Gateway passa un oggetto evento alla funzione Lambda. La funzione Lambda back-end analizza i dati delle richieste in entrata per stabilire la risposta da restituire. Affinché API Gateway possa trasmettere l'output Lambda, la funzione Lambda deve restituire il [formato](#response-transfer-mode-lambda-format) richiesto da API Gateway. ## Differenze nelle integrazioni del proxy Lambda tra la modalità di trasferimento di risposta in streaming e bufferizzata L'elenco seguente descrive le differenze tra un'integrazione con proxy Lambda e un'integrazione con proxy Lambda per lo streaming di risposte: + API Gateway utilizza l'[InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)API per richiamare l'integrazione del proxy Lambda per lo streaming delle risposte. Ciò si traduce in un URI diverso, che è il seguente: ``` arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations ``` Questo ARN utilizza una data diversa per la versione dell'API e un'azione di servizio diversa rispetto all'integrazione del proxy Lambda. Se utilizzi la console API Gateway per lo streaming delle risposte, la console utilizza l'URI corretto per te. + In un'integrazione con proxy Lambda, API Gateway invia la risposta al client solo dopo aver ricevuto la risposta completa da Lambda. In un'integrazione proxy Lambda per lo streaming di risposte, API Gateway avvia il flusso di payload dopo aver ricevuto i metadati e il delimitatore validi da Lambda. + L'integrazione del proxy Lambda per lo streaming di risposte utilizza lo stesso formato di input dell'integrazione proxy, ma richiede un formato di output diverso. ## Formato di integrazione proxy Lambda per lo streaming delle risposte Quando API Gateway richiama una funzione Lambda con streaming di risposte, il formato di input è lo stesso di quello di una funzione Lambda per l'integrazione del proxy. Per ulteriori informazioni, consulta [Formato di input di una funzione Lambda per l'integrazione proxy](set-up-lambda-proxy-integrations.md#api-gateway-simple-proxy-for-lambda-input-format). Quando Lambda invia una risposta a API Gateway, la risposta deve rispettare il seguente formato. Questo formato utilizza un delimitatore per separare i metadati JSON dal payload non elaborato. In questo caso, i dati del payload vengono trasmessi in streaming man mano che vengono trasmessi dalla funzione di streaming Lambda: ``` { "headers": {"headerName": "headerValue", ...}, "multiValueHeaders": { "headerName": ["headerValue", "headerValue2", ...], ... }, "cookies" : ["cookie1", "cookie2"], "statusCode": httpStatusCode }PAYLOAD1 | PAYLOAD2 | PAYLOAD3 ``` Nell'output: + Le `statusCode` chiavi`headers`, `multiValueHeaders``cookies`, e possono non essere specificate se non devono essere restituite intestazioni di risposta aggiuntive. + La chiave `headers` può contenere solo una decina di intestazioni di valore. + L'output prevede che le intestazioni contengano o. `Transfer-Encoding: chunked` `Content-length: number` Se la funzione non restituisce nessuna di queste intestazioni, API Gateway viene aggiunta `Transfer-Encoding: chunked` all'intestazione della risposta. + La chiave `multiValueHeaders` può contenere intestazioni multi-valore e il valore di una decina di intestazioni. È possibile utilizzare la chiave `multiValueHeaders` per specificare tutte le intestazioni aggiuntive, incluse quelle con valore singolo. + Se si specificano valori sia per `headers` che per `multiValueHeaders`, API Gateway li unisce in un unico elenco. Se la stessa coppia chiave-valore viene specificata in entrambi, solo i valori di `multiValueHeaders` verranno visualizzati nell'elenco risultante. + I metadati devono essere in formato JSON valido. Solo `headers``multiValueHeaders`, `cookies` e le `statusCode` chiavi sono supportate. + È necessario fornire un delimitatore dopo i metadati JSON. Il delimitatore deve essere composto da 8 byte nulli e deve apparire all'interno dei primi 16 KB di dati di flusso. + API Gateway non richiede un formato specifico per il payload di risposta del metodo. Se utilizzi l'URL di una funzione per lo streaming della tua funzione Lambda, devi modificare l'input e l'output della funzione Lambda per soddisfare questi requisiti. Se l'output della funzione Lambda non soddisfa i requisiti di questo formato, API Gateway potrebbe comunque richiamare la funzione Lambda. La tabella seguente mostra le combinazioni delle impostazioni della richiesta di integrazione API e del codice della funzione Lambda supportato da API Gateway. Ciò include le combinazioni supportate per la modalità di trasferimento della risposta in modalità buffered. | Modalità di trasferimento della risposta | Il codice della funzione è conforme al formato richiesto | API di richiamo Lambda | Supportato da API Gateway | | --- | --- | --- | --- | | Flusso | Sì | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | Sì. API Gateway trasmette la tua risposta. | | Flusso | No | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway richiama la funzione Lambda e restituisce una risposta di errore 500. | | Flusso | Sì | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | No. API Gateway non supporta questa configurazione di integrazione. | | Flusso | No | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | No. API Gateway non supporta questa configurazione di integrazione. | | Bufferato | Sì | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway non supporta questa configurazione di integrazione. | | Bufferato | No | [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html) | No. API Gateway non supporta questa configurazione di integrazione. | | Bufferato | Sì | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | API Gateway restituisce le intestazioni HTTP e il codice di stato ma non il corpo della risposta. | | Bufferato | No | [Invoke](https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html) | Sì. Si tratta di un'integrazione proxy Lambda. Per ulteriori informazioni, consulta Integrazione del [proxy Lambda](set-up-lambda-proxy-integrations.md). | # Configura l'integrazione di un proxy Lambda con lo streaming della risposta del payload in API Gateway Quando configuri lo streaming del payload di risposta, specifichi la modalità di trasferimento nella richiesta di integrazione della risorsa. Queste impostazioni vengono configurate nella richiesta di integrazione per controllare il comportamento di API Gateway prima e durante la risposta di integrazione. ## Esempi di funzioni Lambda per lo streaming delle risposte La tua funzione Lambda deve rispettare il. [Formato di integrazione proxy Lambda per lo streaming delle risposte](response-transfer-mode-lambda.md#response-transfer-mode-lambda-format) Ti consigliamo di utilizzare una delle tre funzioni Lambda di esempio per testare lo streaming delle risposte. Quando crei la tua funzione Lambda, assicurati di fare quanto segue: + Fornisci un timeout adeguato per la tua funzione. Ti consigliamo di configurare un timeout di almeno 1 minuto per conoscere lo streaming di risposte. Quando crei le tue risorse di produzione, assicurati che il timeout della funzione Lambda copra l'intero ciclo di richiesta. Per ulteriori informazioni, consulta [Configurare il timeout della funzione Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). + Usa il runtime Node.js più recente. + Usa una regione in cui è disponibile lo streaming di risposta Lambda. ------ #### [ Using HttpResponseStream.from ] Il seguente esempio di codice trasmette gli oggetti di metadati e i payload JSON al client utilizzando il `awslambda.HttpResponseStream()` metodo senza utilizzare il metodo pipeline. Non è necessario creare il delimitatore. Per ulteriori informazioni, consulta [Scrittura di funzioni Lambda abilitate allo streaming di risposte](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). ``` export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { "statusCode": 200, "headers": { "x-foo": "bar" }, "multiValueHeaders": { "x-mv1": ["hello", "world"], "Set-Cookie": ["c1=blue", "c2=red"] } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("First payload "); await new Promise(r => setTimeout(r, 1000)); // synthetic delay responseStream.write("Final payload"); responseStream.end(); }); ``` ------ #### [ Using the pipeline method ] Lambda consiglia, quando si scrivono funzioni abilitate allo streaming di risposte, di utilizzare il `awslambda.streamifyResponse()` decoratore fornito dai runtime nativi di Node.js e il metodo. `pipeline()` Quando usi il metodo pipeline, non è necessario creare il delimitatore, Lambda lo fa per te. Per ulteriori informazioni, consulta [Scrittura di funzioni Lambda abilitate allo streaming di risposte](https://docs.aws.amazon.com/lambda/latest/dg/config-rs-write-functions.html). Il seguente esempio di codice invia gli oggetti di metadati JSON e tre payload al client. ``` import { pipeline } from 'node:stream/promises'; import { Readable } from 'node:stream'; export const handler = awslambda.streamifyResponse( async (event, responseStream, context) => { const httpResponseMetadata = { statusCode: 200, headers: { "Content-Type": "text/plain", "X-Custom-Header": "Example-Custom-Header" } }; responseStream = awslambda.HttpResponseStream.from(responseStream, httpResponseMetadata); const dataStream = Readable.from(async function* () { yield "FIRST payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "SECOND payload\n"; await new Promise(r => setTimeout(r, 1000)); yield "THIRD payload\n"; await new Promise(r => setTimeout(r, 1000)); }()); await pipeline(dataStream, responseStream); } ); ``` ------ #### [ Without using the pipeline method ] Il seguente esempio di codice invia gli oggetti di metadati JSON e tre payload al client senza utilizzare il metodo. `awslambda.HttpResponseStream()` Senza il `awslambda.HttpResponseStream()` metodo, è necessario includere un delimitatore di 8 byte nulli tra i metadati e il payload. ``` export const handler = awslambda.streamifyResponse(async (event, response, ctx) => { response.write('{"statusCode": 200, "headers": {"hdr-x": "val-x"}}'); response.write("\x00".repeat(8)); // DELIMITER await new Promise(r => setTimeout(r, 1000)); response.write("FIRST payload"); await new Promise(r => setTimeout(r, 1000)); response.write("SECOND payload"); await new Promise(r => setTimeout(r, 1000)); response.write("FINAL payload"); response.end(); }); ``` ------ ## Crea un'integrazione proxy Lambda con lo streaming di risposta del payload La procedura seguente mostra come creare un'integrazione proxy Lambda con lo streaming di risposta del payload. Usa la funzione Lambda di esempio o creane una tua. ------ #### [ Console di gestione AWS ] **Per creare un'integrazione proxy Lambda con lo streaming di risposta del payload** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegli **Crea risorsa**. 1. Per **Resource Name (Nome risorsa)** immetti **streaming**. 1. Scegli **Crea risorsa**. 1. **Con la risorsa **/streaming** selezionata, scegli il metodo Create.** 1. Per **Tipo di metodo**, scegliete **QUALSIASI**. 1. Per **Tipo di integrazione**, scegli **Lambda**. 1. Scegli l'integrazione con **proxy Lambda**. 1. Per la **modalità di trasferimento Response**, scegli **Stream**. 1. Per la **funzione Lambda**, scegli il nome della tua funzione Lambda. La console API Gateway utilizza automaticamente [InvokeWithResponseStream](https://docs.aws.amazon.com/lambda/latest/api/API_InvokeWithResponseStream.html)l'API per richiamare la funzione Lambda. Sei responsabile della scrittura di una funzione Lambda abilitata per lo streaming di risposte. Per vedere un esempio, consulta [Esempi di funzioni Lambda per lo streaming delle risposte](#response-streaming-lambda-example). 1. Scegli **Crea metodo**. Dopo aver creato il metodo, distribuisci l'API. **Per distribuire l'API** 1. Seleziona **Deploy API (Distribuisci API)**. 1. In **Fase**, seleziona **Nuova fase**. 1. In **Stage name (Nome fase)** immettere **prod**. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. Seleziona **Implementa**. ------ #### [ AWS CLI ] La procedura seguente mostra come importare una nuova API con l'`responseTransferMode`impostazione su. `STREAM` Se disponi di un'API di integrazione esistente e desideri modificarla`responseTransferMode`, consulta[Aggiorna la modalità di trasferimento delle risposte per un'integrazione con proxy Lambda](#response-streaming-lambda-update). **Per creare una nuova API con streaming di risposta al payload** 1. Copia il seguente file Open API, quindi salvalo con nome. `ResponseStreamDemoSwagger.yaml` In questo file, `responseTransferMode` è impostato `STREAM` su e l'URI di integrazione è impostato su`arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations`. Sostituisci il nome della funzione `my-function` con una funzione abilitata allo streaming e sostituisci le credenziali con un ruolo IAM dotato di policy che consentono al `apigateway` servizio di richiamare le funzioni Lambda. ``` openapi: "3.0.1" info: title: "ResponseStreamingDemo" version: "2025-04-28T17:28:25Z" servers: - url: "{basePath}" variables: basePath: default: "prod" paths: /lambda: get: x-amazon-apigateway-integration: httpMethod: "POST" uri: "arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations" type: "aws_proxy" timeoutInMillis: 90000 responseTransferMode: "STREAM" credentials: "arn:aws:iam::111122223333:role/apigateway-lambda-role" ``` Invece di fornire un ruolo IAM per le credenziali, puoi utilizzare il `add-permission` comando per Lambda per aggiungere autorizzazioni basate sulle risorse. 1. Usa il seguente `import-rest-api` comando per importare la tua definizione OpenAPI: ``` aws apigateway import-rest-api \ --body 'fileb://~/ResponseStreamDemoSwagger.yaml' \ --parameters endpointConfigurationTypes=REGIONAL \ --region us-west-1 ``` 1. Usa il seguente `create-deployment` comando per distribuire la tua nuova API in una fase: ``` aws apigateway create-deployment \ --rest-api-id a1b2c2 \ --stage-name prod \ --region us-west-1 ``` ------ ### Aggiorna la modalità di trasferimento delle risposte per un'integrazione con proxy Lambda La procedura seguente mostra come aggiornare la modalità di trasferimento delle risposte per un'integrazione proxy Lambda. Quando modifichi la modalità di trasferimento della risposta in streaming, aggiorna la funzione Lambda in modo che soddisfi i requisiti per lo streaming di risposta. Usa la funzione Lambda di esempio o creane una tua. ------ #### [ Console di gestione AWS ] **Per aggiornare la modalità di trasferimento delle risposte per l'integrazione di un proxy Lambda** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere un metodo. 1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**. 1. **Per la **modalità di trasferimento Response**, scegli Stream.** 1. Per la **funzione Lambda**, scegli il nome della tua funzione Lambda. 1. Scegli **Save** (Salva). Dopo aver aggiornato il metodo, distribuisci l'API. **Per distribuire l'API** 1. Seleziona **Deploy API (Distribuisci API)**. 1. In **Fase**, seleziona **Nuova fase**. 1. In **Stage name (Nome fase)** immettere **prod**. 1. (Facoltativo) In **Descrizione**, immetti una descrizione. 1. Seleziona **Implementa**. ------ #### [ AWS CLI ] 1. Aggiorna la tua funzione Lambda in modo che sia abilitata allo streaming. 1. Usa il seguente AWS CLI comando per aggiornare l'URI di integrazione e la modalità di trasferimento delle risposte della tua integrazione: ``` aws apigateway update-integration \ --rest-api-id a1b2c3 \ --resource-id aaa111 \ --http-method ANY \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"arn:aws:apigateway:us-west-1:lambda:path/2021-11-15/functions/arn:aws:lambda:us-west-1:111122223333:function:my-function-name/response-streaming-invocations\"}, {\"op\":\"replace\",\"path\":\"/responseTransferMode\",\"value\":\"STREAM\"}]" \ --region us-west-1 ``` 1. Implementa nuovamente l'API per rendere effettive le modifiche. ------ # Risolvi i problemi relativi allo streaming delle risposte in API Gateway La seguente guida per la risoluzione dei problemi potrebbe aiutare a risolvere i problemi relativi allo streaming di risposta APIs che utilizza. ## Risoluzione dei problemi generali Puoi utilizzare la scheda di test [TestInvokeMethod](https://docs.aws.amazon.com/apigateway/latest/api/API_TestInvokeMethod.html)o la scheda di test della console per testare la risposta dello stream. Le seguenti considerazioni potrebbero influire sull'utilizzo di test invoke per lo streaming di risposte: + Quando testate il vostro metodo, API Gateway memorizza nel buffer il payload di risposta in streaming. Una volta soddisfatta una delle seguenti condizioni, API Gateway restituisce una risposta unica contenente il payload bufferizzato: + La richiesta è completa + Sono trascorsi 35 secondi + È stato memorizzato nel buffer più di 1 MB di payload di risposta + Se trascorrono più di 35 secondi prima che il metodo restituisca lo stato di risposta HTTP e tutte le intestazioni, lo stato della risposta restituito è 0. TestInvokeMethod + API Gateway non produce alcun log di esecuzione. Dopo aver distribuito l'API, puoi testare la risposta dello stream utilizzando un comando curl. Ti consigliamo di utilizzare l'`-i`opzione per includere le intestazioni di risposta del protocollo nell'output. Per vedere i dati di risposta non appena arrivano, usa l'opzione curl `--no-buffer` ## Risolvi gli errori cURL Se stai testando un'integrazione e ricevi l'errore`curl: (18) transfer closed with outstanding read data remaining`, assicurati che il timeout dell'integrazione sia sufficientemente lungo. Se utilizzi una funzione Lambda, devi aggiornare il timeout di risposta della funzione Lambda. Per ulteriori informazioni, consulta [Configurare il timeout della funzione Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-timeout.html). ## Risolvi i problemi relativi all'utilizzo della registrazione degli accessi Puoi utilizzare i log di accesso per la fase dell'API REST per registrare e risolvere i problemi del flusso di risposta. Oltre alle variabili esistenti, puoi utilizzare le seguenti variabili di registro degli accessi: `$context.integration.responseTransferMode` La modalità di trasferimento delle risposte della tua integrazione. Ciò può essere `BUFFERED` o `STREAMED`. `$context.integration.timeToAllHeaders` Il tempo che intercorre tra il momento in cui API Gateway stabilisce la connessione di integrazione e il momento in cui riceve tutte le intestazioni di risposta all'integrazione dal client. `$context.integration.timeToFirstContent` Il tempo che intercorre tra il momento in cui API Gateway stabilisce la connessione di integrazione e il momento in cui riceve i primi byte di contenuto. `$context.integration.latency` o `$context.integrationLatency` Il momento in cui API Gateway stabilisce la connessione di integrazione e il momento in cui il flusso di risposta dell'integrazione è completo. La figura seguente mostra come queste variabili di log di accesso rappresentino diversi componenti di un flusso di risposta. ![\[Accedi alle variabili di registro per lo streaming delle risposte in API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/response-streaming-figure.png) Per ulteriori informazioni sui log degli accessi al, consultare [Configurare la CloudWatch registrazione per REST APIs in API Gateway](set-up-logging.md). Puoi anche usare X-Ray per monitorare il flusso di risposta. Per ulteriori informazioni, consulta [Traccia delle richieste degli utenti alle REST API utilizzando X-Ray in Gateway API](apigateway-xray.md). # Integrazioni private per REST APIs in API Gateway Utilizza un'integrazione privata per esporre HTTP/HTTPS le tue risorse all'interno di un Amazon VPC per consentire l'accesso da parte di client esterni al VPC. Ciò estende l'accesso alle tue risorse VPC private oltre i confini del VPC. È possibile controllare l'accesso all'API utilizzando uno qualsiasi dei [ metodi di autorizzazione](apigateway-control-access-to-api.md) supportati da API Gateway. Per creare un'integrazione privata, devi innanzitutto creare un collegamento VPC. API Gateway supporta i collegamenti VPC V2 per REST. APIs I collegamenti VPC V2 consentono di creare integrazioni private che collegano l'API REST agli Application Load Balancer senza utilizzare un Network Load Balancer. L'utilizzo di un Application Load Balancer ti consente di connetterti alle applicazioni ECSs basate su container Amazon e a molti altri backend. I link VPC V1 sono considerati un tipo di integrazione legacy. Sebbene siano supportati da API Gateway, ti consigliamo di non creare nuovi collegamenti VPC V1. ## Considerazioni Le seguenti considerazioni potrebbero influire sull'utilizzo delle integrazioni private: + Tutte le risorse devono essere di proprietà dello stesso. Account AWS Ciò include il sistema di bilanciamento del carico, il collegamento VPC e l'API REST. + Per impostazione predefinita, il traffico di integrazione privata utilizza il protocollo HTTP. Per utilizzare HTTPS, specifica un file [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)che contenga un nome di server sicuro, ad esempio. `https://example.com:443/test` + In un'integrazione privata, API Gateway include la parte di [fase](set-up-stages.md) dell'endpoint API nella richiesta alle risorse di backend. Ad esempio, se richiedi la `test` fase di un'API, API Gateway include `test/path` nella richiesta alla tua integrazione privata. Per rimuovere il nome della fase dalla richiesta alle risorse di backend, utilizzate la [mappatura dei parametri](rest-api-parameter-mapping.md) per creare un override per la variabile. `$context.requestOverride.path` + Le integrazioni private con AWS Cloud Map non sono supportate. **Topics** + [Considerazioni](#private-integrations-considerations) + [Configura i collegamenti VPC V2 in API Gateway](apigateway-vpc-links-v2.md) + [Configura un'integrazione privata](set-up-private-integration.md) + [Integrazione privata tramite collegamenti VPC V1 (legacy)](vpc-links-v1.md) # Configura i collegamenti VPC V2 in API Gateway I link VPC ti consentono di creare integrazioni private che collegano i tuoi percorsi API a risorse private in un VPC, come Application Load Balancers o applicazioni basate su container Amazon ECS. Un'integrazione privata utilizza un collegamento VPC V2 per incapsulare le connessioni tra API Gateway e risorse VPC mirate. Puoi riutilizzare i link VPC su diverse risorse e. APIs Quando crei un collegamento VPC, API Gateway crea e gestisce [interfacce di rete elastiche](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-eni.html) per il collegamento VPC V2 nel tuo account. Questo processo può richiedere alcuni minuti. Quando un collegamento VPC V2 è pronto per l'uso, il suo stato passa da a. `PENDING` `AVAILABLE` **Nota** Se non viene inviato alcun traffico tramite il collegamento VPC per 60 giorni, lo stato cambia in `INACTIVE`. Quando lo stato di un collegamento VPC è `INACTIVE`, API Gateway elimina tutte le interfacce di rete del collegamento VPC. In questo caso, le richieste API che dipendono dal collegamento VPC non vanno a buon fine. Se le richieste API riprendono, API Gateway effettua nuovamente il provisioning delle interfacce di rete. Potrebbero essere necessari alcuni minuti per creare le interfacce di rete e riattivare il collegamento VPC. Puoi utilizzare lo stato del collegamento VPC per monitorare lo stato del tuo collegamento VPC. ## Creare un collegamento VPC V2 utilizzando AWS CLI Per creare un collegamento VPC V2, tutte le risorse coinvolte devono essere di proprietà dello stesso account. AWS Il [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-vpc-link.html)comando seguente crea un collegamento VPC: ``` aws apigatewayv2 create-vpc-link --name MyVpcLink \ --subnet-ids subnet-aaaa subnet-bbbb \ --security-group-ids sg1234 sg5678 ``` **Nota** I link VPC V2 sono immutabili. Dopo aver creato un collegamento VPC V2, non puoi modificarne le sottoreti o i gruppi di sicurezza. ## Eliminare un collegamento VPC V2 utilizzando il AWS CLI Il [delete-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/delete-vpc-link.html)comando seguente elimina un collegamento VPC. ``` aws apigatewayv2 delete-vpc-link --vpc-link-id abcd123 ``` ## Disponibilità in base alla Regione I collegamenti VPC V2 sono supportati nelle seguenti regioni e zone di disponibilità: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/apigateway-vpc-links-v2.html) # Configura un'integrazione privata Per creare un'integrazione privata con un Application Load Balancer o Network Load Balancer, devi creare un'integrazione proxy HTTP, specificare il [link VPC V2](apigateway-vpc-links-v2.md) da utilizzare e fornire l'ARN di un Network Load Balancer o di un Application Load Balancer. Per impostazione predefinita, il traffico di integrazione privata utilizza il protocollo HTTP. Per utilizzare HTTPS, specificane uno [https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri](https://docs.aws.amazon.com/apigateway/latest/api/API_PutIntegration.html#apigw-PutIntegration-request-uri)che contenga un nome di server sicuro, ad esempio. `https://example.com:443/test` Per un tutorial completo su come creare un'API REST con un'integrazione privata, consulta[Tutorial: creazione di una REST API con un'integrazione privata](getting-started-with-private-integration.md). ## Creazione di un'integrazione privata La procedura seguente mostra come creare un'integrazione privata che si connette a un sistema di bilanciamento del carico utilizzando un collegamento VPC V2. ------ #### [ Console di gestione AWS ] Per un tutorial su come creare un'integrazione privata, vedi,. [Tutorial: creazione di una REST API con un'integrazione privata](getting-started-with-private-integration.md) ------ #### [ AWS CLI ] Il seguente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) crea un'integrazione privata che si connette a un sistema di bilanciamento del carico utilizzando un collegamento VPC V2: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id aaa000 \ --integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \ --uri 'https://example.com:443/path' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id bbb111 ``` Invece di fornire direttamente l'ID di connessione, puoi utilizzare una variabile di fase. Quando distribuisci l'API su una fase, imposti l'ID VPC link V2. Il seguente comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) crea un'integrazione privata utilizzando una variabile stage per l'ID VPC link V2: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id aaa000 \ --integration-target 'arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011' \ --uri 'https://example.com:443/path' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkV2Id}" ``` Assicurati di inserire due virgolette nell'espressione della variabile stage (\$1 \$1stageVariables.vpclinkV2ID\$1) e di evitare il carattere \$1. ------ #### [ OpenAPI ] È possibile configurare un'API con integrazione privata importando il file OpenAPI dell'API. Le impostazioni sono simili alle definizioni di OpenAPI di un'API con integrazioni HTTP, con le eccezioni seguenti: + Devi impostare esplicitamente `connectionType` su `VPC_LINK`. + Devi impostare esplicitamente `connectionId` sull'ID di un oggetto `VpcLinkV2` o su una variabile di fase che fa riferimento all'ID di un oggetto `VpcLinkV2`. + Il `uri` parametro nell'integrazione privata punta a un HTTP/HTTPS endpoint nel VPC, ma viene invece utilizzato per configurare l'intestazione della richiesta `Host` di integrazione. + Il parametro `uri` nell'integrazione privata con un endpoint HTTPS in VPC viene usato per verificare il nome di dominio indicato confrontandolo con quello nel certificato installato nell'endpoint VPC. Per fare riferimento all'ID di `VpcLinkV2`, è possibile usare una variabile di fase. In alternativa, è possibile assegnare il valore ID direttamente a `connectionId`. Il file OpenAPI dell'API in formato JSON seguente mostra un esempio di un'API con un collegamento VPC in base al riferimento nella variabile di fase (`${stageVariables.vpcLinkIdV2}`): ``` { "swagger": "2.0", "info": { "version": "2017-11-17T04:40:23Z", "title": "MyApiWithVpcLinkV2" }, "host": "abcdef123.execute-api.us-west-2.amazonaws.com", "basePath": "/test", "schemes": [ "https" ], "paths": { "/": { "get": { "produces": [ "application/json" ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } } }, "x-amazon-apigateway-integration": { "responses": { "default": { "statusCode": "200" } }, "uri": "https://example.com:443/path", "passthroughBehavior": "when_no_match", "connectionType": "VPC_LINK", "connectionId": "${stageVariables.vpcLinkV2Id}", "integration-target": "arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011", "httpMethod": "GET", "type": "http_proxy" } } } }, "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Aggiorna un'integrazione privata L'esempio seguente aggiorna il collegamento VPC V2 per un'integrazione privata. ------ #### [ Console di gestione AWS ] **Per aggiornare un'integrazione privata** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegli un'API REST con un'integrazione privata. 1. Scegli la risorsa e il metodo che utilizzano un'integrazione privata. 1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**. 1. Puoi modificare l'impostazione della tua integrazione privata. Se attualmente utilizzi un collegamento VPC V1, puoi modificare il tuo collegamento VPC in un collegamento VPC V2. 1. Scegli **Save** (Salva). 1. Implementa nuovamente l'API per rendere effettive le modifiche. ------ #### [ AWS CLI ] Il seguente comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/latest/api/API_PutIntegration.html) aggiorna un'integrazione privata per utilizzare un collegamento VPC V2: ``` aws apigateway update-integration \ --rest-api-id a1b2c3d4e5 \ --resource-id a1b2c3 \ --http-method GET \ --patch-operations "[{\"op\":\"replace\",\"path\":\"/connectionId\",\"value\":\"pk0000\"}, {\"op\":\"replace\",\"path\":\"/uri\",\"value\":\"http://example.com\"}, {\"op\":\"replace\",\"path\":\"/integrationTarget\",\"value\":\"arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/app/myLoadBalancerName/1234567891011\"}]" ``` ------ # Integrazione privata tramite collegamenti VPC V1 (legacy) **Nota** La seguente implementazione di integrazioni private utilizza i collegamenti VPC V1. I link VPC V1 sono risorse legacy. Ti consigliamo di utilizzare i [collegamenti VPC V2](apigateway-vpc-links-v2.md) per REST. APIs Per creare un'integrazione privata, è necessario innanzitutto creare un collegamento Network Load Balancer. Il Network Load Balancer deve disporre di un [listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) che instrada le richieste alle risorse del VPC. Per migliorare la disponibilità della tua API, assicurati che il sistema di Network Load Balancer stia indirizzando il traffico alle risorse in più zone di disponibilità nella Regione AWS. Quindi, si crea un collegamento VPC che viene utilizzato per connettere l'API e il Network Load Balancer. Dopo avere creato un collegamento VPC, è possibile creare integrazioni private per instradare il traffico dall'API alle risorse del VPC tramite il collegamento VPC e il Network Load Balancer. Il Network Load Balancer e l'API devono essere di proprietà dello stesso. Account AWS **Topics** + [Configurazione di un Network Load Balancer per le integrazioni private di API Gateway (legacy)](set-up-nlb-for-vpclink-using-console.md) + [Concedi le autorizzazioni per API Gateway per creare un collegamento VPC (legacy)](grant-permissions-to-create-vpclink.md) + [Configura un'API API Gateway con integrazioni private utilizzando AWS CLI (legacy)](set-up-api-with-vpclink-cli.md) + [Account API Gateway utilizzati per integrazioni private (legacy)](set-up-api-with-vpclink-accounts.md) # Configurazione di un Network Load Balancer per le integrazioni private di API Gateway (legacy) **Nota** La seguente implementazione di integrazioni private utilizza i collegamenti VPC V1. I link VPC V1 sono risorse legacy. Ti consigliamo di utilizzare i [collegamenti VPC V2](apigateway-vpc-links-v2.md) per REST. APIs Nella procedura seguente vengono illustrate le fasi necessarie per configurare un sistema Network Load Balancer (NLB) per le integrazioni private di API Gateway usando la console Amazon EC2 e vengono forniti i riferimenti a istruzioni dettagliate per ogni fase. Per ogni VPC in cui sono presenti risorse, è sufficiente configurare un NLB e uno. VPCLink Il NLB supporta più [listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-listeners.html) e [gruppi target](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-target-groups.html) per NLB. È possibile configurare ogni servizio come listener specifico sull'NLB e utilizzarne uno per connettersi all'NLB. VPCLink Al momento della creazione dell'integrazione privata in API Gateway è possibile quindi definire ciascun servizio utilizzando la porta specifica assegnata per il servizio. Per ulteriori informazioni, consulta [Tutorial: creazione di una REST API con un'integrazione privata](getting-started-with-private-integration.md). Il Network Load Balancer e l'API devono essere di proprietà dello stesso. Account AWS **Per creare un sistema Network Load Balancer per l'integrazione privata tramite la console API Gateway** 1. Accedi Console di gestione AWS e apri la console Amazon EC2 all'indirizzo. [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) 1. Configura un server Web in un'istanza di Amazon EC2. Per una configurazione di esempio, consulta [Installazione di un server Web LAMP su Amazon Linux 2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-lamp-amazon-linux-2.html). 1. Crea un sistema Network Load Balancer, registra l'istanza EC2 con un gruppo target e aggiungi il gruppo target a un listener del sistema Network Load Balancer. Per ulteriori informazioni, segui le istruzioni contenute in [Nozioni di base sui sistemi Network Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/network/network-load-balancer-getting-started.html). 1. Dopo la creazione del Network Load Balancer, procedi come segue: 1. Prendi nota dell'ARN del Network Load Balancer. Sarà necessario per creare un collegamento VPC in API Gateway per l'integrazione dell'API con le risorse VPC nel sistema Network Load Balancer. 1. Disattiva la valutazione dei gruppi di sicurezza per PrivateLink. + Per disattivare la valutazione dei gruppi di sicurezza per il PrivateLink traffico che utilizza la console, puoi scegliere la scheda **Sicurezza**, quindi **Modifica**. Nelle **impostazioni di sicurezza**, deseleziona **Applica le regole in entrata al PrivateLink traffico**. + Usa il seguente [set-security-groups](https://docs.aws.amazon.com/cli/latest/reference/elbv2/set-security-groups.html)comando per disattivare la valutazione dei gruppi di sicurezza per il PrivateLink traffico: ``` aws elbv2 set-security-groups --load-balancer-arn arn:aws:elasticloadbalancing:us-east-2:111122223333:loadbalancer/net/my-loadbalancer/abc12345 \ --security-groups sg-123345a --enforce-security-group-inbound-rules-on-private-link-traffic off ``` **Nota** Non aggiungete alcuna dipendenza ad API Gateway CIDRs poiché sono destinate a cambiare senza preavviso. # Concedi le autorizzazioni per API Gateway per creare un collegamento VPC (legacy) **Nota** La seguente implementazione di integrazioni private utilizza i collegamenti VPC V1. I link VPC V1 sono risorse legacy. Ti consigliamo di utilizzare i [collegamenti VPC V2](apigateway-vpc-links-v2.md) per REST. APIs Per poter creare e gestire un collegamento VPC, è necessario disporre delle autorizzazioni per creare, eliminare e visualizzare le configurazioni del servizio endpoint VPC, modificare le autorizzazioni del servizio endpoint VPC ed esaminare i sistemi di bilanciamento del carico. Per concedere tali autorizzazioni, esegui la procedura illustrata di seguito. **Per concedere le autorizzazioni per creare, aggiornare o eliminare un link VPC** 1. Crea una policy IAM simile alla seguente: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "apigateway:POST", "apigateway:GET", "apigateway:PATCH", "apigateway:DELETE" ], "Resource": [ "arn:aws:apigateway:us-east-1::/vpclinks", "arn:aws:apigateway:us-east-1::/vpclinks/*" ] }, { "Effect": "Allow", "Action": [ "elasticloadbalancing:DescribeLoadBalancers" ], "Resource": "*" }, { "Effect": "Allow", "Action": [ "ec2:CreateVpcEndpointServiceConfiguration", "ec2:DeleteVpcEndpointServiceConfigurations", "ec2:DescribeVpcEndpointServiceConfigurations", "ec2:ModifyVpcEndpointServicePermissions" ], "Resource": "*" } ] } ``` ------ Se desideri abilitare il tagging per il collegamento VPC, assicurati di consentire le operazioni di tagging. Per ulteriori informazioni, consulta [Consentire operazioni di assegnazione di tag](apigateway-tagging-iam-policy.md#allow-tagging). 1. Crea o scegli un ruolo IAM e collega la policy precedente al ruolo. 1. Assegna il ruolo IAM a te stesso o a un utente nell'account che sta creando collegamenti VPC. # Configura un'API API Gateway con integrazioni private utilizzando AWS CLI (legacy) **Nota** La seguente implementazione di integrazioni private utilizza i collegamenti VPC V1. I link VPC V1 sono risorse legacy. Ti consigliamo di utilizzare i [collegamenti VPC V2](apigateway-vpc-links-v2.md) per REST. APIs Il seguente tutorial mostra come utilizzare per AWS CLI creare un collegamento VPC e un'integrazione privata. Devono essere soddisfatti i seguenti prerequisiti: + È necessario creare e configurare un Network Load Balancer con l'origine VPC come destinazione. Per ulteriori informazioni, consulta [Configurazione di un Network Load Balancer per le integrazioni private di API Gateway (legacy)](set-up-nlb-for-vpclink-using-console.md). Deve essere Account AWS uguale alla tua API. È necessario l'ARN del Network Load Balancer per creare il collegamento VPC. + Per creare e gestire un `VpcLink`, sono necessarie le autorizzazioni per creare un `VpcLink` nell'API. Non sono necessarie autorizzazioni per utilizzare il `VpcLink`. Per ulteriori informazioni, consulta [Concedi le autorizzazioni per API Gateway per creare un collegamento VPC (legacy)](grant-permissions-to-create-vpclink.md). **Per configurare un'API con l'integrazione privata utilizzando AWS CLI** 1. Usa il [create-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-vpc-link.html)comando seguente per creare un `VpcLink` target per il Network Load Balancer specificato: ``` aws apigateway create-vpc-link \ --name my-test-vpc-link \ --target-arns arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef ``` L'output di questo comando riconosce la ricezione della richiesta e mostra lo stato `PENDING` per il `VpcLink` in fase di creazione. ``` { "status": "PENDING", "targetArns": [ "arn:aws:elasticloadbalancing:us-east-2:123456789012:loadbalancer/net/my-vpclink-test-nlb/1234567890abcdef" ], "id": "gim7c3", "name": "my-test-vpc-link" } ``` Per la creazione dell'oggetto `VpcLink` in API Gateway sono necessari da 2 a 4 minuti. Dopo il completamento dell'operazione, il valore di `status` è `AVAILABLE`. È possibile verificarlo utilizzando il seguente comando: [get-vpc-link](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-vpc-link.html) ``` aws apigateway get-vpc-link --vpc-link-id gim7c3 ``` Se l'operazione non riesce, lo stato è `FAILED` e `statusMessage` contiene il messaggio di errore. Se, ad esempio, tenti di creare un oggetto `VpcLink` con un sistema Network Load Balancer già associato a un endpoint VPC, la proprietà `statusMessage` contiene quanto segue: ``` "NLB is already associated with another VPC Endpoint Service" ``` Dopo la corretta creazione di `VpcLink` è possibile creare un'API e integrarla con la risorsa VPC tramite la `VpcLink`. Prendi nota del valore `id` del `VpcLink` appena creato. In questo output di esempio, è `gim7c3`. Questo valore è necessario per configurare l'integrazione privata. 1. Utilizzate il seguente [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando per creare una [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa API Gateway: ``` aws apigateway create-rest-api --name 'My VPC Link Test' ``` Prendi nota del valore `id` di `RestApi` e del valore `rootResourceId` di `RestApi` nel risultato restituito. Questo valore è necessario per eseguire ulteriori operazioni sull'API. Quindi, crea un’API con solo un metodo `GET` nella risorsa root (`/`) e integra il metodo con `VpcLink`. 1. Utilizza il comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) seguente per creare il metodo `GET /`: ``` aws apigateway put-method \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --http-method GET \ --authorization-type "NONE" ``` Se non usi l'integrazione proxy con il `VpcLink`, devi configurare anche almeno una risposta del metodo per il codice di stato `200`. In questo caso si usa l’integrazione proxy. 1. Dopo aver creato il metodo `GET /`, viene configurata l'integrazione. Per un'integrazione privata, si utilizza il parametro `connection-id` per fornire l'ID del `VpcLink`. Puoi utilizzare una variabile di fase o inserire direttamente l'ID del `VpcLink`. Il parametro `uri` non viene usato per il routing delle richieste all'endpoint, ma viene usato per impostare l'intestazione `Host` per la convalida del certificato. ------ #### [ Use the VPC link ID ] Utilizza il comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) seguente per usare l’ID del `VpcLink` direttamente nell’integrazione: ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id gim7c3 ``` ------ #### [ Use a stage variable ] Utilizza il comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) seguente per usare una variabile di fase per fare riferimento all’ID del collegamento VPC. Quando implementi l'API in una fase, viene impostato l'ID del collegamento VPC. ``` aws apigateway put-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --uri 'http://my-vpclink-test-nlb-1234567890abcdef.us-east-2.amazonaws.com' \ --http-method GET \ --type HTTP_PROXY \ --integration-http-method GET \ --connection-type VPC_LINK \ --connection-id "\${stageVariables.vpcLinkId}" ``` Assicurati di racchiudere tra virgolette doppie l'espressione della variabile di fase (`${stageVariables.vpcLinkId}`) e di aggiungere il carattere di escape davanti a `$`. ------ In qualsiasi momento, puoi anche aggiornare l'integrazione per modificare il valore `connection-id`. Utilizza il comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) seguente per aggiornare l’integrazione: ``` aws apigateway update-integration \ --rest-api-id abcdef123 \ --resource-id skpp60rab7 \ --http-method GET \ --patch-operations '[{"op":"replace","path":"/connectionId","value":"${stageVariables.vpcLinkId}"}]' ``` Assicurati di usare un elenco JSON in formato stringa come valore del parametro `patch-operations`. Poiché è stata utilizzata l’integrazione proxy privata, l’API è ora pronta per l’implementazione e i test. 1. Se hai utilizzato la variabile di fase per definire il valore `connection-id`, devi implementare l'API per testarla. Utilizza il comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) seguente per implementare l’API con una variabile di fase: ``` aws apigateway create-deployment \ --rest-api-id abcdef123 \ --stage-name test \ --variables vpcLinkId=gim7c3 ``` Per aggiornare la variabile di fase con un ID del `VpcLink` diverso, ad esempio `asf9d7`, utilizza il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente: ``` aws apigateway update-stage \ --rest-api-id abcdef123 \ --stage-name test \ --patch-operations op=replace,path='/variables/vpcLinkId',value='asf9d7' ``` Quando imposti come hardcoded la proprietà `connection-id` con il valore letterale ID di `VpcLink`, non è necessario implementare l'API per testarla. Usa il [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html)comando per testare l'API prima che venga distribuita. 1. Utilizza il seguente comando per invocare l'API: ``` curl -X GET https://abcdef123.execute-api.us-east-2.amazonaws.com/test ``` In alternativa, puoi inserire l'URL di invocazione dell'API in un browser web per visualizzare il risultato. # Account API Gateway utilizzati per integrazioni private (legacy) Il seguente account API Gateway specifico della regione IDs viene aggiunto automaticamente al tuo servizio endpoint VPC come quando `AllowedPrincipals` crei un. `VpcLink` | **Region** | **ID account** | | --- | --- | | us-east-1 | 392220576650 | | us-east-2 | 718770453195 | | us-west-1 | 968246515281 | | us-west-2 | 109351309407 | | ca-central-1 | 796887884028 | | eu-west-1 | 631144002099 | | eu-west-2 | 544388816663 | | eu-west-3 | 061510835048 | | eu-central-1 | 474240146802 | | eu-central-2 | 166639821150 | | eu-north-1 | 394634713161 | | eu-south-1 | 753362059629 | | eu-south-2 | 359345898052 | | ap-northeast-1 | 969236854626 | | ap-northeast-2 | 020402002396 | | ap-northeast-3 | 360671645888 | | ap-southeast-1 | 195145609632 | | ap-southeast-2 | 798376113853 | | ap-southeast-3 | 652364314486 | | ap-southeast-4 | 849137399833 | | ap-south-1 | 507069717855 | | ap-south-2 | 644042651268 | | ap-east-1 | 174803364771 | | sa-east-1 | 287228555773 | | me-south-1 | 855739686837 | | me-central-1 | 614065512851 | # Integrazioni fittizie per REST APIs in API Gateway Amazon API Gateway supporta le integrazioni fittizie per i metodi API. Questa caratteristica permette agli sviluppatori di API di generare risposte API da API Gateway direttamente, senza che sia necessario un back-end di integrazione. Uno sviluppatore di API può usare questa caratteristica per sbloccare team dipendenti che devono lavorare a un'API prima che lo sviluppo del progetto sia completato. Puoi anche usare questa caratteristica per allestire una pagina di destinazione per l'API, con una panoramica e comandi di navigazione per l'API. Per un esempio di pagina di destinazione di questo tipo, consulta la richiesta e la risposta di integrazione del metodo GET nella risorsa root dell'API di esempio illustrata in [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). Uno sviluppatore di API può decidere in che modo API Gateway risponde alle richieste di integrazione fittizia. A tale scopo, è necessario configurare la richiesta e la risposta di integrazione del metodo per associare una risposta a un codice di stato specifico. Affinché un metodo con l'integrazione fittizia restituisca una risposta `200`, configura il modello di mappatura del corpo della richiesta di integrazione per restituire quanto segue. ``` {"statusCode": 200} ``` Configura una risposta di integrazione `200` con il modello di mappatura del corpo seguente, ad esempio: ``` { "statusCode": 200, "message": "Go ahead without me." } ``` Analogamente, affinché il metodo restituisca, ad esempio, una risposta di errore `500`, configura il modello di mappatura del corpo della richiesta di integrazione per restituire quanto segue. ``` {"statusCode": 500} ``` Configura, ad esempio, una risposta di integrazione `500` con il modello di mappatura seguente: ``` { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } ``` In alternativa, puoi fare in modo che un metodo dell'integrazione fittizia restituisca la risposta di integrazione predefinita senza definire il modello di mappatura della richiesta di integrazione. La risposta di integrazione predefinita è quella con valore **HTTP status regex (Regex stato HTTP)** non definito. Assicurati che siano impostati i comportamenti di passthrough appropriati. **Nota** Le integrazioni fittizie non sono concepite per supportare modelli di risposta di grandi dimensioni. Se ne hai bisogno per il caso d'uso specifico, dovresti valutare invece l'utilizzo di un'integrazione Lambda. Usando un modello di mappatura della richiesta di integrazione puoi inserire la logica dell'applicazione per stabilire quale risposta di integrazione fittizia restituire in base a determinate condizioni. Puoi ad esempio usare un parametro di query `scope` nella richiesta in ingresso per determinare se restituire una risposta di esito positivo o di errore: ``` { #if( $input.params('scope') == "internal" ) "statusCode": 200 #else "statusCode": 500 #end } ``` In questo modo, il metodo dell'integrazione fittizia consente alle chiamate interne di passare, mentre gli altri tipi di chiamate vengono rifiutati con una risposta di errore. Questa sezione descrive come utilizzare la console API Gateway per abilitare l'integrazione fittizia per un metodo API. **Topics** + [Abilitazione dell'integrazione fittizia tramite la console API Gateway](how-to-mock-integration-console.md) # Abilitazione dell'integrazione fittizia tramite la console API Gateway In Gateway API deve essere disponibile un metodo. Segui le istruzioni in [Tutorial: creazione di una REST API con un'integrazione non proxy HTTP](api-gateway-create-api-step-by-step.md). 1. Seleziona una risorsa API e scegli **Crea metodo**. Per creare il metodo, procedi nel seguente modo: 1. Per **Tipo di metodo** seleziona un metodo. 1. Per **Tipo di integrazione** seleziona **Fittizio**. 1. Scegli **Crea metodo**. 1. Nella scheda **Richiesta metodo** scegli **Modifica** in **Impostazioni della richiesta del metodo**. 1. Scegli **Parametri della stringa di query URL**. Scegli **Aggiungi stringa di query** e per **Nome** immetti **scope**. Questo parametro di query determina se il chiamante è interno o meno. 1. Scegli **Save** (Salva). 1. Nella scheda **Risposta metodo** scegli **Crea risposta**, quindi procedi come indicato di seguito: 1. Per **Stato HTTP** immetti **500**. 1. Scegli **Save** (Salva). 1. Nella scheda **Richiesta di integrazione** seleziona **Modifica** per **Impostazioni della richiesta di integrazione**. 1. Scegli **Modelli di mappatura** e procedi come indicato di seguito: 1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci quanto segue: ``` { #if( $input.params('scope') == "internal" ) "statusCode": 200 #else "statusCode": 500 #end } ``` 1. Scegli **Save** (Salva). 1. Nella scheda **Risposta di integrazione** scegli **Modifica** per **Predefinito - Risposta**. 1. Scegli **Modelli di mappatura** e procedi come indicato di seguito: 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci quanto segue: ``` { "statusCode": 200, "message": "Go ahead without me" } ``` 1. Scegli **Save** (Salva). 1. Scegli **Crea risposta**. Per creare una risposta 500, procedi come descritto qui di seguito: 1. Per **HTTP status regex (Regex stato HTTP)**, immettere **5\$1d\$12\$1**. 1. Per **Stato metodo risposta** seleziona **500**. 1. Scegli **Save** (Salva). 1. Per **5\$1d\$12\$1 - Risposta** scegli **Modifica**. 1. Scegli **Modelli di mappatura**, quindi seleziona **Aggiungi modello di mappatura**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci quanto segue: ``` { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } ``` 1. Scegli **Save** (Salva). 1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. Per testare l'integrazione fittizia, procedi come indicato di seguito: 1. Immetti `scope=internal` in **Stringhe di query**. Scegli **Test (Esegui test)**. Viene visualizzato il risultato del test: ``` Request: /?scope=internal Status: 200 Latency: 26 ms Response Body { "statusCode": 200, "message": "Go ahead without me" } Response Headers {"Content-Type":"application/json"} ``` 1. Immettere `scope=public` in `Query strings` oppure lasciare vuoto il campo. Scegli **Test (Esegui test)**. Viene visualizzato il risultato del test: ``` Request: / Status: 500 Latency: 16 ms Response Body { "statusCode": 500, "message": "The invoked method is not supported on the API resource." } Response Headers {"Content-Type":"application/json"} ``` Puoi anche restituire le intestazioni in una risposta di integrazione fittizia aggiungendo prima di tutto un'intestazione a una risposta del metodo e quindi configurando una mappatura dell'intestazione nella risposta di integrazione. È in questo modo che la console API Gateway abilita il supporto CORS restituendo le intestazioni richieste da CORS. # Richiedi la convalida per REST APIs in API Gateway Puoi configurare API Gateway per l'esecuzione di una convalida di base di una richiesta API prima di procedere con la richiesta di integrazione. Quando la convalida fallisce, API Gateway fallisce immediatamente la richiesta, restituisce una risposta di errore 400 al chiamante e pubblica i risultati della convalida in Logs. CloudWatch Questo comportamento riduce le chiamate non necessarie al back-end. Aspetto ancora più importante, ti permette di concentrarti sulle attività di convalida specifiche dell'applicazione. È possibile convalidare il corpo di una richiesta verificando che i parametri obbligatori della richiesta siano validi e diversi da null oppure specificando uno schema di modello per una convalida dei dati più complessa. **Topics** + [Panoramica della convalida di base delle richieste in API Gateway](#api-gateway-request-validation-basic-definitions) + [Modelli di dati per REST APIs](models-mappings-models.md) + [Configurazione della convalida di base delle richieste in API Gateway](api-gateway-request-validation-set-up.md) + [AWS CloudFormation modello di un'API di esempio con convalida delle richieste di base](api-gateway-request-validation-sample-cloudformation.md) ## Panoramica della convalida di base delle richieste in API Gateway Gateway Amazon API può eseguire la convalida di base delle richieste, in modo che sia possibile concentrarsi sulla convalida specifica dell'app nel back-end. Per la convalida, Gateway Amazon API verifica una o entrambe le condizioni seguenti: + I parametri della richiesta obbligatori nell'URI, nella stringa di query e nelle intestazioni di una richiesta in entrata sono inclusi e non sono vuoti. Gateway API verifica solo l’esistenza di un parametro e non controlla il tipo o il formato. + Il payload della richiesta applicabile soddisfa la richiesta configurata dello [schema JSON](https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-04) del metodo per un tipo di contenuto specifico. 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, impostare il tipo di contenuto per il modello di dati su `$default`. Per attivare la convalida di base, è necessario specificare regole di convalida in un [validatore di richieste](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html), aggiungere il validatore alla [mappa di validatori di richieste](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html) dell'API e assegnare il validatore a singoli metodi API. **Nota** La convalida del corpo della richiesta e [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md) sono due argomenti separati. Quando il payload di una richiesta non dispone di uno schema di modello corrispondente, puoi scegliere di eseguire il transito o il blocco del payload originale. Per ulteriori informazioni, consulta [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md). # Modelli di dati per REST APIs In API Gateway, un modello definisce la struttura dei dati di un payload. In Gateway Amazon API i modelli sono definiti utilizzando lo [schema JSON bozza 4](https://tools.ietf.org/html/draft-zyp-json-schema-04). Il seguente oggetto JSON è un esempio di dati nell'esempio di Pet Store. ``` { "id": 1, "type": "dog", "price": 249.99 } ``` I dati contengono i valori `id`, `type` e `price` dell'animale domestico. Un modello di questi dati consente di: + Usare la convalida di base delle richieste. + Creare modelli di mappatura per la trasformazione dei dati. + Creare un tipo di dati definito dall'utente (UDT) quando viene generato un SDK. ![\[Esempio di modello di dati JSON per PetStore API.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/how-to-validate-requests.png) In questo modello: 1. L'oggetto `$schema` rappresenta un identificatore valido della versione dello schema JSON. Questo schema è lo schema JSON bozza v4. 1. L'oggetto `title` è un identificatore in formato leggibile del modello. Questo titolo è `PetStoreModel`. 1. La parola chiave di convalida `required` richiede `type` e `price` per la convalida di base della richiesta. 1. La variabile `properties` del modello è `id`, `type` e`price`. Ogni oggetto ha proprietà che vengono descritte nel modello. 1. L'oggetto `type` può avere solo i valori `dog`, `cat` o `fish`. 1. L'oggetto `price` è un numero ed è vincolato con un valore `minimum` di 25 e un valore `maximum` di 500. ## PetStore modello ``` 1 { 2 "$schema": "http://json-schema.org/draft-04/schema#", 3 "title": "PetStoreModel", 4 "type" : "object", 5 "required" : [ "price", "type" ], 6 "properties" : { 7 "id" : { 8 "type" : "integer" 9 }, 10 "type" : { 11 "type" : "string", 12 "enum" : [ "dog", "cat", "fish" ] 13 }, 14 "price" : { 15 "type" : "number", 16 "minimum" : 25.0, 17 "maximum" : 500.0 18 } 19 } 20 } ``` In questo modello: 1. Alla riga 2, l'oggetto `$schema` rappresenta un identificatore valido della versione dello schema JSON. Questo schema è lo schema JSON bozza v4. 1. Alla riga 3, l'oggetto `title` è un identificatore in formato leggibile del modello. Questo titolo è `PetStoreModel`. 1. Alla riga 5, la parola chiave di convalida `required` richiede `type` e `price` per la convalida di base della richiesta. 1. Alle righe da 6 a 17, la variabile `properties` del modello è `id`. `type` e `price`. Ogni oggetto ha proprietà che vengono descritte nel modello. 1. Alla riga 12, l'oggetto `type` può avere solo i valori `dog`, `cat` o `fish`. 1. Alle righe da 14 a 17, l'oggetto `price` è un numero ed è vincolato con un valore `minimum` di 25 e un valore `maximum` di 500. ## Creazione di modelli più complessi È possibile utilizzare la primitiva `$ref` per creare definizioni riutilizzabili per modelli più lunghi. Ad esempio, è possibile creare una definizione chiamata `Price` nella sezione `definitions` che descrive l'oggetto `price`. Il valore di `$ref` è la definizione `Price`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReUsableRef", "required" : ["price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "#/definitions/Price" } }, "definitions" : { "Price": { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` È inoltre possibile fare riferimento a un altro schema del modello definito in un file di modello esterno. Impostare il valore della proprietà `$ref` sulla posizione del modello. Nell'esempio seguente, il modello `Price` è definito nel modello `PetStorePrice` nell'API `a1234`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStorePrice", "type": "number", "minimum": 25, "maximum": 500 } ``` Il modello più lungo può fare riferimento al modello `PetStorePrice`. ``` { "$schema" : "http://json-schema.org/draft-04/schema#", "title" : "PetStoreModelReusableRefAPI", "required" : [ "price", "type" ], "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string", "enum" : [ "dog", "cat", "fish" ] }, "price" : { "$ref": "https://apigateway.amazonaws.com/restapis/a1234/models/PetStorePrice" } } } ``` ## Utilizzo di modelli di dati di output In caso di trasformazione dei dati, è possibile definire un modello di payload nella risposta dell'integrazione. È possibile utilizzare un modello di payload quando si genera un SDK. Per linguaggi fortemente tipizzati, come Java, Objective-C o Swift, l'oggetto corrisponde a un tipo di dati definito dall'utente (UDT). Gateway Amazon API crea un tipo di dati definito dall'utente se viene specificato con un modello di dati durante la generazione di un SDK. Per ulteriori informazioni sulle trasformazioni dei dati, consultare [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). L'esempio seguente indica i dati di output di una risposta di integrazione. ``` { [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] } ``` L'esempio seguente indica un modello di payload che descrive i dati di output. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PetStoreOutputModel", "type" : "object", "required" : [ "description", "askingPrice" ], "properties" : { "description" : { "type" : "string" }, "askingPrice" : { "type" : "number", "minimum" : 25.0, "maximum" : 500.0 } } } ``` Con questo modello, è possibile eseguire una chiamata a un SDK per recuperare i valori delle proprietà `description`, `askingPrice` leggendo le proprietà `PetStoreOutputModel[i].description` e `PetStoreOutputModel[i].askingPrice`. Se non viene fornito alcun modello, API Gateway utilizzerà il modello vuoto per creare un UDT predefinito. ## Fasi successive + Questa sezione fornisce risorse che è possibile utilizzare per acquisire maggiori conoscenze sui concetti trattati in questo argomento. È possibile seguire i tutorial relativi alla convalida delle richieste: + [Configurazione della convalida delle richieste tramite la console Gateway Amazon API](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-in-console) + [Imposta la convalida delle richieste di base utilizzando il AWS CLI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-cli) + [Configurazione della convalida di base delle richieste utilizzando una definizione OpenAPI](api-gateway-request-validation-set-up.md#api-gateway-request-validation-setup-importing-swagger) + Per ulteriori informazioni sulla trasformazione dei dati e sui modelli di mappatura, consultare [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). # Configurazione della convalida di base delle richieste in API Gateway Questa sezione mostra come configurare la convalida delle richieste per API Gateway utilizzando la console e una definizione OpenAPI. AWS CLI **Topics** + [Configurazione della convalida delle richieste tramite la console Gateway Amazon API](#api-gateway-request-validation-setup-in-console) + [Imposta la convalida delle richieste di base utilizzando il AWS CLI](#api-gateway-request-validation-setup-cli) + [Configurazione della convalida di base delle richieste utilizzando una definizione OpenAPI](#api-gateway-request-validation-setup-importing-swagger) ## 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 applichi uno dei validatori a un metodo API, la console API Gateway aggiunge il validatore alla mappa dell'[RequestValidators](https://docs.aws.amazon.com/apigateway/latest/api/API_RequestValidator.html)API. Per seguire questo tutorial, utilizzerai un CloudFormation modello per creare un'API API Gateway 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'app per CloudFormation](samples/request-validation-tutorial-console.zip). Verrà utilizzato questo modello per creare un'API incompleta. Il resto della procedura verrà completato nella console Gateway Amazon API. **Per creare una pila CloudFormation** 1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/) 1. Scegliere **Create stack (Crea stack)**, quindi **With new resources (standard) (Con nuove risorse (standard))**. 1. In **Specificare modello**, scegliere **Carica un file modello**. 1. Selezionare il modello scaricato. 1. Scegli **Next (Successivo)**. 1. Per **Stack name (Nome stack)**, inserire **request-validation-tutorial-console**, quindi scegliere **Next (Avanti)**. 1. Per **Configure stack options (Configura opzioni di stack)**, scegliere **Next (Successivo)**. 1. Per quanto riguarda **le funzionalità**, riconosci che CloudFormation puoi creare risorse IAM nel tuo account. 1. Scegli **Avanti**, quindi scegli **Invia**. CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Quando lo stato del tuo CloudFormation stack è **CREATE\$1COMPLETE**, sei pronto per passare alla fase successiva. **Selezione dell'API appena creata** 1. Selezionare lo stack **request-validation-tutorial-console** appena creato. 1. Scegliere **Resources** (Risorse). 1. 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** 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. 1. Scegli **Crea modello**. 1. In **Nome**, inserisci **PetStoreModel**. 1. 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 **\$1default**. 1. Per **Descrizione** immetti **My PetStore Model** come descrizione del modello. 1. 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 APIs](models-mappings-models.md). **Per configurare la convalida della richiesta per un metodo `GET`** 1. Nel pannello di navigazione principale scegli **Risorse**, quindi seleziona il metodo **GET**. 1. Nella scheda **Richiesta metodo**, in **Impostazioni richiesta metodo**, scegli **Modifica**. 1. Per **Validatore richiesta** seleziona **Convalida parametri di stringa query e intestazioni**. 1. In **Parametri della stringa di query URL** ed effettua le seguenti operazioni: 1. Scegliere **Add query string (Aggiungi stringa di query)**. 1. In **Nome**, inserisci **petType**. 1. Attiva **Campo obbligatorio**. 1. Mantieni disattivata l'opzione **Caching**. 1. Scegli **Save** (Salva). 1. Nella scheda **Richiesta di integrazione** scegli **Modifica** in **Impostazioni della richiesta di integrazione**. 1. In **Parametri della stringa di query URL** ed effettua le seguenti operazioni: 1. Scegliere **Add query string (Aggiungi stringa di query)**. 1. In **Nome**, inserisci **petType**. 1. 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](set-up-data-transformations-in-api-gateway.md#mapping-example-console). 1. Mantieni disattivata l'opzione **Caching**. 1. Scegli **Save** (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. 1. In **Stringhe di query** immetti **petType=dog** e scegli **Test**. 1. 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](set-up-data-transformations-in-api-gateway.md#mapping-example-console). 1. Rimuovere **petType=dog** e scegliere **Test**. 1. 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**. 1. Nella scheda **Richiesta metodo**, in **Impostazioni richiesta metodo**, scegli **Modifica**. 1. Per **Validatore richiesta** seleziona **Convalida corpo**. 1. In **Corpo della richiesta** scegli **Aggiungi modello**. 1. 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**** 1. Scegli **Save** (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. 1. In **Corpo della richiesta** incolla quanto segue nell'editor di codice: ``` { "id": 2, "name": "Bella", "type": "dog", "price": 400 } ``` Scegli **Test (Esegui test)**. 1. Il test del metodo restituirà `200 OK` e un messaggio di operazione riuscita. 1. In **Corpo della richiesta** incolla quanto segue nell'editor di codice: ``` { "id": 2, "name": "Bella", "type": "dog", "price": 4000 } ``` Scegli **Test (Esegui test)**. 1. 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 una CloudFormation pila** 1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/) 1. Seleziona il tuo stack. CloudFormation 1. Scegli **Elimina** e conferma la tua scelta. ### Fasi successive + Per informazioni su come trasformare i dati di output ed eseguire ulteriori mappature dei dati, consultare il [tutorial sulla mappatura dei dati](set-up-data-transformations-in-api-gateway.md#mapping-example-console). + Eseguire il tutorial [Configurazione della convalida di base delle richieste in AWS CLI](#api-gateway-request-validation-setup-cli) per eseguire passaggi simili utilizzando la  AWS CLI. ## Imposta la convalida delle richieste di base utilizzando il AWS CLI È possibile creare un validatore per configurare la convalida della richiesta utilizzando la  AWS CLI. Per seguire questo tutorial, utilizzerai un CloudFormation modello per creare un'API API Gateway API incompleta. **Nota** Questo non è lo stesso CloudFormation modello 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 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. **Per creare una CloudFormation pila** Scarica e decomprimi [il modello di creazione dell'app](samples/request-validation-tutorial-cli.zip) per. CloudFormation Per completare il tutorial seguente, è necessario disporre della [AWS Command Line Interface (AWS CLI) versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 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](https://learn.microsoft.com/en-us/windows/wsl/install). 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. Usa il seguente comando per creare lo CloudFormation stack. ``` aws cloudformation create-stack --stack-name request-validation-tutorial-cli --template-body file://request-validation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Usa il comando seguente per vedere lo stato del tuo CloudFormation stack. ``` aws cloudformation describe-stacks --stack-name request-validation-tutorial-cli ``` 1. Quando lo stato dello CloudFormation stack è`StackStatus: "CREATE_COMPLETE"`, usa il seguente comando per recuperare i valori di output pertinenti 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, che è l'ID dell'API. Per questo tutorial, l'ID API è `abc123`. + ResourceId, che è l'ID della risorsa di validazione in cui sono esposti `POST` i metodi `GET` and. 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`. 1. 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`. 1. È 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`** 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 ``` 1. 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 ``` 1. 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' ``` 1. 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. 1. 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`. 1. 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. 1. 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 CloudFormation** + Usa il seguente comando per eliminare le tue CloudFormation risorse. ``` 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 [x-amazon-apigateway-request-Validators.RequestValidator oggetto](api-gateway-swagger-extensions-request-validators.requestValidator.md) nella mappa [x-amazon-apigateway-requestoggetto -validators](api-gateway-swagger-extensions-request-validators.md) 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à [x-amazon-apigateway-requestproprietà -validator](api-gateway-swagger-extensions-request-validator.md) 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](import-export-api-endpoints.md) o una [Importazione di un'API ottimizzata per l'edge in API Gateway](import-edge-optimized-api.md). ------ #### [ 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 } } } ``` ------ # AWS CloudFormation modello di un'API di esempio con convalida delle richieste di base La seguente definizione di modello di CloudFormation esempio definisce un'API di esempio con la convalida della richiesta abilitata. L'API [PetStore è un subset dell'API ](http://petstore-demo-endpoint.execute-api.com/petstore/pets). L'API espone un metodo `POST` per aggiungere un animale domestico alla raccolta `pets` e un metodo `GET` per l'esecuzione di query relative agli animali domestici in base a un tipo specificato. Sono dichiarati due validatori di richiesta: **`GETValidator`** Questo validatore è abilitato nel metodo `GET`. Permette a Gateway API di verificare che il parametro di query obbligatorio (`q1`) sia incluso e non vuoto nella richiesta in entrata. **`POSTValidator`** Questo validatore è abilitato nel metodo `POST`. Consente a Gateway API di verificare che il formato di payload della richiesta sia conforme all'impostazione `RequestBodyModel` specificata quando il tipo di contenuto è `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 contenuto, specifica `$default`. `RequestBodyModel` contiene un modello aggiuntivo, `RequestBodyModelId`, per definire l'ID dell'animale domestico. ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: ReqValidatorsSample RequestBodyModelId: Type: 'AWS::ApiGateway::Model' Properties: RestApiId: !Ref Api ContentType: application/json Description: Request body model for Pet ID. Schema: $schema: 'http://json-schema.org/draft-04/schema#' title: RequestBodyModelId properties: id: type: integer RequestBodyModel: Type: 'AWS::ApiGateway::Model' Properties: RestApiId: !Ref Api ContentType: application/json Description: Request body model for Pet type, name, price, and ID. Schema: $schema: 'http://json-schema.org/draft-04/schema#' title: RequestBodyModel required: - price - name - type type: object properties: id: "$ref": !Sub - 'https://apigateway.amazonaws.com/restapis/${Api}/models/${RequestBodyModelId}' - Api: !Ref Api RequestBodyModelId: !Ref RequestBodyModelId price: type: number minimum: 25 maximum: 500 name: type: string type: type: string enum: - "dog" - "cat" - "fish" GETValidator: Type: AWS::ApiGateway::RequestValidator Properties: Name: params-only RestApiId: !Ref Api ValidateRequestBody: False ValidateRequestParameters: True POSTValidator: Type: AWS::ApiGateway::RequestValidator Properties: Name: body-only RestApiId: !Ref Api ValidateRequestBody: True ValidateRequestParameters: False ValidationResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'validation' ValidationMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref ValidationResource HttpMethod: GET AuthorizationType: NONE RequestValidatorId: !Ref GETValidator RequestParameters: method.request.querystring.q1: true Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ValidationMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref ValidationResource HttpMethod: POST AuthorizationType: NONE RequestValidatorId: !Ref POSTValidator RequestModels: application/json : !Ref RequestBodyModel Integration: Type: HTTP_PROXY IntegrationHttpMethod: POST Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - ValidationMethodGet - RequestBodyModel Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiRootUrl: Description: Root Url of the API Value: !Sub 'https://${Api}.execute-api.${AWS::Region}.amazonaws.com/${StageName}' ``` # Trasformazioni dei dati per REST APIs in API Gateway **Nota** In questa sezione vengono illustrate le funzionalità da utilizzare con un’integrazione non proxy. Tuttavia, è consigliabile, ove possibile, usare un’integrazione proxy per la REST API. L’integrazione proxy ha una configurazione di integrazione più semplice e può evolvere con il backend senza annullare le impostazioni esistenti. Per ulteriori informazioni, consulta [Scegliere un tipo di integrazione API Gateway API](api-gateway-api-integration-types.md). Se si utilizza un’integrazione non proxy, è possibile usare due funzionalità di Gateway API per trasformare la richiesta di metodo e la risposta di integrazione. È possibile trasformare la richiesta di metodo se utilizza un formato di payload diverso rispetto al payload della richiesta di integrazione. È possibile trasformare la risposta di integrazione se restituisce un formato di payload diverso da quello che deve essere restituito nella risposta di metodo. Per ulteriori informazioni sul ciclo di vita della richiesta, consultare [Risorsa di esempio per una REST API](rest-api-develop.md#rest-api-develop-example). L’esempio seguente mostra una trasformazione di dati in cui per l’intestazione `"x-version:beta"`, il parametro di intestazione `x-version` viene trasformato nel parametro di intestazione `app-version`. La trasformazione di dati da `x-version` a `app-version` avviene nella richiesta di integrazione. In questo modo, l’endpoint di integrazione riceve il valore del parametro di intestazione trasformato. Quando l’endpoint di integrazione restituisce un codice di stato, il codice di stato viene trasformato da `200` a `204` prima della risposta di metodo. ![\[Diagramma della trasformazione di dati di Gateway API\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/develop-non-proxy.png) Per creare una trasformazione di dati, è possibile utilizzare le seguenti funzionalità: **Mappatura dei parametri** Nella mappatura dei parametri, è possibile modificare i parametri del percorso URL della richiesta di integrazione, i parametri della stringa di query URL o i valori dell’intestazione HTTP, ma non è possibile modificare il payload della richiesta di integrazione. È inoltre possibile modificare i valori dell’intestazione della risposta HTTP. La mappatura dei parametri si utilizza per creare valori di intestazione statici per CORS (Cross-Origin Resource Sharing). È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per integrazioni proxy e non proxy, ma per usarla per una risposta di integrazione, è necessaria un’integrazione non proxy. La mappatura dei parametri non richiede script in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Per ulteriori informazioni, consulta [Mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping.md). **Trasformazioni dei modelli di mappatura** Nelle trasformazioni dei modelli di mappatura, si usa un modello di mappatura per mappare i parametri del percorso URL, i parametri della stringa di query URL, le intestazioni HTTP e la richiesta di integrazione o il corpo della risposta di integrazione. Un *modello di mappatura* è uno script espresso in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) utilizzando [JSONPath espressioni](https://goessner.net/articles/JsonPath/) e applicato al payload in base all'intestazione. `Content-type` Con un modello di mappatura è possibile eseguire le seguenti operazioni: + Seleziona i dati da inviare utilizzando l'integrazione Servizi AWS, ad esempio le funzioni Amazon DynamoDB o Lambda o gli endpoint HTTP. Per ulteriori informazioni, consulta [Tutorial: modifica la richiesta e la risposta di integrazione per le integrazioni ai servizi AWS](set-up-data-transformations-in-api-gateway.md). + Sostituire in modo condizionale i parametri di richiesta e risposta di integrazione di un’API, creare nuovi valori di intestazione e sostituire i codici di stato. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). È anche possibile specificare il comportamento dell’API quando il corpo di una richiesta di integrazione ha un’intestazione `Content-type` senza modelli di mappatura corrispondenti. Questo processo è chiamato comportamento passthrough di integrazione. Per ulteriori informazioni, consulta [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md). ## Scelta tra mappatura dei parametri e trasformazioni dei modelli di mappatura Quando possibile, è consigliabile utilizzare la mappatura dei parametri per trasformare i dati. Se l’API richiede la modifica del corpo o l’esecuzione di sostituzioni e modifiche condizionali in base alla richiesta o alla risposta di integrazione in entrata e non è possibile utilizzare un’integrazione proxy, si usano le trasformazioni dei modelli di mappatura. # Mappatura dei parametri per REST APIs in API Gateway **Nota** Se si utilizza un’API HTTP, consultare [Trasformazione delle richieste e delle risposte API per API HTTP in Gateway API](http-api-parameter-mapping.md). Nella mappatura dei parametri si mappano i parametri della richiesta o della risposta. È possibile mappare i parametri utilizzando valori statici o espressioni di mappatura dei parametri. Per l’elenco delle espressioni di mappatura, consultare [Riferimento alla fonte di mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping-sources.md). È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per integrazioni proxy e non proxy, ma per usarla per una risposta di integrazione, è necessaria un’integrazione non proxy. Ad esempio, è possibile mappare il parametro di intestazione della richiesta di metodo `puppies` al parametro di intestazione della richiesta di integrazione `DogsAge0`. Quindi, se un client invia l’intestazione `puppies:true` all’API, la richiesta di integrazione invia l’intestazione della richiesta `DogsAge0:true` all’endpoint di integrazione. Nel diagramma seguente viene illustrato il ciclo di vita della richiesta di questo esempio. ![\[Diagramma dell’esempio di mappatura dei parametri di Gateway API per una richiesta\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/parameter-mapping-example1.png) Per eseguire questo esempio utilizzando Gateway API, consultare [Esempio 1: mappare un parametro della richiesta di metodo a un parametro della richiesta di integrazione](request-response-data-mappings.md#request-response-data-mappings-example-1). Inoltre, è possibile mappare il parametro di intestazione `kittens` della risposta di integrazione al parametro di intestazione `CatsAge0` della risposta di metodo. Quindi, se l’endpoint di integrazione restituisce `kittens:false`, il client riceve l’intestazione `CatsAge0:false`. Nel diagramma seguente viene illustrato il ciclo di vita della richiesta di questo esempio. ![\[Diagramma dell’esempio di mappatura dei parametri di Gateway API per una risposta\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/parameter-mapping-example2.png) **Topics** + [Esempi di mappatura dei parametri per REST APIs in API Gateway](request-response-data-mappings.md) + [Riferimento alla fonte di mappatura dei parametri per REST APIs in API Gateway](rest-api-parameter-mapping-sources.md) # Esempi di mappatura dei parametri per REST APIs in API Gateway Gli esempi seguenti mostrano come creare espressioni di mappatura dei parametri utilizzando la console Gateway API, OpenAPI e modelli CloudFormation . Per un esempio di come utilizzare la mappatura dei parametri per creare le intestazioni CORS richieste, consultare [CORS per REST APIs in API Gateway](how-to-cors.md). ## Esempio 1: mappare un parametro della richiesta di metodo a un parametro della richiesta di integrazione L’esempio seguente mappa il parametro di intestazione `puppies` della richiesta di metodo al parametro di intestazione `DogsAge0`della richiesta di integrazione. ------ #### [ Console di gestione AWS ] **Per mappare il parametro della richiesta di metodo** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere un metodo. Il metodo deve disporre di un’integrazione non proxy. 1. Per **Impostazioni della richiesta del metodo** scegliere **Modifica**. 1. Scegli **Intestazioni di richiesta HTTP**. 1. Seleziona **Add header (Aggiungi intestazione)**. 1. In **Nome**, inserisci **puppies**. 1. Scegli **Save** (Salva). 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** per **Impostazioni della richiesta di integrazione**. Aggiunge Console di gestione AWS automaticamente una mappatura dei parametri da `method.request.header.puppies ` a `puppies` per te, ma devi modificare il **nome** in modo che corrisponda al parametro di intestazione della richiesta previsto dall'endpoint di integrazione. 1. In **Nome**, inserisci **DogsAge0**. 1. Scegli **Save** (Salva). 1. Implementa nuovamente l'API per rendere effettive le modifiche. I passaggi seguenti mostrano come verificare che la mappatura dei parametri sia stata completata correttamente. **(Facoltativo) Test della mappatura dei parametri** 1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. 1. In Intestazioni, immetti **puppies:true**. 1. Scegli **Test (Esegui test)**. 1. Nella sezione **Log**, il risultato sarà simile al seguente: ``` Tue Feb 04 00:28:36 UTC 2025 : Method request headers: {puppies=true} Tue Feb 04 00:28:36 UTC 2025 : Method request body before transformations: Tue Feb 04 00:28:36 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets Tue Feb 04 00:28:36 UTC 2025 : Endpoint request headers: {DogsAge0=true, x-amzn-apigateway-api-id=abcd1234, Accept=application/json, User-Agent=AmazonAPIGateway_aaaaaaa, X-Amzn-Trace-Id=Root=1-abcd-12344} ``` Il parametro dell’intestazione della richiesta è cambiato da `puppies` a `DogsAge0`. ------ #### [ CloudFormation ] In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) per importare un file di definizione OpenAPI in Gateway API. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: ParameterMappingExample version: "2025-02-04T00:30:41Z" paths: /pets: get: parameters: - name: puppies in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.DogsAge0: method.request.header.puppies passthroughBehavior: when_no_match type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] ``` { "openapi" : "3.0.1", "info" : { "title" : "ParameterMappingExample", "version" : "2025-02-04T00:30:41Z" }, "paths" : { "/pets" : { "get" : { "parameters" : [ { "name" : "puppies", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.DogsAge0" : "method.request.header.puppies" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } } } ``` ------ ## Esempio 2: mappare più parametri di richiesta di metodo a diversi parametri di richiesta di integrazione L’esempio seguente mappa il parametro della stringa di query della richiesta di metodo con più valori `methodRequestQueryParam` al parametro della stringa di query della richiesta di integrazione `integrationQueryParam` e mappa il parametro dell’intestazione della richiesta di metodo `methodRequestHeaderParam` al parametro del percorso della richiesta di integrazione `integrationPathParam`. ------ #### [ Console di gestione AWS ] **Per mappare i parametri della richiesta di metodo** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere un metodo. Il metodo deve disporre di un’integrazione non proxy. 1. Per **Impostazioni della richiesta del metodo** scegliere **Modifica**. 1. Scegli **Parametri della stringa di query URL**. 1. Scegliere **Add query string (Aggiungi stringa di query)**. 1. In **Nome**, inserisci **methodRequestQueryParam**. 1. Scegli **Intestazioni di richiesta HTTP**. 1. Seleziona **Add header (Aggiungi intestazione)**. 1. In **Nome**, inserisci **methodRequestHeaderParam**. 1. Scegli **Save** (Salva). 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** per **Impostazioni della richiesta di integrazione**. 1. Scegli **Parametri di percorso URL**. 1. Scegli **Aggiungi parametro di percorso**. 1. In **Nome**, inserisci **integrationPathParam**. 1. In **Mappato da**, inserire **method.request.header.methodRequestHeaderParam**. In questo modo l’intestazione della richiesta di metodo specificata nella richiesta di metodo viene mappata a un nuovo parametro del percorso della richiesta di integrazione. 1. Scegli **Parametri della stringa di query URL**. 1. Scegliere **Add query string (Aggiungi stringa di query)**. 1. In **Nome**, inserisci **integrationQueryParam**. 1. In **Mappato da**, inserire **method.request.multivaluequerystring.methodRequestQueryParam**. In questo modo il parametro della stringa di query con più valori viene mappato a un nuovo parametro della stringa di query della richiesta di integrazione a valore singolo. 1. Scegli **Save** (Salva). 1. Implementa nuovamente l'API per rendere effettive le modifiche. ------ #### [ CloudFormation ] In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) per importare un file di definizione OpenAPI in Gateway API. La seguente definizione OpenAPI crea le mappature dei parametri per un’integrazione HTTP: + L’intestazione della richiesta di metodo `methodRequestHeaderParam` nel parametro di percorso della richiesta di integrazione `integrationPathParam` + La stringa di query della richiesta di metodo con più valori `methodRequestQueryParam` nella stringa di query della richiesta di integrazione `integrationQueryParam` ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example 2 version: "2025-01-15T19:12:31Z" paths: /: post: parameters: - name: methodRequestQueryParam in: query schema: type: string - name: methodRequestHeaderParam in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.querystring.integrationQueryParam: method.request.multivaluequerystring.methodRequestQueryParam integration.request.path.integrationPathParam: method.request.header.methodRequestHeaderParam requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La seguente definizione OpenAPI crea le mappature dei parametri per un’integrazione HTTP: + L’intestazione della richiesta di metodo `methodRequestHeaderParam` nel parametro di percorso della richiesta di integrazione `integrationPathParam` + La stringa di query della richiesta di metodo con più valori `methodRequestQueryParam` nella stringa di query della richiesta di integrazione `integrationQueryParam` ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example 2", "version" : "2025-01-15T19:12:31Z" }, "paths" : { "/" : { "post" : { "parameters" : [ { "name" : "methodRequestQueryParam", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "methodRequestHeaderParam", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.querystring.integrationQueryParam" : "method.request.multivaluequerystring.methodRequestQueryParam", "integration.request.path.integrationPathParam" : "method.request.header.methodRequestHeaderParam" }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000, "type" : "http" } } } } } ``` ------ ## Esempio 3: mappare i campi dal corpo della richiesta JSON ai parametri della richiesta di integrazione [Puoi anche mappare i parametri della richiesta di integrazione dai campi del corpo della richiesta JSON utilizzando un'espressione. JSONPath ](http://goessner.net/articles/JsonPath/index.html#e2) L’esempio seguente mappa il corpo della richiesta di metodo a un’intestazione della richiesta di integrazione denominata `body-header` e mappa parte del corpo della richiesta, come indicato da un’espressione JSON, a un’intestazione della richiesta di integrazione denominata `pet-price`. Per testare questo esempio è necessario fornire un input che contenga una categoria di prezzo, come la seguente: ``` [ { "id": 1, "type": "dog", "price": 249.99 } ] ``` ------ #### [ Console di gestione AWS ] **Per mappare i parametri della richiesta di metodo** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere un metodo `POST`, `PUT`, `PATCH` o `ANY`. Il metodo deve disporre di un’integrazione non proxy. 1. Per **Impostazioni della richiesta di integrazione**, scegliere **Modifica**. 1. Scegliere **Parametri delle intestazioni delle richieste URL**. 1. Scegliere **Aggiungi parametro dell’intestazione della richiesta**. 1. In **Nome**, inserisci **body-header**. 1. In **Mappato da**, inserire **method.request.body**. In questo modo il corpo della richiesta di metodo viene mappato a un nuovo parametro di intestazione della richiesta di integrazione. 1. Scegliere **Aggiungi parametro dell’intestazione della richiesta**. 1. In **Nome**, inserisci **pet-price**. 1. In **Mappato da**, inserire ** method.request.body[0].price**. In questo modo una parte del corpo della richiesta di metodo viene mappata a un nuovo parametro di intestazione della richiesta di integrazione. 1. Scegli **Save** (Salva). 1. Implementa nuovamente l'API per rendere effettive le modifiche. ------ #### [ CloudFormation ] In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) per importare un file di definizione OpenAPI in Gateway API. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example 3 version: "2025-01-15T19:19:14Z" paths: /: post: responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.pet-price: method.request.body[0].price integration.request.header.body-header: method.request.body requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 type: http ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La seguente definizione OpenAPI mappa i parametri della richiesta di integrazione dai campi del corpo della richiesta JSON. ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example 3", "version" : "2025-01-15T19:19:14Z" }, "paths" : { "/" : { "post" : { "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.pet-price" : "method.request.body[0].price", "integration.request.header.body-header" : "method.request.body" }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000, "type" : "http" } } } } } ``` ------ ## Esempio 4: mappare la risposta di integrazione alla risposta di metodo È anche possibile mappare la risposta di integrazione alla risposta di metodo. L’esempio seguente mappa il corpo della risposta di integrazione a un’intestazione della risposta di metodo denominata `location`, mappa l’intestazione della risposta di integrazione `x-app-id` all’intestazione della risposta di metodo e mappa l’intestazione `id` della risposta di integrazione con più valori `item` all’intestazione della risposta del metodo `items`. ------ #### [ Console di gestione AWS ] **Per mappare la risposta di integrazione** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Scegliere un metodo. Il metodo deve disporre di un’integrazione non proxy. 1. Scegliere la scheda **Metodo di risposta**, quindi per **Risposta 200** scegliere **Modifica**. 1. Per **Nome intestazione**, scegliere **Aggiungi intestazione**. 1. Creare tre intestazioni denominate **id**, **item** e **location**. 1. Scegli **Save** (Salva). 1. Nella scheda **Risposta di integrazione** scegliere **Modifica** per **Predefinito - Risposta**. 1. In **Mappature intestazione** immettere i seguenti valori. 1. Per **id**, immettere **integration.response.header.x-app-id** 1. Per **elemento**, immettere **integration.response.multivalueheader.item** 1. Per **percorso**, immettere **integration.response.body.redirect.url** 1. Scegli **Save** (Salva). 1. Implementa nuovamente l'API per rendere effettive le modifiche. ------ #### [ CloudFormation ] In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) per importare un file di definizione OpenAPI in Gateway API. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: Parameter mapping example version: "2025-01-15T19:21:35Z" paths: /: post: responses: "200": description: 200 response headers: item: schema: type: string location: schema: type: string id: schema: type: string x-amazon-apigateway-integration: type: http httpMethod: GET uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets responses: default: statusCode: "200" responseParameters: method.response.header.id: integration.response.header.x-app-id method.response.header.location: integration.response.body.redirect.url method.response.header.item: integration.response.multivalueheader.item requestTemplates: application/json: '{"statusCode": 200}' passthroughBehavior: when_no_templates timeoutInMillis: 29000 ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La definizione OpenAPI seguente mappa la risposta di integrazione alla risposta di metodo. ``` { "openapi" : "3.0.1", "info" : { "title" : "Parameter mapping example", "version" : "2025-01-15T19:21:35Z" }, "paths" : { "/" : { "post" : { "responses" : { "200" : { "description" : "200 response", "headers" : { "item" : { "schema" : { "type" : "string" } }, "location" : { "schema" : { "type" : "string" } }, "id" : { "schema" : { "type" : "string" } } } } }, "x-amazon-apigateway-integration" : { "type" : "http", "httpMethod" : "GET", "uri" : "http://petstore-demo-endpoint.execute-api.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200", "responseParameters" : { "method.response.header.id" : "integration.response.header.x-app-id", "method.response.header.location" : "integration.response.body.redirect.url", "method.response.header.item" : "integration.response.multivalueheader.item" } } }, "requestTemplates" : { "application/json" : "{\"statusCode\": 200}" }, "passthroughBehavior" : "when_no_templates", "timeoutInMillis" : 29000 } } } } } ``` ------ # Riferimento alla fonte di mappatura dei parametri per REST APIs in API Gateway Quando si crea una mappatura dei parametri, è possibile specificare i parametri della richiesta di metodo o della risposta di integrazione da modificare e le modalità con cui si desidera modificare tali parametri. La tabella seguente mostra i parametri della richiesta di metodo che è possibile mappare e l’espressione per creare la mappatura. In queste espressioni, *name* è il nome di un parametro di richiesta del metodo. Ad esempio, per mappare il parametro dell’intestazione della richiesta `puppies`, si utilizza l’espressione `method.request.header.puppies`. L’espressione deve corrispondere all’espressione regolare `'^[a-zA-Z0-9._$-]+$]'`. È possibile utilizzare la mappatura dei parametri nella richiesta di integrazione per le integrazioni proxy e non proxy. | **Origine dati mappata** | **Espressione di mappatura** | | --- | --- | | Percorso della richiesta di metodo | method.request.path.name | | Stringa di query della richiesta di metodo | method.request.querystring.name | | Stringa di query multi-valore della richiesta del metodo | method.request.multivaluequerystring.name | | Intestazione della richiesta di metodo | method.request.header.name | | Intestazione multi-valore della richiesta di metodo | method.request.multivalueheader.name | | Corpo della richiesta di metodo | method.request.body | | Corpo della richiesta del metodo (JsonPath) | `method.request.body.JSONPath_EXPRESSION`. *JSONPath\$1EXPRESSION*è un' JSONPath espressione per un campo JSON del corpo di una richiesta. Per ulteriori informazioni, vedere [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). | | Variabili di fase | stageVariables.name | | Variabili di contesto | `context.name` Il nome deve essere una delle [variabili di contesto supportate](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valore statico | `'static_value'`. La *static\$1value* è una stringa letterale e deve essere racchiusa tra virgolette singole. Ad esempio, `'https://www.example.com'`. | La tabella seguente mostra i parametri della risposta di integrazione che è possibile mappare e l’espressione per creare la mappatura. In queste espressioni, *name* è il nome di un parametro di risposta di integrazione. È possibile mappare le intestazioni della risposta di metodo da qualsiasi intestazione o corpo della risposta di integrazione, variabili \$1context o valori statici. Per utilizzare la mappatura dei parametri per una risposta di integrazione, è necessaria un’integrazione non proxy. | Origine dati mappata | Espressione di mappatura | | --- | --- | | Intestazione della risposta di integrazione | integration.response.header.name | | Intestazione della risposta di integrazione | integration.response.multivalueheader.name | | Corpo della risposta di integrazione | integration.response.body | | Corpo della risposta di integrazione (JsonPath) | `integration.response.body.JSONPath_EXPRESSION` *JSONPath\$1EXPRESSION*è un' JSONPath espressione per un campo JSON del corpo di una risposta. Per ulteriori informazioni, vedere [JSONPath expression](http://goessner.net/articles/JsonPath/index.html#e2). | | Variabile di fase | stageVariables.name | | Variabile di contesto | `context.name` Il nome deve essere una delle [variabili di contesto supportate](api-gateway-mapping-template-reference.md#context-variable-reference). | | Valore statico | ` 'static_value'` La *static\$1value* è una stringa letterale e deve essere racchiusa tra virgolette singole. Ad esempio, `'https://www.example.com'`. | # Trasformazioni dei modelli di mappatura per REST APIs in API Gateway Una trasformazione del modello di mappatura utilizza un modello di mappatura per modificare la richiesta o la risposta di integrazione. Un *modello di mappatura* è uno script espresso in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html) e applicato a un payload utilizzando un codice basato sull'intestazione. [JSONPath ](https://goessner.net/articles/JsonPath/)`Content-type` Si utilizzano i modelli di mappatura per le trasformazioni dei modelli di mappatura. Questa sezione descrive le informazioni concettuali relative ai modelli di mappatura. Il diagramma seguente mostra il ciclo di vita della richiesta per una `POST /pets` risorsa che ha un'integrazione con un endpoint di integrazione. PetStore In questa API, un utente invia i dati su un animale domestico e l’endpoint di integrazione restituisce la tariffa di adozione associata all’animale domestico. In questo ciclo di vita della richiesta, le trasformazioni dei modelli di mappatura filtrano il corpo della richiesta all’endpoint di integrazione e il corpo della risposta dall’endpoint di integrazione. ![\[Esempio di ciclo di vita della richiesta\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/mapping-template-transforms.png) Le sezioni seguenti illustrano il ciclo di vita della richiesta e della risposta. ## Richiesta di metodo e richiesta di integrazione Nell’esempio precedente, se il corpo della richiesta inviato alla richiesta di metodo è: ``` POST /pets HTTP/1.1 Host:abcd1234.us-west-2.amazonaws.com Content-type: application/json { "id": 1, "type": "dog", "Age": 11, } ``` Questo corpo della richiesta non è nel formato corretto per essere utilizzato dall’endpoint di integrazione, pertanto Gateway API esegue una trasformazione del modello di mappatura. Gateway API esegue solo una trasformazione del modello di mappatura perché esiste un modello di mappatura definito per Content-Type `application/json`. Se non si definisce un modello di mappatura per Content-Type, per impostazione predefinita, Gateway API passa il corpo all’endpoint di integrazione tramite la richiesta di integrazione. Per modificare questo comportamento, consultare [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md). Il seguente modello di mappatura trasforma i dati della richiesta di metodo nella richiesta di integrazione prima che vengano inviati all’endpoint di integrazione: ``` #set($inputRoot = $input.path('$')) { "dogId" : "dog_"$elem.id, "Age": $inputRoot.Age } ``` 1. La variabile `$inputRoot` rappresenta l'oggetto radice nei dati JSON originali della sezione precedente. Le direttive iniziano con il simbolo `#`. 1. `dog` è una concatenazione di `id` dell’utente e di un valore di stringa. 1. `Age` proviene dal corpo della richiesta di metodo. Quindi, il seguente output viene inoltrato all’endpoint di integrazione: ``` { "dogId" : "dog_1", "Age": 11 } ``` ## Risposta di integrazione e risposta di metodo Dopo l’esito positivo della richiesta all’endpoint di integrazione, l’endpoint invia una risposta alla risposta di integrazione di Gateway API. L’esempio seguente indica i dati di output di un endpoint di integrazione: ``` { "dogId" : "dog_1", "adoptionFee": 19.95, } ``` La risposta di metodo prevede un payload diverso da quello restituito dalla risposta di integrazione. Gateway API esegue una trasformazione del modello di mappatura. Gateway API esegue solo una trasformazione del modello di mappatura perché esiste un modello di mappatura definito per Content-Type `application/json`. Se non si definisce un modello di mappatura per Content-Type, per impostazione predefinita, Gateway API passa il corpo alla risposta di metodo tramite la risposta di integrazione. Per modificare questo comportamento, consultare [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md). ``` #set($inputRoot = $input.path('$')) { "adoptionFee" : $inputRoot.adoptionFee, } ``` Il seguente output viene inviato alla risposta di metodo: ``` {"adoptionFee": 19.95} ``` L’esempio di trasformazione del modello di mappatura è completato. Se possibile, anziché utilizzare trasformazioni di modelli di mappatura, è consigliabile un’integrazione proxy per trasformare i dati. Per ulteriori informazioni, consulta [Scegliere un tipo di integrazione API Gateway API](api-gateway-api-integration-types.md). # Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway Se la richiesta di metodo ha un payload senza modello di mappatura definito per l’intestazione `Content-Type`, è possibile scegliere di passare il payload della richiesta fornito dal client tramite la richiesta di integrazione al backend senza trasformazione. Il processo è noto come passthrough di integrazione. L’effettivo comportamento del passthrough di una richiesta in entrata è determinato da questa impostazione. Sono disponibili tre opzioni: **Opzione Quando nessun modello corrisponde all'intestazione Content-Type della richiesta** Selezionare questa opzione se si desidera che venga eseguito il passthrough del corpo della richiesta di metodo nella richiesta di integrazione al back-end senza trasformazione quando il tipo di contenuto della richiesta di metodo non corrisponde ai tipi di contenuto associati ai modelli di mappatura. Durante la chiamata all'API Gateway API, scegli questa opzione impostando `WHEN_NO_MATCH` come valore della proprietà `passthroughBehavior` in [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). **Quando non ci sono modelli definiti (consigliato)** Selezionare questa opzione se si desidera che venga eseguito il passthrough del corpo della richiesta di metodo nella richiesta di integrazione al back-end senza trasformazione quando nella richiesta di integrazione non è stato definito un modello di mappatura. Se viene definito un modello con questa opzione selezionata, la richiesta di metodo con un payload e un tipo di contenuto che non corrispondono ad alcun modello di mappatura definito verrà rifiutata con una risposta HTTP 415 Tipo di supporto non compatibile. Durante la chiamata all'API Gateway API, scegli questa opzione impostando `WHEN_NO_TEMPLATES` come valore della proprietà `passthroughBehavior` in [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). **Mai** Selezionare questa opzione se non si desidera che venga eseguito il passthrough del corpo della richiesta di metodo nella richiesta di integrazione al back-end senza trasformazione quando nella richiesta di integrazione non è stato definito un modello di mappatura. Se viene definito un modello al momento della selezione di questa opzione, la richiesta di metodo di un tipo di contenuto non mappato sarà rifiutata con la risposta Tipo di supporto non supportato HTTP 415. Durante la chiamata all'API Gateway API, scegli questa opzione impostando `NEVER` come valore della proprietà `passthroughBehavior` in [Integrazione](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). Gli esempi seguenti illustrano i possibili comportamenti del passthrough. Esempio 1: viene definito un modello di mappatura nella richiesta di integrazione per il tipo di contenuto `application/json`. | Content-type | Opzione passthrough | Comportamento | | --- | --- | --- | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1MATCH | Il payload della richiesta viene trasformato utilizzando il modello. | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta viene trasformato utilizzando il modello. | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | NEVER | Il payload della richiesta viene trasformato utilizzando il modello. | | application/json | WHEN\$1NO\$1MATCH | Il payload della richiesta viene trasformato utilizzando il modello. | | application/json | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta viene trasformato utilizzando il modello. | | application/json | NEVER | Il payload della richiesta viene trasformato utilizzando il modello. | | application/xml | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | application/xml | WHEN\$1NO\$1TEMPLATES | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | application/xml | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | Esempio 2: viene definito un modello di mappatura nella richiesta di integrazione per il tipo di contenuto `application/xml`. | Content-type | Opzione passthrough | Comportamento | | --- | --- | --- | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1TEMPLATES | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | application/json | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | application/json | WHEN\$1NO\$1TEMPLATES | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | application/json | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | application/xml | WHEN\$1NO\$1MATCH | Il payload della richiesta viene trasformato utilizzando il modello. | | application/xml | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta viene trasformato utilizzando il modello. | | application/xml | NEVER | Il payload della richiesta viene trasformato utilizzando il modello. | Esempio 3: nessun modello di mappatura viene definito nella richiesta di integrazione | Content-type | Opzione passthrough | Comportamento | | --- | --- | --- | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | Nessuno Gateway API utilizza l’impostazione predefinita `application/json` | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | application/json | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | application/json | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | application/json | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | | application/xml | WHEN\$1NO\$1MATCH | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | application/xml | WHEN\$1NO\$1TEMPLATES | Il payload della richiesta non viene trasformato e viene inviato al back-end inalterato. | | application/xml | NEVER | La richiesta viene respinta con una risposta HTTP 415 Unsupported Media Type. | # Esempio di modello di mappatura aggiuntivo per REST APIs in API Gateway L’esempio seguente mostra un’API per album fotografico in Gateway API che utilizza modelli di mappatura per trasformare i dati delle richieste e delle risposte di integrazione. Utilizza anche modelli di dati per definire i payload della richiesta di metodo e della risposta di integrazione. Per ulteriori informazioni sui modelli di dati, consulta [Modelli di dati per REST APIs](models-mappings-models.md). ## Richiesta di metodo e richiesta di integrazione Di seguito è riportato un modello che definisce il corpo della richiesta di metodo. Questo modello di input richiede che il chiamante carichi una pagina di foto con un minimo di 10 foto per ogni pagina. È possibile utilizzare questo modello di input per generare un SDK o per usare la convalida della richiesta per l’API. Quando si utilizza la convalida della richiesta, se il corpo della richiesta di metodo non aderisce alla struttura dei dati del modello, Gateway API non esegue la richiesta. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosInputModel", "type": "object", "properties": { "photos": { "type": "object", "required" : [ "photo" ], "properties": { "page": { "type": "integer" }, "pages": { "type": "string" }, "perpage": { "type": "integer", "minimum" : 10 }, "total": { "type": "string" }, "photo": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "owner": { "type": "string" }, "photographer_first_name" : {"type" : "string"}, "photographer_last_name" : {"type" : "string"}, "secret": { "type": "string" }, "server": { "type": "string" }, "farm": { "type": "integer" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } } } ``` Di seguito è riportato un esempio di corpo della richiesta di metodo che aderisce alla struttura dei dati del modello di dati precedente. ``` { "photos": { "page": 1, "pages": "1234", "perpage": 100, "total": "123398", "photo": [ { "id": "12345678901", "owner": "23456789@A12", "photographer_first_name" : "Saanvi", "photographer_last_name" : "Sarkar", "secret": "abc123d456", "server": "1234", "farm": 1, "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "owner": "34567890@B23", "photographer_first_name" : "Richard", "photographer_last_name" : "Roe", "secret": "bcd234e567", "server": "2345", "farm": 2, "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } } ``` In questo esempio, quando il corpo della richiesta di metodo precedente viene inviato dal client, il modello di mappatura trasforma il payload in modo che corrisponda al formato richiesto dall’endpoint di integrazione. ``` #set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.ispublic, "isfriend": $elem.isfriend, "isfamily": $elem.isfamily }#if($foreach.hasNext),#end #end ] } ``` L’esempio seguente fornisce i dati di output della trasformazione: ``` { "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } ``` Questi dati vengono inviati alla richiesta di integrazione e quindi all’endpoint di integrazione. ## Risposta di integrazione e risposta di metodo Di seguito è riportato un esempio di modello di output per i dati delle foto dall’endpoint di integrazione. È possibile utilizzare questo metodo per un modello di risposta del metodo, che è necessario quando si genera un SDK tipizzato in modo sicuro per l'API. Ciò garantisce che l'output venga trasmesso in una classe appropriata in Java o Objective-C. ``` { "$schema": "http://json-schema.org/draft-04/schema#", "title": "PhotosOutputModel", "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "photographedBy": { "type": "string" }, "title": { "type": "string" }, "ispublic": { "type": "boolean" }, "isfriend": { "type": "boolean" }, "isfamily": { "type": "boolean" } } } } } } ``` L’endpoint di integrazione potrebbe non generare una risposta che aderisce alla struttura dei dati di questo modello. Ad esempio, la risposta di integrazione potrebbe essere simile alla seguente: ``` "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "description": "My sample photo 1", "public": true, "friend": false, "family": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "description": "My sample photo 1", "public": true, "friend": false, "family": false } ] } ``` Il modello di mappatura di esempio seguente trasforma i dati della risposta di integrazione nel formato previsto dalla risposta di metodo: ``` #set($inputRoot = $input.path('$')) { "photos": [ #foreach($elem in $inputRoot.photos.photo) { "id": "$elem.id", "photographedBy": "$elem.photographer_first_name $elem.photographer_last_name", "title": "$elem.title", "ispublic": $elem.public, "isfriend": $elem.friend, "isfamily": $elem.family }#if($foreach.hasNext),#end #end ] } ``` L’esempio seguente fornisce i dati di output della trasformazione: ``` { "photos": [ { "id": "12345678901", "photographedBy": "Saanvi Sarkar", "title": "Sample photo 1", "ispublic": true, "isfriend": false, "isfamily": false }, { "id": "23456789012", "photographedBy": "Richard Roe", "title": "Sample photo 2", "ispublic": true, "isfriend": false, "isfamily": false } ] } ``` Questi dati vengono inviati alla risposta di metodo e quindi nuovamente al client. # Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway È possibile utilizzare le trasformazioni dei modelli di mappatura per sostituire qualsiasi tipo di parametro della richiesta, intestazione della risposta o codice di stato della risposta. Per utilizzare il modello di mappatura: + Esegui mappature many-to-one dei parametri + Sostituire i parametri dopo l'applicazione delle mappature standard di Gateway API + Mappare i parametri in modo condizionale in base al contenuto del corpo o ad altri valori dei parametri + Creare nuovi parametri in modo programmatico + Sostituire i codici di stato restituiti dall'endpoint di integrazione Le sovrascritture sono finali. Una sovrascrittura può essere applicata a ciascun parametro una sola volta. Se si prova a sovrascrivere lo stesso parametro più volte, Gateway API restituisce una risposta `5XX`. Se occorre sovrascrivere lo stesso parametro più volte in tutto il modello, ti consigliamo di creare una variabile e applicare la sovrascrittura alla fine del modello. Il modello viene applicato solo dopo che l'intero modello è stato analizzato. ## Esempio 1: sostituire il codice di stato in base al corpo di integrazione L’esempio seguente utilizza l’[API di esempio](api-gateway-create-api-from-example.md) per sostituire il codice di stato in base al corpo della risposta di integrazione. ------ #### [ Console di gestione AWS ] **Per sostituire un codice di stato in base al corpo della risposta di integrazione** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona **Create API** (Crea API). 1. Per **API REST**, scegliere **Crea**. 1. Per **Dettagli API**, scegliere **API di esempio**. 1. Seleziona **Create API** (Crea API). Gateway API crea un’API PetStore di esempio. Per recuperare le informazioni su un animale domestico, si utilizza la richiesta di metodo dell’API `GET /pets/{petId}`, dove `{petId}` è un parametro di percorso corrispondente al numero ID di un animale domestico. In questo esempio, si sostituisce il codice di risposta del metodo `GET` con `400` quando viene rilevata una condizione di errore. 1. Nella struttura **Risorse**, scegli il metodo `GET` in `/{petId}`. 1. Innanzitutto, esegui il test dell’attuale implementazione dell’API. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. 1. Per **petId** immetti **-1**, quindi seleziona **Test**. Il **corpo della risposta indica** un errore: out-of-range ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Inoltre, l’ultima riga nella sezione **Log** termina con: `Method completed with status: 200`. L’integrazione è stata completata, ma si è verificato un errore. Ora si sostituisce il codice di stato in base alla risposta di integrazione. 1. Nella scheda **Risposta di integrazione** scegli **Modifica** per **Predefinito - Risposta**. 1. Scegli **Modelli di mappatura**. 1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci quanto segue: ``` #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end ``` Questo modello di mappatura utilizza la variabile `$context.responseOverride.status` per sostituire il codice di stato con `400` se la risposta di integrazione contiene la stringa `error`. 1. Scegli **Save** (Salva). 1. Seleziona la scheda **Test**. 1. Per **petId** immetti **-1**. 1. Nei risultati, il **Response Body** indica un out-of-range errore: ``` { "errors": [ { "key": "GetPetRequest.petId", "message": "The value is out of range." } ] } ``` Tuttavia, l’ultima riga nella sezione **Log** termina ora con: `Method completed with status: 400`. ------ #### [ CloudFormation ] In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) per importare un file di definizione OpenAPI in Gateway API. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: PetStore Example 1 description: Example pet store API. version: "2025-01-14T00:13:18Z" paths: /pets/{petId}: get: parameters: - name: petId in: path required: true schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId} responses: default: statusCode: "200" responseTemplates: application/json: |- #set($inputRoot = $input.path('$')) $input.json("$") #if($inputRoot.toString().contains("error")) #set($context.responseOverride.status = 400) #end requestParameters: integration.request.path.petId: method.request.path.petId passthroughBehavior: when_no_match type: http components: schemas: Pet: type: object properties: id: type: integer type: type: string price: type: number ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La seguente definizione OpenAPI crea la risorsa `GET pets/{petId}` e sostituisce il codice di stato in base al corpo di integrazione. ``` { "openapi" : "3.0.1", "info" : { "title" : "PetStore Example 1", "description" : "Example pet store API.", "version" : "2025-01-14T00:13:18Z" }, "paths" : { "/pets/{petId}" : { "get" : { "parameters" : [ { "name" : "petId", "in" : "path", "required" : true, "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets/{petId}", "responses" : { "default" : { "statusCode" : "200", "responseTemplates" : { "application/json" : "#set($inputRoot = $input.path('$'))\n$input.json(\"$\")\n#if($inputRoot.toString().contains(\"error\"))\n#set($context.responseOverride.status = 400)\n#end" } } }, "requestParameters" : { "integration.request.path.petId" : "method.request.path.petId" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } }, "components" : { "schemas" : { "Pet" : { "type" : "object", "properties" : { "id" : { "type" : "integer" }, "type" : { "type" : "string" }, "price" : { "type" : "number" } } } } } } ``` ------ ## Esempio 2: sostituire l’intestazione della richiesta e creare nuove intestazioni L’esempio seguente utilizza l’[API di esempio](api-gateway-create-api-from-example.md) per sostituire l’intestazione della richiesta e creare nuove intestazioni. ------ #### [ Console di gestione AWS ] **Per sostituire un’intestazione della richiesta di metodo creando una nuova intestazione** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegli l’API di esempio creata nel tutorial precedente. Il nome dell'API dovrebbe essere. **PetStore** 1. Nella struttura **Risorse**, scegli il metodo `GET` in `/pet`. 1. Nella scheda **Richiesta metodo** scegli **Modifica** in **Impostazioni della richiesta del metodo**. 1. Scegli **Intestazioni di richiesta HTTP**, quindi seleziona **Aggiungi intestazione**. 1. In **Nome**, inserisci **header1**. 1. Scegli **Aggiungi intestazione**, quindi crea una seconda intestazione chiamata **header2**. 1. Scegli **Save** (Salva). Ora, si combinano queste intestazioni in un unico valore di intestazione utilizzando un modello di mappatura. 1. Nella scheda **Richiesta di integrazione** seleziona **Modifica** per **Impostazioni della richiesta di integrazione**. 1. Per **Richiesta corpo passthrough** scegli **Quando non ci sono modelli definiti (consigliato)**. 1. Scegli **Modelli di mappatura** e procedi come indicato di seguito: 1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci quanto segue: ``` #set($header1Override = "pets") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value]) ``` Questo modello di mappatura sostituisce `header1` con la stringa `pets` e crea un’intestazione con più valori chiamata `$header3Value` che combina `header1` e `header2`. 1. Scegli **Save** (Salva). 1. Seleziona la scheda **Test**. 1. In **Intestazioni**, copiare il codice seguente: ``` header1:header1Val header2:header2Val ``` 1. Scegli **Test (Esegui test)**. Nella sezione **Log** è presente una voce che include questo testo: ``` Endpoint request headers: {header3=header1Valheader2Val, header2=header2Val, header1=pets, x-amzn-apigateway-api-id=api-id, Accept=application/json, multivalueheader=pets,header1Valheader2Val} ``` ------ #### [ CloudFormation ] In questo esempio, si utilizza la proprietà [body](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-apigateway-restapi.html#cfn-apigateway-restapi-body) per importare un file di definizione OpenAPI in Gateway API. ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Body: openapi: 3.0.1 info: title: PetStore Example 2 description: Example pet store API. version: "2025-01-14T00:36:18Z" paths: /pets: get: parameters: - name: header2 in: header schema: type: string - name: page in: query schema: type: string - name: type in: query schema: type: string - name: header1 in: header schema: type: string responses: "200": description: 200 response x-amazon-apigateway-integration: httpMethod: GET uri: http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets responses: default: statusCode: "200" requestParameters: integration.request.header.header1: method.request.header.header1 integration.request.header.header2: method.request.header.header2 integration.request.querystring.page: method.request.querystring.page integration.request.querystring.type: method.request.querystring.type requestTemplates: application/json: |- #set($header1Override = "pets") #set($header3Value = "$input.params('header1')$input.params('header2')") $input.json("$") #set($context.requestOverride.header.header3 = $header3Value) #set($context.requestOverride.header.header1 = $header1Override) #set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value]) passthroughBehavior: when_no_match type: http components: schemas: Pet: type: object properties: id: type: integer type: type: string price: type: number ApiGatewayDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api ApiGatewayDeployment20250219: Type: 'AWS::ApiGateway::Deployment' DependsOn: Api Properties: RestApiId: !Ref Api Stage: Type: 'AWS::ApiGateway::Stage' Properties: DeploymentId: !Ref ApiGatewayDeployment20250219 RestApiId: !Ref Api StageName: prod ``` ------ #### [ OpenAPI ] La seguente definizione OpenAPI crea la risorsa `GET pets`, sostituisce l’intestazione della richiesta e crea nuove intestazioni. ``` { "openapi" : "3.0.1", "info" : { "title" : "PetStore Example 2", "description" : "Example pet store API.", "version" : "2025-01-14T00:36:18Z" }, "paths" : { "/pets" : { "get" : { "parameters" : [ { "name" : "header2", "in" : "header", "schema" : { "type" : "string" } }, { "name" : "page", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "type", "in" : "query", "schema" : { "type" : "string" } }, { "name" : "header1", "in" : "header", "schema" : { "type" : "string" } } ], "responses" : { "200" : { "description" : "200 response" } }, "x-amazon-apigateway-integration" : { "httpMethod" : "GET", "uri" : "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets", "responses" : { "default" : { "statusCode" : "200" } }, "requestParameters" : { "integration.request.header.header1" : "method.request.header.header1", "integration.request.header.header2" : "method.request.header.header2", "integration.request.querystring.page" : "method.request.querystring.page", "integration.request.querystring.type" : "method.request.querystring.type" }, "requestTemplates" : { "application/json" : "#set($header1Override = \"pets\")\n#set($header3Value = \"$input.params('header1')$input.params('header2')\")\n$input.json(\"$\")\n#set($context.requestOverride.header.header3 = $header3Value)\n#set($context.requestOverride.header.header1 = $header1Override)\n#set($context.requestOverride.header.multivalueheader=[$header1Override, $header3Value])" }, "passthroughBehavior" : "when_no_match", "type" : "http" } } } } } ``` ------ Per utilizzare la sostituzione di un modello di mappatura, si aggiunge una o più delle seguenti variabili `$context`. Per l’elenco delle variabili `$context`, consultare [Variabili di contesto per le trasformazioni dei dati](api-gateway-mapping-template-reference.md#context-variable-reference). # Tutorial: modifica la richiesta e la risposta di integrazione per le integrazioni ai servizi AWS Il seguente tutorial mostra come utilizzare le trasformazioni dei modelli di mappatura per configurare i modelli di mappatura per trasformare le richieste e le risposte di integrazione utilizzando la console e la CLI. AWS **Topics** + [Configurare la trasformazione dei dati utilizzando la console Gateway Amazon API](#mapping-example-console) + [Configura la trasformazione dei dati utilizzando la AWS CLI](#mapping-example-cli) + [CloudFormation Modello di trasformazione dei dati completato](#api-gateway-data-transformations-full-cfn-stack) ## Configurare la trasformazione dei dati utilizzando la console Gateway Amazon API [In questo tutorial, creerai un'API incompleta e una tabella DynamoDB utilizzando il seguente file.zip .zip. data-transformation-tutorial-console](samples/data-transformation-tutorial-console.zip) Questa API incompleta dispone di una risorsa `/pets`  con i metodi `GET` e `POST`. + Il metodo `GET` otterrà i dati dall'endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. I dati di output verranno trasformati in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). + Il metodo `POST` consentirà all'utente di pubblicare (`POST`) le informazioni sugli animali domestici in una tabella Amazon DynamoDB utilizzando un modello di mappatura. Scarica e decomprimi il modello di creazione [dell'](samples/data-transformation-tutorial-console.zip)app per. CloudFormation Verrà utilizzato questo modello per creare una tabella DynamoDB per pubblicare informazioni sugli animali domestici e un'API incompleta. Il resto della procedura verrà completato nella console Gateway Amazon API. **Per creare una pila CloudFormation** 1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/) 1. Scegliere **Create stack (Crea stack)**, quindi **With new resources (standard) (Con nuove risorse (standard))**. 1. In **Specificare modello**, scegliere **Carica un file modello**. 1. Selezionare il modello scaricato. 1. Scegli **Next (Successivo)**. 1. Per **Stack name (Nome stack)**, inserire **data-transformation-tutorial-console**, quindi scegliere **Next (Avanti)**. 1. Per **Configure stack options (Configura opzioni di stack)**, scegliere **Next (Successivo)**. 1. Per quanto riguarda **le funzionalità**, riconosci che CloudFormation puoi creare risorse IAM nel tuo account. 1. Scegli **Avanti**, quindi scegli **Invia**. CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Quando lo stato del tuo CloudFormation stack è **CREATE\$1COMPLETE**, sei pronto per passare alla fase successiva. **Test della risposta di integrazione `GET`** 1. Nella scheda **Risorse** dello CloudFormation stack di**data-transformation-tutorial-console**, seleziona l'ID fisico della tua API. 1. Nel pannello di navigazione principale scegli **Risorse**, quindi seleziona il metodo **GET**. 1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. L'output del test mostrerà quanto segue: ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Questo output verrà trasformato in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). **Trasformazione della risposta di integrazione `GET`** 1. Scegli la scheda **Risposta di integrazione**. Attualmente non sono definiti modelli di mappatura, quindi la risposta di integrazione non verrà trasformata. 1. Per **Predefinito - Risposta** scegli **Modifica**. 1. Scegli **Modelli di mappatura** e procedi come indicato di seguito: 1. Scegliere **Add mapping template (Aggiungi modello di mappatura)**. 1. Per **Tipo di contenuto** inserisci **application/json**. 1. Per **Corpo del modello** inserisci quanto segue: ``` #set($inputRoot = $input.path('$')) [ #foreach($elem in $inputRoot) { "description" : "Item $elem.id is a $elem.type.", "askingPrice" : $elem.price }#if($foreach.hasNext),#end #end ] ``` Scegli **Save** (Salva). **Test della risposta di integrazione `GET`** + Scegli la scheda **Test**, quindi seleziona **Test**. L'output del test mostrerà la risposta trasformata. ``` [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] ``` **Trasformazione dei dati di input dal metodo `POST`** 1. Scegli il metodo **POST**. 1. Scegli la scheda **Richiesta di integrazione**, quindi seleziona **Modifica** per **Impostazioni della richiesta di integrazione**. Il CloudFormation modello ha compilato alcuni campi di richiesta di integrazione. + Il tipo di integrazione è Servizio AWS. + Servizio AWS Si tratta di DynamoDB. + Il metodo HTTP è `POST`. + L'operazione è `PutItem`. + Il ruolo di esecuzione che consente ad API Gateway di inserire un elemento nella tabella DynamoDB è. `data-transformation-tutorial-console-APIGatewayRole` CloudFormation ha creato questo ruolo per consentire ad API Gateway di disporre delle autorizzazioni minime per interagire con DynamoDB. Il nome della tabella DynamoDB non è stato specificato. Il nome verrà specificato nei passaggi seguenti. 1. Per **Richiesta corpo passthrough** seleziona **Mai**. Ciò significa che l'API rifiuterà i dati con Content-Types che non dispongono di un modello di mappatura. 1. Scegli **Modelli di mappatura**. 1. **Tipo di contenuto** è impostato su `application/json`. Ciò significa che i tipi di contenuto che non lo sono application/json verranno rifiutati dall'API. Per ulteriori informazioni sui comportamenti passthrough di integrazione, consultare [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md). 1. Inserire il codice seguente nell'editor di testo. ``` { "TableName":"data-transformation-tutorial-console-ddb", "Item": { "id": { "N": $input.json("$.id") }, "type": { "S": $input.json("$.type") }, "price": { "N": $input.json("$.price") } } } ``` Questo modello specifica la tabella come `data-transformation-tutorial-console-ddb` e imposta gli elementi come `id`, `type` e`price`. Gli elementi proverranno dal corpo del metodo `POST`. È anche possibile utilizzare un modello di dati per creare un modello di mappatura. Per ulteriori informazioni, consulta [Richiedi la convalida per REST APIs in API Gateway](api-gateway-method-request-validation.md). 1. Scegliere il pulsante **Salva** per salvare il modello di mappatura. **Aggiunta di un metodo e una risposta di integrazione dal metodo `POST`** Hanno CloudFormation creato un metodo vuoto e una risposta di integrazione. Questa risposta verrà modificata per fornire ulteriori informazioni. Per ulteriori informazioni su come modificare le risposte, consultare [Esempi di mappatura dei parametri per REST APIs in API Gateway](request-response-data-mappings.md). 1. Nella scheda **Risposta di integrazione** scegli **Modifica** per **Predefinito - Risposta**. 1. Scegli **Modelli di mappatura**, quindi seleziona **Aggiungi modello di mappatura**. 1. Per **Content-type** immetti **application/json**. 1. Nell'editor di codice, inserire il seguente modello di mappatura di output per inviare un messaggio di output: ``` { "message" : "Your response was recorded at $context.requestTime" } ``` Per ulteriori informazioni sulle variabili di contesto, consultare [Variabili di contesto per le trasformazioni dei dati](api-gateway-mapping-template-reference.md#context-variable-reference). 1. Scegliere il pulsante **Salva** per salvare il modello di mappatura. **Test del metodo `POST`** Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. 1. Nel corpo della richiesta, inserire il seguente esempio. ``` { "id": "4", "type" : "dog", "price": "321" } ``` 1. Scegli **Test (Esegui test)**. L'output dovrebbe mostrare il messaggio di operazione riuscita. Puoi aprire la console DynamoDB [https://console.aws.amazon.com/dynamodb/](https://console.aws.amazon.com/dynamodb/)all'indirizzo per verificare che l'elemento di esempio sia nella tua tabella. **Per eliminare uno stack CloudFormation** 1. Apri la CloudFormation console in [https://console.aws.amazon.com/cloudformation.](https://console.aws.amazon.com/cloudformation/) 1. Seleziona il tuo stack. CloudFormation 1. Scegli **Elimina** e conferma la tua scelta. ## Configura la trasformazione dei dati utilizzando la AWS CLI [In questo tutorial, creerai un'API incompleta e una tabella DynamoDB utilizzando il seguente file.zip .zip. data-transformation-tutorial-cli](samples/data-transformation-tutorial-cli.zip) Questa API incompleta dispone di una risorsa `/pets` con un metodo `GET` integrato con l'endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. Verrà creato un metodo `POST` per connettersi a una tabella DynamoDB e si useranno modelli di mappatura per inserire dati in una tabella DynamoDB. + I dati di output verranno quindi trasformati in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). + Verrà creato un metodo `POST` per consentire all'utente di pubblicare (`POST`) le informazioni sugli animali domestici in una tabella Amazon DynamoDB utilizzando un modello di mappatura. **Per creare uno stack CloudFormation** Scarica e decomprimi [il modello di creazione dell'app](samples/data-transformation-tutorial-cli.zip) per. CloudFormation Per completare il tutorial seguente, è necessario disporre della [AWS Command Line Interface (AWS CLI) versione 2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). 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](https://learn.microsoft.com/en-us/windows/wsl/install). 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. Usa il seguente comando per creare lo CloudFormation stack. ``` aws cloudformation create-stack --stack-name data-transformation-tutorial-cli --template-body file://data-transformation-tutorial-cli.zip --capabilities CAPABILITY_NAMED_IAM ``` 1. CloudFormation fornisce le risorse specificate nel modello. Per completare il provisioning delle risorse, potrebbero essere necessari alcuni minuti. Usa il comando seguente per vedere lo stato del tuo CloudFormation stack. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli ``` 1. Quando lo stato dello CloudFormation stack è`StackStatus: "CREATE_COMPLETE"`, usa il seguente comando per recuperare i valori di output pertinenti per i passaggi futuri. ``` aws cloudformation describe-stacks --stack-name data-transformation-tutorial-cli --query "Stacks[*].Outputs[*].{OutputKey: OutputKey, OutputValue: OutputValue, Description: Description}" ``` Di seguito sono riportati i valori di output: + ApiRole, che è il nome del ruolo che consente ad API Gateway di inserire elementi nella tabella DynamoDB. Per questo tutorial, il nome del ruolo è `data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG`. + DDBTableNome, che è il nome della tabella DynamoDB. Per questo tutorial il nome della tabella è `data-transformation-tutorial-cli-ddb`. + ResourceId, che è l'ID della risorsa pets in cui sono esposti i `POST` metodi `GET` and. Per questo tutorial, l'ID risorsa è `efg456`. + ApiId, che è l'ID dell'API. Per questo tutorial, l'ID API è `abc123`. **Test del metodo `GET` prima della trasformazione dei dati** + Utilizzare il seguente comando per eseguire il test del metodo `GET`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET ``` L'output del test riporterà le seguenti informazioni. ``` [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Questo output verrà trasformato in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). **Trasformazione della risposta di integrazione `GET`** + Utilizzare il comando seguente per aggiornare una risposta di integrazione per il metodo `GET`. Sostituisci *rest-api-id* e *resource-id* con i tuoi valori. Per creare una risposta di integrazione, utilizzare il comando seguente. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]"}' ``` **Test del metodo `GET`** + Utilizzare il seguente comando per eseguire il test del metodo `GET`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method GET \ ``` L'output del test mostrerà la risposta trasformata. ``` [ { "description" : "Item 1 is a dog.", "askingPrice" : 249.99 }, { "description" : "Item 2 is a cat.", "askingPrice" : 124.99 }, { "description" : "Item 3 is a fish.", "askingPrice" : 0.99 } ] ``` **Creazione di un metodo `POST`** 1. Utilizzare il seguente comando per creare un nuovo metodo nella risorsa `/pets`. ``` aws apigateway put-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --authorization-type "NONE" \ ``` Questo metodo ti consentirà di inviare informazioni sugli animali domestici alla tabella DynamoDB che hai creato nello stack. CloudFormation 1. Utilizzate il seguente comando per creare un' Servizio AWS integrazione sul metodo. `POST` ``` aws apigateway put-integration --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --type AWS \ --integration-http-method POST \ --uri "arn:aws:apigateway:us-east-2:dynamodb:action/PutItem" \ --credentials arn:aws:iam::111122223333:role/data-transformation-tutorial-cli-APIGatewayRole-ABCDEFG \ --request-templates '{"application/json":"{\"TableName\":\"data-transformation-tutorial-cli-ddb\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}"}' ``` 1. Utilizzare il comando seguente per creare una risposta del metodo per una corretta chiamata del metodo `POST`. ``` aws apigateway put-method-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 ``` 1. Utilizzare il comando seguente per creare una risposta dell'integrazione per una corretta chiamata del metodo `POST`. ``` aws apigateway put-integration-response --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --status-code 200 \ --selection-pattern "" \ --response-templates '{"application/json": "{\"message\": \"Your response was recorded at $context.requestTime\"}"}' ``` **Test del metodo `POST`** + Utilizzare il seguente comando per eseguire il test del metodo `POST`. ``` aws apigateway test-invoke-method --rest-api-id abc123 \ --resource-id efg456 \ --http-method POST \ --body '{\"id\": \"4\", \"type\": \"dog\", \"price\": \"321\"}' ``` L'output mostrerà il messaggio di operazione riuscita. **Per eliminare una CloudFormation pila** + Usa il seguente comando per eliminare le tue CloudFormation risorse. ``` aws cloudformation delete-stack --stack-name data-transformation-tutorial-cli ``` ## CloudFormation Modello di trasformazione dei dati completato L'esempio seguente è un CloudFormation modello completo, che crea un'API e una tabella DynamoDB con `/pets` una risorsa `GET` con metodi and. `POST` + Il metodo `GET` recupererà i dati dall'endpoint HTTP `http://petstore-demo-endpoint.execute-api.com/petstore/pets`. I dati di output verranno trasformati in base al modello di mappatura in [Trasformazioni dei modelli di mappatura per REST APIs in API Gateway](models-mappings.md). + Il metodo `POST` consentirà all'utente di pubblicare (`POST`) le informazioni sugli animali domestici in una tabella DynamoDB utilizzando un modello di mappatura. ### Modello di esempio CloudFormation ``` AWSTemplateFormatVersion: 2010-09-09 Description: A completed Amazon API Gateway REST API that uses non-proxy integration to POST to an Amazon DynamoDB table and non-proxy integration to GET transformed pets data. Parameters: StageName: Type: String Default: v1 Description: Name of API stage. Resources: DynamoDBTable: Type: 'AWS::DynamoDB::Table' Properties: TableName: !Sub data-transformation-tutorial-complete AttributeDefinitions: - AttributeName: id AttributeType: N KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: 5 WriteCapacityUnits: 5 APIGatewayRole: Type: 'AWS::IAM::Role' Properties: AssumeRolePolicyDocument: Version: 2012-10-17 Statement: - Action: - 'sts:AssumeRole' Effect: Allow Principal: Service: - apigateway.amazonaws.com Policies: - PolicyName: APIGatewayDynamoDBPolicy PolicyDocument: Version: 2012-10-17 Statement: - Effect: Allow Action: - 'dynamodb:PutItem' Resource: !GetAtt DynamoDBTable.Arn Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: data-transformation-complete-api ApiKeySourceType: HEADER PetsResource: Type: 'AWS::ApiGateway::Resource' Properties: RestApiId: !Ref Api ParentId: !GetAtt Api.RootResourceId PathPart: 'pets' PetsMethodGet: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: GET ApiKeyRequired: false AuthorizationType: NONE Integration: Type: HTTP Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ PassthroughBehavior: WHEN_NO_TEMPLATES IntegrationResponses: - StatusCode: '200' ResponseTemplates: application/json: "#set($inputRoot = $input.path(\"$\"))\n[\n#foreach($elem in $inputRoot)\n {\n \"description\": \"Item $elem.id is a $elem.type\",\n \"askingPrice\": \"$elem.price\"\n }#if($foreach.hasNext),#end\n\n#end\n]" MethodResponses: - StatusCode: '200' PetsMethodPost: Type: 'AWS::ApiGateway::Method' Properties: RestApiId: !Ref Api ResourceId: !Ref PetsResource HttpMethod: POST ApiKeyRequired: false AuthorizationType: NONE Integration: Type: AWS Credentials: !GetAtt APIGatewayRole.Arn IntegrationHttpMethod: POST Uri: arn:aws:apigateway:us-west-1:dynamodb:action/PutItem PassthroughBehavior: NEVER RequestTemplates: application/json: "{\"TableName\":\"data-transformation-tutorial-complete\",\"Item\":{\"id\":{\"N\":$input.json(\"$.id\")},\"type\":{\"S\":$input.json(\"$.type\")},\"price\":{\"N\":$input.json(\"$.price\")} }}" IntegrationResponses: - StatusCode: 200 ResponseTemplates: application/json: "{\"message\": \"Your response was recorded at $context.requestTime\"}" MethodResponses: - StatusCode: '200' ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api StageName: !Sub '${StageName}' Outputs: ApiId: Description: API ID for CLI commands Value: !Ref Api ResourceId: Description: /pets resource ID for CLI commands Value: !Ref PetsResource ApiRole: Description: Role ID to allow API Gateway to put and scan items in DynamoDB table Value: !Ref APIGatewayRole DDBTableName: Description: DynamoDB table name Value: !Ref DynamoDBTable ``` # Esempi di utilizzo di variabili per trasformazioni dei modelli di mappatura per Gateway API L’esempio seguente mostra come utilizzare le variabili `$context`, `input` e `util` nei modelli di mappatura. È possibile utilizzare un’integrazione fittizia o un’integrazione non proxy Lambda che restituisce l’evento di input a Gateway API. Per l’elenco di tutte le variabili supportate per le trasformazioni dei dati, consultare [Variabili per le trasformazioni dei dati per Gateway API](api-gateway-mapping-template-reference.md). ## Esempio 1: passare più variabili `$context` all’endpoint di integrazione L'esempio seguente mostra un modello di mappatura che mappa variabili `$context` in ingresso a variabili back-end con nomi leggermente diversi nel payload di una richiesta di integrazione: ``` { "stage" : "$context.stage", "request_id" : "$context.requestId", "api_id" : "$context.apiId", "resource_path" : "$context.resourcePath", "resource_id" : "$context.resourceId", "http_method" : "$context.httpMethod", "source_ip" : "$context.identity.sourceIp", "user-agent" : "$context.identity.userAgent", "account_id" : "$context.identity.accountId", "api_key" : "$context.identity.apiKey", "caller" : "$context.identity.caller", "user" : "$context.identity.user", "user_arn" : "$context.identity.userArn" } ``` L'output di questo modello di mappatura deve essere analogo al seguente: ``` { stage: 'prod', request_id: 'abcdefg-000-000-0000-abcdefg', api_id: 'abcd1234', resource_path: '/', resource_id: 'efg567', http_method: 'GET', source_ip: '192.0.2.1', user-agent: 'curl/7.84.0', account_id: '111122223333', api_key: 'MyTestKey', caller: 'ABCD-0000-12345', user: 'ABCD-0000-12345', user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar' } ``` Una delle variabili è una chiave API. L'esempio presuppone che il metodo richieda una chiave API. ## Esempio 2: passare tutti i parametri della richiesta all’endpoint di integrazione tramite un payload JSON L’esempio seguente passa tutti i parametri della richiesta, inclusi `path`, `querystring` e `header`, all’endpoint di integrazione tramite un payload JSON: ``` #set($allParams = $input.params()) { "params" : { #foreach($type in $allParams.keySet()) #set($params = $allParams.get($type)) "$type" : { #foreach($paramName in $params.keySet()) "$paramName" : "$util.escapeJavaScript($params.get($paramName))" #if($foreach.hasNext),#end #end } #if($foreach.hasNext),#end #end } } ``` Se una richiesta ha i seguenti parametri di input: + Un parametro di percorso denominato `myparam` + Parametri della stringa di query `querystring1=value1,value2` + Intestazioni `"header1" : "value1"`. L'output di questo modello di mappatura deve essere analogo al seguente: ``` {"params":{"path":{"example2":"myparamm"},"querystring":{"querystring1":"value1,value2"},"header":{"header1":"value1"}}} ``` ## Esempio 3: passare una sezione secondaria di una richiesta di metodo all’endpoint di integrazione L’esempio seguente utilizza il parametro di input `name` per recuperare solo il parametro `name` e il parametro di input `input.json('$')` per recuperare l’intero corpo della richiesta di metodo: ``` { "name" : "$input.params('name')", "body" : $input.json('$') } ``` Per una richiesta che include i parametri della stringa di query `name=Bella&type=dog` e il corpo seguente: ``` { "Price" : "249.99", "Age": "6" } ``` L'output di questo modello di mappatura deve essere analogo al seguente: ``` { "name" : "Bella", "body" : {"Price":"249.99","Age":"6"} } ``` Questo modello di mappatura rimuove il parametro della stringa di query `type=dog`. Se l'input JSON contiene caratteri senza escape che non possono essere analizzati, API JavaScript Gateway potrebbe restituire una risposta 400. Applica `$util.escapeJavaScript($input.json('$'))` per assicurare che l'input JSON possa essere analizzato correttamente. L'esempio precedente con `$util.escapeJavaScript($input.json('$'))` applicato risulta come segue: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$'))" } ``` In questo caso, l'output di questo modello di mappatura deve essere analogo al seguente: ``` { "name" : "Bella", "body": {"Price":"249.99","Age":"6"} } ``` ## Esempio 4: usa l' JSONPath espressione per passare una sottosezione di una richiesta di metodo all'endpoint di integrazione L'esempio seguente utilizza le JSONPath espressioni per recuperare solo il parametro di input `name` e il testo `Age` dal corpo della richiesta: ``` { "name" : "$input.params('name')", "body" : $input.json('$.Age') } ``` Per una richiesta che include i parametri della stringa di query `name=Bella&type=dog` e il corpo seguente: ``` { "Price" : "249.99", "Age": "6" } ``` L'output di questo modello di mappatura deve essere analogo al seguente: ``` { "name" : "Bella", "body" : "6" } ``` Questo modello di mappatura rimuove il parametro della stringa di query `type=dog` e il campo `Price` dal corpo. Se il payload di una richiesta di metodo contiene caratteri senza escape che non possono essere analizzati, API JavaScript Gateway potrebbe restituire una risposta. `400` Applica `$util.escapeJavaScript()` per assicurare che l'input JSON possa essere analizzato correttamente. L'esempio precedente con `$util.escapeJavaScript($input.json('$.Age'))` applicato risulta come segue: ``` { "name" : "$input.params('name')", "body" : "$util.escapeJavaScript($input.json('$.Age'))" } ``` In questo caso, l'output di questo modello di mappatura deve essere analogo al seguente: ``` { "name" : "Bella", "body": "\"6\"" } ``` ## Esempio 5: utilizzare un' JSONPath espressione per passare informazioni su una richiesta di metodo all'endpoint di integrazione L’esempio seguente utilizza `$input.params()`, `$input.path()` e `$input.json()` per inviare informazioni su una richiesta di metodo all’endpoint di integrazione. Questo modello di mappatura utilizza il metodo `size()` per fornire il numero di elementi di un elenco. ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : $input.json('$.things') } ``` Per una richiesta che include il parametro di percorso `123` e il corpo seguente: ``` { "things": { "1": {}, "2": {}, "3": {} } } ``` L'output di questo modello di mappatura deve essere analogo al seguente: ``` {"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}} ``` Se il payload di una richiesta di metodo contiene caratteri senza escape che non possono essere analizzati, API JavaScript Gateway potrebbe restituire una risposta. `400` Applica `$util.escapeJavaScript()` per assicurare che l'input JSON possa essere analizzato correttamente. L'esempio precedente con `$util.escapeJavaScript($input.json('$.things'))` applicato risulta come segue: ``` { "id" : "$input.params('id')", "count" : "$input.path('$.things').size()", "things" : "$util.escapeJavaScript($input.json('$.things'))" } ``` L'output di questo modello di mappatura deve essere analogo al seguente: ``` {"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"} ``` # Variabili per le trasformazioni dei dati per Gateway API Quando si crea una mappatura dei parametri, è possibile utilizzare le variabili di contesto come origine dati. Per creare le trasformazioni di modelli di mappatura, è possibile utilizzare variabili di contesto, input e util negli script scritti in [Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Per modelli di mappatura di esempio che utilizzano queste variabili di riferimento, consultare [Esempi di utilizzo di variabili per trasformazioni dei modelli di mappatura per Gateway API](api-gateway-mapping-variable-examples.md). Per l’elenco delle variabili di riferimento per la registrazione degli accessi, consultare [Variabili per la registrazione dei log degli accessi per Gateway API](api-gateway-variables-for-access-logging.md). ## Variabili di contesto per le trasformazioni dei dati È possibile utilizzare le seguenti variabili `$context` con distinzione tra maiuscole e minuscole per le trasformazioni dei dati. | Parametro | Description | | --- | --- | | \$1context.accountId | L'ID dell' AWS account del proprietario dell'API. | | \$1context.apiId | Identificatore assegnato da API Gateway all'API. | | \$1context.authorizer.claims.property | Proprietà delle richieste restituite dal pool di utenti di Amazon Cognito dopo che l'intermediario del metodo viene autenticato correttamente. Per ulteriori informazioni, consulta [Controlla l'accesso a REST APIs utilizzando i pool di utenti di Amazon Cognito come autorizzatore](apigateway-integrate-with-cognito.md). La chiamata di `$context.authorizer.claims` restituisce null. | | \$1context.authorizer.principalId | Identificazione dell'utente dell'entità principale associata al token inviata dal client e restituita da un'autorizzazione Lambda in API Gateway (precedentemente noto come autorizzazione ad hoc). Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.authorizer.property | Valore in formato stringa della coppia chiave/valore specificata della mappa `context` restituita da una funzione delle autorizzazioni Lambda di API Gateway. Ad esempio, se le autorizzazioni restituiscono la mappa `context` seguente: 
"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}
La chiamata di `$context.authorizer.key` restituisce la stringa `"value"`, la chiamata di `$context.authorizer.numKey` restituisce la stringa `"1"` e la chiamata di `$context.authorizer.boolKey` restituisce la stringa `"true"`. Infatti*property*, l'unico carattere speciale supportato è il carattere di sottolineatura`(_)`. Per ulteriori informazioni, consulta [Uso di autorizzazioni Lambda di API Gateway](apigateway-use-lambda-authorizer.md). | | \$1context.awsEndpointRequestId | L'ID della richiesta dell' AWS endpoint. | | \$1context.deploymentId | ID dell'implementazione API. | | \$1context.domainName | Nome di dominio completo usato per richiamare l'API. Deve essere lo stesso dell'intestazione `Host` in ingresso. | | \$1context.domainPrefix | Prima etichetta di `$context.domainName`. | | \$1context.error.message | Stringa contenente un messaggio di errore di API Gateway. Questa variabile può essere utilizzata solo per la semplice sostituzione di variabili in un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)body mapping, che non viene elaborato dal motore Velocity Template Language, e nella registrazione degli accessi. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.messageString | Valore \$1context.error.message tra virgolette, ovvero "\$1context.error.message". | | \$1context.error.responseType | [Un tipo di. [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) Questa variabile può essere utilizzata solo per la semplice sostituzione di variabili in un modello di [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)body mapping, che non viene elaborato dal motore Velocity Template Language, e nella registrazione degli accessi. Per ulteriori informazioni, consultare [Monitora l'esecuzione delle WebSocket API con CloudWatch metriche](apigateway-websocket-api-logging.md) e [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](api-gateway-gatewayResponse-definition.md#customize-gateway-responses). | | \$1context.error.validationErrorString | Stringa contenente un messaggio dettagliato di errore di convalida. | | \$1context.extendedRequestId | ID esteso generato da API Gateway e assegnato alla richiesta API. L’ID della richiesta esteso contiene ulteriori informazioni utili per il debug e la risoluzione dei problemi. | | \$1context.httpMethod | Metodo HTTP usato. I valori validi sono: `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST` e `PUT`. | | \$1context.identity.accountId | L'ID dell'account associato alla richiesta. AWS | | \$1context.identity.apiKey | Per i metodi API che richiedono una chiave API, questa variabile è la chiave API associata alla richiesta del metodo. Per i metodi che non richiedono una chiave API, questa variabile è null. Per ulteriori informazioni, consulta [Piani di utilizzo e chiavi API per REST APIs in API Gateway](api-gateway-api-usage-plans.md). | | \$1context.identity.apiKeyId | ID chiave API associato a una richiesta API che richiede una chiave API. | | \$1context.identity.caller | Identificatore dell'entità principale dell'intermediario che ha firmato la richiesta. Supportato per risorse che utilizzano l'autorizzazione IAM. | | \$1context.identity.cognitoAuthenticationProvider | Un elenco separato da virgole con tutti i provider di autenticazione Amazon Cognito utilizzati dal chiamante che effettua la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. Ad esempio, per un'identità di un pool di utenti Amazon Cognito, `cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim` Per informazioni sui provider di autenticazione Amazon Cognito disponibili, consulta [Using Federated Identities](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-identity.html) nella *Guida per gli sviluppatori di Amazon Cognito*. | | \$1context.identity.cognitoAuthenticationType | Tipo di autenticazione Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. I valori possibili includono `authenticated` per le identità autenticate e `unauthenticated` per le identità non autenticate. | | \$1context.identity.cognitoIdentityId | ID identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. | | \$1context.identity.cognitoIdentityPoolId | ID pool di identità di Amazon Cognito dell'intermediario da cui proviene la richiesta. Disponibile solo se la richiesta è stata firmata con credenziali Amazon Cognito. | | \$1context.identity.principalOrgId | L'[ID organizzazione AWS](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_org_details.html). | | \$1context.identity.sourceIp | L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta all'endpoint di Gateway API. | | \$1context.identity.clientCert.clientCertPem | Certificato client codificato PEM che il client ha presentato durante l'autenticazione TLS reciproca. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.subjectDN | Nome distinto dell'oggetto del certificato presentato da un client. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.issuerDN | Nome distinto dell'approvatore del certificato presentato da un cliente. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.serialNumber | Il numero di serie del certificato. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.validity.notBefore | La data prima della quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.clientCert.validity.notAfter | La data dopo la quale il certificato non è valido. Presente quando un client accede a un'API utilizzando un nome di dominio personalizzato che ha attivato l'autenticazione TLS reciproca. Presente solo nei log di accesso se l'autenticazione TLS reciproca non riesce. | | \$1context.identity.vpcId | L'ID VPC del VPC da cui proviene la richiesta all'endpoint Gateway API. | | \$1context.identity.vpceId | L'ID endpoint VPC dell'endpoint VPC da cui proviene la richiesta all'endpoint Gateway API. Presente solo quando si dispone di un'API privata. | | \$1context.identity.user | Identificatore dell'entità principale dell'utente che sarà autorizzato per l'accesso alle risorse. Supportato per risorse che utilizzano l'autorizzazione IAM. | | \$1context.identity.userAgent | Intestazione [https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) del chiamante API. | | \$1context.identity.userArn | Amazon Resource Name (ARN) dell'utente valido identificato dopo l'autenticazione. Per ulteriori informazioni, consulta [https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html). | | \$1context.isCanaryRequest | Restituisce `true` se la richiesta era indirizzata al canary e `false` se la richiesta non era indirizzata al canary. Presente solo quando è abilitato un canary. | | \$1context.path | Percorso della richiesta. Ad esempio, per un URL di richiesta non proxy https://\$1rest-api-id\$1.execute-api.\$1region\$1.amazonaws.com/\$1stage\$1/root/child, il valore di \$1context.path è /\$1stage\$1/root/child. | | \$1context.protocol | Protocollo della richiesta, ad esempi, HTTP/1.1. API Gateway APIs può accettare richieste HTTP/2, ma API Gateway invia richieste alle integrazioni di backend utilizzando HTTP/1.1. Di conseguenza, il protocollo di richiesta viene registrato come HTTP/1.1 anche se un client invia una richiesta che utilizza HTTP/2. | | \$1context.requestId | L'ID della richiesta. I client possono sovrascrivere questo ID di richiesta. Utilizza `$context.extendedRequestId` per un ID di richiesta univoco generato da API Gateway. | | \$1context.requestOverride.header.header\$1name | Sovrascrittura intestazione della richiesta. Se definito, questo parametro contiene le intestazioni da utilizzare al posto delle **intestazioni HTTP** che sono definite nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.path.path\$1name | Sovrascrittura percorso della richiesta. Se definito, questo parametro contiene il percorso della richiesta da utilizzare al posto dei **parametri di percorso URL** che sono definiti nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestOverride.querystring.querystring\$1name | Sovrascrittura stringa di query della richiesta. Se definito, questo parametro contiene la stringa di query della richiesta da utilizzare al posto dei **URL Query String Parameters (Parametri stringa di query URL)** che sono definiti nel riquadro **Integration Request (Richiesta di integrazione)**. Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.header.header\$1name | Sovrascrittura intestazione della risposta. Se definito, questo parametro contiene l'intestazione da restituire al posto della Response header (Intestazione di risposta) che è definita come la Default mapping (mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.responseOverride.status | Sovrascrittura codice di stato della risposta. Se definito, questo parametro contiene il codice di stato da restituire al posto di Method response status (Stato risposta metodo) che è definito come la Default mapping (Mappatura predefinita) nel riquadro Integration Response (Risposta integrazione). Per ulteriori informazioni, consulta [Sostituisci i parametri di richiesta e risposta e i codici di stato dell'API per REST APIs in API Gateway](apigateway-override-request-response-parameters.md). | | \$1context.requestTime | Ora della richiesta in formato [CLF](https://httpd.apache.org/docs/current/logs.html#common) (dd/MMM/yyyy:HH:mm:ss \$1-hhmm). | | \$1context.requestTimeEpoch | L'ora della richiesta in formato [epoca (Unix epoch)](https://en.wikipedia.org/wiki/Unix_time) in millisecondi. | | \$1context.resourceId | Identificatore assegnato da API Gateway alla risorsa. | | \$1context.resourcePath | Percorso della risorsa. Ad esempio, per l'URI della richiesta non proxy di `https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child`, il valore di `$context.resourcePath` è `/root/child`. Per ulteriori informazioni, consulta [Tutorial: creazione di una REST API con un'integrazione non proxy HTTP](api-gateway-create-api-step-by-step.md). | | \$1context.stage | La fase di distribuzione della richiesta API (ad esempio `Beta` o `Prod`). | | \$1context.wafResponseCode | La risposta ricevuta da [AWS WAF](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html): `WAF_ALLOW` o `WAF_BLOCK`. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). | | \$1context.webaclArn | ARN completo della lista di controllo accessi Web usata per stabilire se consentire o bloccare la richiesta. Non verrà impostata se la fase non è associata a un ACL Web. Per ulteriori informazioni, consulta [Utilizzalo AWS WAF per proteggere il tuo REST APIs in API Gateway](apigateway-control-access-aws-waf.md). | ## Variabili input È possibile utilizzare le seguenti variabili `$input` con distinzione tra maiuscole e minuscole per fare riferimento ai parametri e al payload della richiesta di metodo. Sono disponibili le funzioni seguenti: | Variabile e funzione | Descrizione | | --- | --- | | \$1input.body | Restituisce il payload della richiesta non elaborata come stringa. È possibile utilizzare `$input.body` per conservare interi numeri in virgola mobile, ad esempio `10.00`. | | \$1input.json(x) | Questa funzione valuta un' JSONPath espressione e restituisce i risultati come stringa JSON. Ad esempio, `$input.json('$.pets')` restituisce una stringa JSON che rappresenta la struttura `pets`. Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for](https://github.com/json-path/JsonPath) Java. | | \$1input.params() | Restituisce una mappa di tutti i parametri della richiesta. Si consiglia di utilizzare `$util.escapeJavaScript` per sanificare il risultato ed evitare un potenziale attacco di iniezione. Per il pieno controllo della sanificazione delle richieste, utilizzare un'integrazione proxy senza un modello e gestire la sanificazione delle richieste nell'integrazione. | | \$1input.params(x) | Restituisce il valore di un parametro della richiesta del metodo dal percorso, dalla stringa di query o dal valore dell'intestazione (cercati in questo ordine) a partire da una stringa del nome del parametro `x`. Si consiglia di utilizzare `$util.escapeJavaScript` per sanificare il parametro ed evitare un potenziale attacco di iniezione. Per il controllo completo della sanificazione dei parametri, utilizzare un'integrazione proxy senza un modello e gestire la sanificazione delle richieste nell'integrazione. | | \$1input.path(x) | Accetta una stringa di JSONPath espressione (`x`) e restituisce una rappresentazione in oggetto JSON del risultato. In questo modo, puoi accedere agli elementi del payload e modificarli in modo nativo in [Apache Velocity Template Language (VTL)](https://velocity.apache.org/engine/devel/vtl-reference.html). Ad esempio, se l'espressione `$input.path('$.pets')` restituisce un oggetto in questo modo: 
[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]
`$input.path('$.pets').size()` restituisce `"3"`. Per ulteriori informazioni su JSONPath, vedere [JSONPath](https://goessner.net/articles/JsonPath/)or [JSONPath for Java](https://github.com/json-path/JsonPath). | ## Variabili di fase È possibile utilizzare le seguenti variabili di fase come segnaposto per ARNs e URLs nelle integrazioni di metodi. Per ulteriori informazioni, consulta [Utilizzo delle variabili di fase per una REST API in Gateway API](stage-variables.md). | Sintassi | Description | | --- | --- | | \$1stageVariables.variable\$1name, \$1stageVariables['variable\$1name'] o \$1\$1stageVariables['variable\$1name']\$1 | *variable\$1name*rappresenta il nome di una variabile di fase. | ## Variabili util È possibile utilizzare le seguenti variabili `$util` con distinzione tra maiuscole e minuscole per usare le funzioni di utilità per i modelli di mappatura. Se non diversamente specificato, il set di caratteri predefinito è UTF-8. | Funzione | Description | | --- | --- | | \$1util.escapeJavaScript() | Sfugge ai caratteri di una stringa utilizzando le regole delle JavaScript stringhe. Questa funzione trasforma qualsiasi virgoletta singola (`'`) in virgoletta preceduta da un carattere escape (`\'`). Tuttavia, le virgolette singole con escape non sono valide in JSON. Di conseguenza, quando l'output di questa funzione viene usato in una proprietà JSON, devi modificare di nuovo qualsiasi virgoletta singola con carattere escape (`\'`) in virgoletta singola normale (`'`). Questo viene mostrato nell'esempio seguente: 
 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
| | \$1util.parseJson() | Da una stringa JSON restituisce una rappresentazione oggetto del risultato. Puoi usare il risultato di questa funzione per accedere agli elementi del payload e modificarli in modo nativo in Apache Velocity Template Language (VTL). Ad esempio, in presenza del payload seguente: 
{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}
E se usi il modello di mappatura seguente: 
#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}
Otterrai l'output seguente: 
{
   "errorMessageObjKey2ArrVal" : 1
}
| | \$1util.urlEncode() | Converte una stringa nel formato «application/x-www-form-urlencoded». | | \$1util.urlDecode() | Decodifica una stringa «application/». x-www-form-urlencoded | | \$1util.base64Encode() | Codifica i dati in una stringa con codifica base64. | | \$1util.base64Decode() | Decodifica i dati da una stringa con codifica base64. | # Risposte gateway per REST APIs in API Gateway Una risposta del gateway è identificata da un tipo di risposta definito da API Gateway. La risposta consiste in un codice di stato HTTP, un insieme di intestazioni aggiuntive specificate dalle mappature dei parametri e un payload generato da un modello di mappatura non [VTL](https://velocity.apache.org/engine/devel/vtl-reference.html). Nell'API REST di API Gateway, una risposta del gateway è rappresentata da [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html). In OpenAPI, un'`GatewayResponse`istanza è descritta dall'estensione [x-amazon-apigateway-gateway-Response.gatewayResponse](api-gateway-swagger-extensions-gateway-responses.gatewayResponse.md). Per abilitare una risposta del gateway, dei impostare una risposta del gateway per un [tipo di risposta supportato](supported-gateway-response-types.md) a livello di API. Ogni volta che API Gateway restituisce una risposta di questo tipo, vengono applicate le mappature delle intestazioni e i modelli di mappatura del payload definiti nel gateway per restituire i risultati mappati all'intermediario dell'API. Nella sezione seguente viene illustrato come impostare le risposte del gateway tramite la console API Gateway e l'API REST API Gateway. ## Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori Se API Gateway non riesce a elaborare una richiesta in entrata, restituisce al client una risposta di errore senza inoltrare la richiesta al back-end di integrazione. Per impostazione predefinita, la risposta di errore contiene un breve messaggio di errore descrittivo. Ad esempio, se tenti di chiamare un'operazione da una risorsa API non definita, riceverai una risposta di errore con il messaggio `{ "message": "Missing Authentication Token" }`. Se sei nuovo su API Gateway, potrebbe essere difficile capire che cosa esattamente non sia andato a buon fine. Per alcune delle risposte di errore, API Gateway consente agli sviluppatori API di personalizzare le risposte in formati differenti. Per l'esempio `Missing Authentication Token`, puoi aggiungere un suggerimento al payload originale della risposta con la possibile causa, come in questo esempio: `{"message":"Missing Authentication Token", "hint":"The HTTP method or resources may not be supported."}`. Quando l'API fa da intermediario tra uno scambio esterno e il AWS Cloud, utilizzi modelli di mappatura VTL per la richiesta di integrazione o la risposta di integrazione per mappare il payload da un formato all'altro. Tuttavia, i modelli di mappatura VTL funzionano solo per le richieste valide con risposte andate a buon fine. Per le richieste non valide, API Gateway ignora completamente l'integrazione e restituisce una risposta di errore. Devi utilizzare la personalizzazione per rendere le risposte di errore in un formato conforme allo scambio. Qui, la personalizzazione viene realizzata in un modello di mappatura non-VTL che supporta solo le sostituzioni semplici delle variabili. Per generalizzare la risposta di errore generata da API Gateway e qualsiasi risposta generata da API Gateway, usiamo il termine *risposte del gateway*. In questo modo facciamo distinzione tra le risposte generate da API Gateway e le risposte di integrazione. Un modello di mappatura di una risposta del gateway può accedere ai valori della variabile `$context` e ai valori della proprietà `$stageVariables`, nonché ai parametri della richiesta di metodo, sotto forma di `method.request.param-position.param-name`. Per ulteriori informazioni sulle variabili `$context`, consulta [Variabili di contesto per le trasformazioni dei dati](api-gateway-mapping-template-reference.md#context-variable-reference). Per ulteriori informazioni su `$stageVariables`, consulta [Variabili di fase](api-gateway-mapping-template-reference.md#stagevariables-template-reference). Per ulteriori informazioni sui parametri di richiesta del metodo, consulta [Variabili input](api-gateway-mapping-template-reference.md#input-variable-reference). **Topics** + [Configurazione delle risposte del gateway per la personalizzazione delle risposte agli errori](#customize-gateway-responses) + [Impostare una risposta del gateway per un'API REST utilizzando la console API Gateway](set-up-gateway-response-using-the-console.md) + [Configurazione di una risposta del gateway mediante l'API REST API Gateway](set-up-gateway-response-using-the-api.md) + [Configurazione della personalizzazione di una risposta del gateway in OpenAPI](set-up-gateway-responses-in-swagger.md) + [Tipi di risposta del gateway in Gateway API](supported-gateway-response-types.md) # Impostare una risposta del gateway per un'API REST utilizzando la console API Gateway Il seguente esempio mostra come impostare una risposta del gateway per una REST API utilizzando la console Gateway API. **Per configurare una risposta del gateway mediante la console API Gateway** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere una REST API. 1. Nel riquadro di navigazione principale di Gateway API, scegli **Risposte di Gateway**. 1. Scegli un tipo di risposta, quindi scegli **Modifica**. In questa procedura guidata, utilizziamo **Token di autenticazione mancante** come esempio. 1. Ora puoi cambiare il valore dell'opzione **Codice di stato** generato da Gateway API per restituire un codice di stato diverso che soddisfi i requisiti dell'API. In questo esempio, la personalizzazione cambia il codice di stato da quello predefinito (`403`) al codice `404`, poiché questo messaggio di errore viene ricevuto quando un client chiama una risorsa non valida o non supportata che può essere considerata come non trovata. 1. Per tornare alle intestazioni personalizzate, seleziona **Aggiungi intestazione della risposta** in **Intestazioni di risposta**. A scopo illustrativo, aggiungiamo le seguenti intestazioni personalizzate: ``` Access-Control-Allow-Origin:'a.b.c' x-request-id:method.request.header.x-amzn-RequestId x-request-path:method.request.path.petId x-request-query:method.request.querystring.q ``` Nelle precedenti mappature delle intestazioni, viene mappato un nome di dominio statico (`'a.b.c'`) all'intestazione `Allow-Control-Allow-Origin` per consentire a CORS di accedere all'API; l'intestazione della richiesta di input di `x-amzn-RequestId` viene mappata a `request-id` nella risposta; la variabile di percorso `petId` della richiesta in entrata viene mappata all'intestazione `request-path` nella risposta, mentre il parametro di query `q` della richiesta originale viene mappato all'intestazione `request-query` della risposta. 1. In **Modelli di risposta**, non modificare `application/json` in **Tipo di contenuto** e immetti il seguente modello di mappatura del corpo nell'editor **Corpo modello**: ``` { "message":"$context.error.messageString", "type": "$context.error.responseType", "statusCode": "'404'", "stage": "$context.stage", "resourcePath": "$context.resourcePath", "stageVariables.a": "$stageVariables.a" } ``` Questo modello mostra come mappare le proprietà `$context` e `$stageVariables` alle proprietà del corpo di risposta del gateway. 1. Scegli **Save changes** (Salva modifiche). 1. Distribuzione dell'API in una fase nuova o esistente. Esegui un test della risposta del gateway chiamando il seguente comando CURL, supponendo che l'URL di richiamo del metodo API corrispondente sia `https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/{petId}`: ``` curl -v -H 'x-amzn-RequestId:123344566' https://o81lxisefl.execute-api.us-east-1.amazonaws.com/custErr/pets/5/type?q=1 ``` Considerato che il parametro aggiuntivo della stringa di query `q=1` non è compatibile con l'API, viene restituito un errore dalla risposta del gateway specificata. Dovresti visualizzare una risposta del gateway simile alla seguente: ``` > GET /custErr/pets/5?q=1 HTTP/1.1 Host: o81lxisefl.execute-api.us-east-1.amazonaws.com User-Agent: curl/7.51.0 Accept: */* HTTP/1.1 404 Not Found Content-Type: application/json Content-Length: 334 Connection: keep-alive Date: Tue, 02 May 2017 03:15:47 GMT x-amzn-RequestId: 123344566 Access-Control-Allow-Origin: a.b.c x-amzn-ErrorType: MissingAuthenticationTokenException header-1: static x-request-query: 1 x-request-path: 5 X-Cache: Error from cloudfront Via: 1.1 441811a054e8d055b893175754efd0c3.cloudfront.net (CloudFront) X-Amz-Cf-Id: nNDR-fX4csbRoAgtQJ16u0rTDz9FZWT-Mk93KgoxnfzDlTUh3flmzA== { "message":"Missing Authentication Token", "type": MISSING_AUTHENTICATION_TOKEN, "statusCode": '404', "stage": custErr, "resourcePath": /pets/{petId}, "stageVariables.a": a } ``` Il precedente esempio presuppone che il back-end dell'API sia [Pet Store](http://petstore-demo-endpoint.execute-api.com/petstore/pets) e l'API abbia una variabile di fase, `a`, definita. # Configurazione di una risposta del gateway mediante l'API REST API Gateway Prima di personalizzare una risposta del gateway tramite l'API REST API Gateway, devi aver già creato un'API e aver ottenuto il relativo identificatore. Per recuperare l'identificatore dell'API puoi seguire la relazione di collegamento [restapi:gateway-responses](https://docs.aws.amazon.com/apigateway/latest/api/API_GetGatewayResponses.html) ed esaminare il risultato. **Per configurare una risposta del gateway mediante l'API REST API Gateway** 1. Per sovrascrivere un'intera [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)istanza, chiama il [gatewayresponse:put](https://docs.aws.amazon.com/apigateway/latest/api/API_PutGatewayResponse.html) action. Specificare un valore desiderato per [responseType](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseType) nel parametro di percorso URL e fornire nel payload della richiesta le mappature [statusCode](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#statusCode), [responseParameters](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseParameters) e [responseTemplates](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html#responseTemplates). 1. Per aggiornare parte di un'istanza `GatewayResponse`, chiamare l'operazione [gatewayresponse:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateGatewayResponse.html). Specificare un valore desiderato per `responseType` nel parametro di percorso URL e fornire nel payload della richiesta le singole proprietà `GatewayResponse` desiderate, ad esempio la mappatura `responseParameters` o `responseTemplates`. # Configurazione della personalizzazione di una risposta del gateway in OpenAPI Puoi usare l'estensione `x-amazon-apigateway-gateway-responses` a livello di radice dell'API per personalizzare le risposte del gateway in OpenAPI. La seguente definizione di OpenAPI mostra un esempio per personalizzare il [GatewayResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_GatewayResponse.html)tipo. `MISSING_AUTHENTICATION_TOKEN` ``` "x-amazon-apigateway-gateway-responses": { "MISSING_AUTHENTICATION_TOKEN": { "statusCode": 404, "responseParameters": { "gatewayresponse.header.x-request-path": "method.input.params.petId", "gatewayresponse.header.x-request-query": "method.input.params.q", "gatewayresponse.header.Access-Control-Allow-Origin": "'a.b.c'", "gatewayresponse.header.x-request-header": "method.input.params.Accept" }, "responseTemplates": { "application/json": "{\n \"message\": $context.error.messageString,\n \"type\": \"$context.error.responseType\",\n \"stage\": \"$context.stage\",\n \"resourcePath\": \"$context.resourcePath\",\n \"stageVariables.a\": \"$stageVariables.a\",\n \"statusCode\": \"'404'\"\n}" } } ``` In questo esempio, la personalizzazione cambia il codice di stato dal predefinito (`403`) a `404`. Aggiunge anche alla risposta del gateway quattro parametri di intestazione e un modello di mappatura del corpo per il tipo di supporto `application/json`. # Tipi di risposta del gateway in Gateway API API Gateway espone le seguenti risposte del gateway alla personalizzazione da parte degli sviluppatori di API. | Tipo di risposta del gateway | Codice di stato predefinito | Descrizione | | --- | --- | --- | | ACCESS\$1DENIED | 403 | Risposta del gateway per un'autorizzazione non riuscita, ad esempio quando l'accesso viene negato da un'autorizzazione ad hoc o di Amazon Cognito. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | API\$1CONFIGURATION\$1ERROR | 500 | La risposta del gateway per configurazioni API non valide, incluso l'invio dell'indirizzo dell'endpoint errato, la codifica base64 non riuscita sui dati binari quando il supporto binario è abilitato o la mappatura della risposta di integrazione non corrispondente a nessun modello e nessuna configurazione di un modello predefinito. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_5XX`. | | AUTHORIZER\$1CONFIGURATION\$1ERROR | 500 | Risposta del gateway per la mancata connessione ad autorizzazioni ad hoc o di Amazon Cognito. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_5XX`. | | AUTHORIZER\$1FAILURE | 500 | Risposta del gateway quando autorizzazioni ad hoc o di Amazon Cognito non riescono ad autenticare l'intermediario. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_5XX`. | | BAD\$1REQUEST\$1PARAMETERS | 400 | Riposta del gateway quando il parametro di richiesta non può essere convalidato in base a un validatore abilitato delle richieste. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | BAD\$1REQUEST\$1BODY | 400 | Riposta del gateway quando il corpo della richiesta non può essere convalidato in base a un validatore abilitato delle richieste. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | DEFAULT\$14XX | Null | La risposta predefinita del gateway per un tipo di risposta non specificato con codice di stato `4XX`. Cambiando il codice di stato di questa risposta di fallback del gateway significa cambiare i codici di stato di tutte le altre risposte `4XX` al nuovo valore. Reimpostando il codice di stato su null, i codici di stato di tutte le altre risposte `4XX` ritornano ai loro valori originali. [AWS WAF le risposte personalizzate](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) hanno la precedenza sulle risposte gateway personalizzate. | | DEFAULT\$15XX | Null | La risposta predefinita del gateway per un tipo di risposta non specificato con codice di stato `5XX`. Cambiando il codice di stato di questa risposta di fallback del gateway significa cambiare i codici di stato di tutte le altre risposte `5XX` al nuovo valore. Reimpostando il codice di stato su null, i codici di stato di tutte le altre risposte `5XX` ritornano ai loro valori originali. | | EXPIRED\$1TOKEN | 403 | La risposta del gateway per un errore del token AWS di autenticazione è scaduta. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | INTEGRATION\$1FAILURE | 504 | Risposta del gateway per un errore di integrazione non riuscita. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_5XX`. | | INTEGRATION\$1TIMEOUT | 504 | Risposta del gateway per un errore di integrazione scaduta. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_5XX`. | | INVALID\$1API\$1KEY | 403 | Risposta del gateway per una chiave API non valida inviata per un metodo che la richiedeva. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | INVALID\$1SIGNATURE | 403 | La risposta del gateway per un errore di AWS firma non valido. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | MISSING\$1AUTHENTICATION\$1TOKEN | 403 | Risposta del gateway per un errore di token autenticazione mancante, inclusi i casi in cui il cliente tenta di chiamare un metodo o una risorsa API non supportati. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | QUOTA\$1EXCEEDED | 429 | Risposta del gateway per un errore di superamento della quota di utilizzo del piano. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | REQUEST\$1TOO\$1LARGE | 413 | Risposta del gateway per un errore di dimensioni eccessive della richiesta. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito su `HTTP content length exceeded 10485760 bytes`. | | RESOURCE\$1NOT\$1FOUND | 404 | Risposta del gateway quando API Gateway non riesce a trovare l risorsa specificata dopo che una richiesta API passa autenticazione e autorizzazione, ad eccezione dell'autenticazione e dell'autorizzazione della chiave API. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | THROTTLED | 429 | Risposta del gateway quando vengono superati i limiti di throttling a livello di account, fase, metodo o piano. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | UNAUTHORIZED | 401 | Risposta del gateway quando l'autorizzazione ad hoc o di Amazon Cognito non riesce ad autenticare l'intermediario. | | UNSUPPORTED\$1MEDIA\$1TYPE | 415 | Risposta del gateway quando il payload presenta un tipo di supporto non supportato, se è stato abilitato un comportamento passthrough severo. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. | | WAF\$1FILTERED | 403 | La risposta del gateway quando una richiesta è bloccato da AWS WAF. Se il tipo di risposta non è specificato, la risposta viene impostata in modo predefinito sul tipo `DEFAULT_4XX`. [AWS WAF le risposte personalizzate](https://docs.aws.amazon.com/waf/latest/developerguide/waf-custom-request-response.html) hanno la precedenza sulle risposte gateway personalizzate. | # CORS per REST APIs in API Gateway [CORS (Cross-origin resource sharing)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) è una caratteristica di sicurezza del browser che limita le richieste HTTP multiorigine avviate da script in esecuzione nel browser. Per ulteriori informazioni, consulta [Che cos'è CORS?](https://aws.amazon.com/what-is/cross-origin-resource-sharing/) ## Determinazione della necessità di abilitare il supporto di CORS Una richiesta HTTP *multiorigine* è una richiesta effettuata a: + Un *dominio* diverso (ad esempio da `example.com` a `amazondomains.com`) + Un *sottodominio* diverso (ad esempio da `example.com` a `petstore.example.com`) + Una *porta* diversa (ad esempio da `example.com` a `example.com:10777`) + Un *protocollo* diverso (ad esempio da `https://example.com` a `http://example.com`) Se non riesci ad accedere all'API e ricevi un messaggio di errore che contiene `Cross-Origin Request Blocked`, potresti dover abilitare CORS. Le richieste HTTP multiorigine possono essere di due tipi: richieste *semplici* e richieste *non semplici*. ## Abilitazione di CORS per una richiesta semplice Una richiesta HTTP è *semplice* se si verificano tutte le condizioni seguenti: + Viene inviata a una risorsa API che permette solo richieste `GET`, `HEAD` e `POST`. + Se si tratta di una richiesta di metodo `POST`, deve includere un'intestazione `Origin`. + Il tipo di contenuto del payload della richiesta è `text/plain`, `multipart/form-data` o `application/x-www-form-urlencoded`. + La richiesta non contiene intestazioni personalizzate. + Eventuali requisiti aggiuntivi elencati nella [documentazione di Mozilla CORS per le richieste semplici](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#Simple_requests). Per richieste di metodo `POST` multiorigine semplici, la risposta della risorsa deve includere l'intestazione `Access-Control-Allow-Origin: '*'` o `Access-Control-Allow-Origin:'origin'`. Tutte le altre richieste HTTP multiorigine sono richieste *non semplici*. ## Abilitazione di CORS per una richiesta non semplice Se le risorse dell'API ricevono richieste non semplici, è necessario abilitare il supporto CORS aggiuntivo a seconda del tipo di integrazione. ### Abilitazione di CORS per integrazioni non proxy Per questo tipo di integrazioni, il [protocollo CORS](https://fetch.spec.whatwg.org/#http-cors-protocol) richiede al browser di inviare una richiesta preliminare al server e di attendere l'approvazione (o una richiesta di credenziali) del server prima di inviare la richiesta effettiva. È necessario configurare l'API per inviare una risposta appropriata alla richiesta di verifica preliminare. Creazione di una risposta di verifica preliminare 1. Creare un metodo `OPTIONS` per l'integrazione fittizia. 1. Aggiungere le seguenti intestazioni di risposta alla risposta del metodo 200: + `Access-Control-Allow-Headers` + `Access-Control-Allow-Methods` + `Access-Control-Allow-Origin` 1. Impostare il comportamento passthrough di integrazione su `NEVER`. In questo caso, la richiesta di metodo di un tipo di contenuto non mappato sarà rifiutata con la risposta Tipo di supporto non compatibile HTTP 415. Per ulteriori informazioni, consulta [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md). 1. Immettere i valori per le intestazioni delle risposte. Per consentire tutte le origini, tutti i metodi e le intestazioni comuni, usare i seguenti valori di intestazione: + `Access-Control-Allow-Headers: 'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` + `Access-Control-Allow-Methods: 'DELETE,GET,HEAD,OPTIONS,PUT,POST,PATCH'` + `Access-Control-Allow-Origin: '*'` Dopo aver creato la richiesta di verifica preliminare, è necessario restituire l'intestazione `Access-Control-Allow-Origin: '*'` o `Access-Control-Allow-Origin:'origin'` per tutti i metodi abilitati per CORS per almeno tutte le 200 risposte. ### Abilitazione di CORS per integrazioni non proxy utilizzando il Console di gestione AWS È possibile utilizzare il per abilitare CORS Console di gestione AWS . Gateway Amazon API crea un metodo `OPTIONS` e aggiunge l'intestazione `Access-Control-Allow-Origin` alle risposte di integrazione del metodo esistente. Questo non sempre funziona e talvolta è necessario modificare manualmente la risposta di integrazione per restituire l'intestazione `Access-Control-Allow-Origin` di tutti i metodi abilitati per CORS per almeno tutte le 200 risposte. Se i tipi di supporti binari sono impostati su `*/*` per l’API, quando Gateway API crea un metodo `OPTIONS`, modificare `contentHandling` in `CONVERT_TO_TEXT`. Il comando [update-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration.html) seguente modifica `contentHandling` in `CONVERT_TO_TEXT` per una richiesta di integrazione: ``` aws apigateway update-integration \ --rest-api-id abc123 \ --resource-id aaa111 \ --http-method OPTIONS \ --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' ``` Il [update-integration-response](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-integration-response.html)comando seguente modifica il formato `contentHandling` `CONVERT_TO_TEXT` per una risposta di integrazione: ``` aws apigateway update-integration-response \ --rest-api-id abc123 \ --resource-id aaa111 \ --http-method OPTIONS \ --status-code 200 \ --patch-operations op='replace',path='/contentHandling',value='CONVERT_TO_TEXT' ``` ## Abilitazione del supporto di CORS per le integrazioni proxy Per un'integrazione proxy Lambda o un'integrazione con proxy HTTP, il back-end è responsabile della restituzione delle intestazioni `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods` e `Access-Control-Allow-Headers` , perché un'integrazione proxy non restituisce una risposta di integrazione. Le seguenti funzioni Lambda di esempio restituiscono le intestazioni CORS richieste: ------ #### [ Node.js ] ``` export const handler = async (event) => { const response = { statusCode: 200, headers: { "Access-Control-Allow-Headers" : "Content-Type", "Access-Control-Allow-Origin": "https://www.example.com", "Access-Control-Allow-Methods": "OPTIONS,POST,GET" }, body: JSON.stringify('Hello from Lambda!'), }; return response; }; ``` ------ #### [ Python 3 ] ``` import json def lambda_handler(event, context): return { 'statusCode': 200, 'headers': { 'Access-Control-Allow-Headers': 'Content-Type', 'Access-Control-Allow-Origin': 'https://www.example.com', 'Access-Control-Allow-Methods': 'OPTIONS,POST,GET' }, 'body': json.dumps('Hello from Lambda!') } ``` ------ **Topics** + [Determinazione della necessità di abilitare il supporto di CORS](#apigateway-cors-request-types) + [Abilitazione di CORS per una richiesta semplice](#apigateway-cors-simple-request) + [Abilitazione di CORS per una richiesta non semplice](#apigateway-enable-cors-non-simple) + [Abilitazione del supporto di CORS per le integrazioni proxy](#apigateway-enable-cors-proxy) + [Abilitazione CORS su una risorsa tramite la console API Gateway](how-to-cors-console.md) + [Abilitazione di CORS per una risorsa tramite l'API di importazione di API Gateway](enable-cors-for-resource-using-swagger-importer-tool.md) + [Test di CORS per un'API di Gateway API](apigateway-test-cors.md) # Abilitazione CORS su una risorsa tramite la console API Gateway È possibile utilizzare la console API Gateway per abilitare il supporto di CORS per uno o per tutti i metodi in una risorsa API REST creata. Dopo aver abilitato il supporto CORS, impostare il comportamento passthrough di integrazione su `NEVER`. In questo caso, la richiesta di metodo di un tipo di contenuto non mappato sarà rifiutata con la risposta Tipo di supporto non compatibile HTTP 415. Per ulteriori informazioni, consulta [Comportamento della richiesta del metodo per i payload senza modelli di mappatura per REST APIs in API Gateway](integration-passthrough-behaviors.md) **Importante** Le risorse possono contenere risorse figlio. L'abilitazione del supporto di CORS per una risorsa e per i relativi metodi non comporta l'abilitazione ricorsiva per le risorse figlio e i relativi metodi. **Abilitazione del supporto di CORS in una risorsa REST API** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere un'API. 1. Scegliere una risorsa in **Resources (Risorse)**. 1. Nella sezione **Dettagli delle risorse**, scegli **Abilita CORS.** ![\[Nel riquadro Risorse scegli Abilita CORS.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors.png) 1. Nella casella **Abilita CORS** esegui quanto segue: 1. (Facoltativo) Se hai creato una risposta del gateway del cliente e desideri abilitare il supporto di CORS per una risposta, seleziona una risposta gateway. 1. Seleziona ciascun metodo per abilitare il supporto di CORS. Per il metodo `OPTION` è necessario abilitare il supporto di CORS. Se abiliti il supporto di CORS per un metodo `ANY`, CORS viene abilitato per tutti i metodi. 1. Nel campo di input **Access-Control-Allow-Headers**, immetti una stringa statica di un elenco di intestazioni separate da virgole che il client deve inviare nella richiesta della risorsa. Usa l'elenco di intestazioni `'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'` fornito dalla console o specifica intestazioni personalizzate. 1. Utilizza il valore `'*'` fornito dalla console come valore dell'intestazione **Access-Control-Allow-Origin** per consentire le richieste di accesso da tutte le origini oppure specifica le origini autorizzate ad accedere alla risorsa. 1. Scegli **Save** (Salva). ![\[Scelta delle intestazioni consentite\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/amazon-api-gateway-new-console-enable-cors-resources.png) **Importante** Quando si applicano le istruzioni sopra riportate al metodo `ANY` in un'integrazione proxy, non verrà impostata nessuna intestazione CORS applicabile. Il back-end deve invece restituire le intestazioni CORS applicabili, ad esempio `Access-Control-Allow-Origin`. Dopo l'abilitazione di CORS per il metodo `GET`, alla risorsa viene aggiunto un metodo `OPTIONS`, se non è già presente. La risposta `200` del metodo `OPTIONS` viene configurata automaticamente per restituire le tre intestazioni `Access-Control-Allow-*` per soddisfare gli handshake preliminari. Inoltre, il metodo effettivo (`GET`) è configurato per impostazione predefinita per restituire l'intestazione `Access-Control-Allow-Origin` anche nella risposta 200. Gli altri tipi di risposta devono essere configurati manualmente in modo da restituire l'intestazione `Access-Control-Allow-Origin'` con '\$1' oppure origini specifiche, se non si vuole che venga restituito l'errore `Cross-origin access`. Dopo aver abilitato il supporto di CORS nella risorsa, è necessario distribuire o ridistribuire l'API per rendere effettive le nuove impostazioni. Per ulteriori informazioni, consulta [Crea distribuzione](set-up-deployments.md#create-deployment). **Nota** Se non è possibile abilitare il supporto CORS sulla risorsa con questa procedura, si consiglia di confrontare la configurazione CORS con la risorsa `/pets` dell'API di esempio. Per informazioni su come creare l'API di esempio, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). # Abilitazione di CORS per una risorsa tramite l'API di importazione di API Gateway Se utilizzi l'[API di importazione di API Gateway](api-gateway-import-api.md), puoi configurare il supporto di CORS utilizzando un file OpenAPI. È prima necessario definire un metodo `OPTIONS` nella risorsa che restituisce le intestazioni necessarie. **Nota** I browser Web prevedono che Access-Control-Allow-Headers le Access-Control-Allow-Origin intestazioni vengano configurate in ogni metodo API che accetta richieste CORS. Inoltre, alcuni browser inviano prima una richiesta HTTP a un metodo `OPTIONS` nella stessa risorsa e quindi aspettano di ricevere le stesse intestazioni. ## Metodo di esempio `Options` L'esempio seguente crea un metodo `OPTIONS` per un'integrazione fittizia. ------ #### [ OpenAPI 3.0 ] ``` /users: options: summary: CORS support description: | Enable CORS by returning correct headers tags: - CORS responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: {} x-amazon-apigateway-integration: type: mock requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods: "'*'" method.response.header.Access-Control-Allow-Origin: "'*'" ``` ------ #### [ OpenAPI 2.0 ] ``` /users: options: summary: CORS support description: | Enable CORS by returning correct headers consumes: - "application/json" produces: - "application/json" tags: - CORS x-amazon-apigateway-integration: type: mock requestTemplates: "{\"statusCode\": 200}" passthroughBehavior: "never" responses: "default": statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods : "'*'" method.response.header.Access-Control-Allow-Origin : "'*'" responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Headers: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Origin: type: "string" ``` ------ Una volta configurato il metodo `OPTIONS` per la risorsa, puoi aggiungere le intestazioni richieste agli altri metodi nella stessa risorsa che deve accettare le richieste CORS. 1. Dichiarare **Access-Control-Allow-Origin (Controllo accessi - Autorizza origine)** e **Headers (Intestazioni)** nei tipi di risposta. ------ #### [ OpenAPI 3.0 ] ``` responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: {} ``` ------ #### [ OpenAPI 2.0 ] ``` responses: 200: description: Default response for CORS method headers: Access-Control-Allow-Headers: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Origin: type: "string" ``` ------ 1. Nel tag `x-amazon-apigateway-integration` tag configura la mappatura per quelle intestazioni nei valori statici: ------ #### [ OpenAPI 3.0 ] ``` responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods: "'*'" method.response.header.Access-Control-Allow-Origin: "'*'" responseTemplates: application/json: | {} ``` ------ #### [ OpenAPI 2.0 ] ``` responses: "default": statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Headers : "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Methods : "'*'" method.response.header.Access-Control-Allow-Origin : "'*'" ``` ------ ## API di esempio L'esempio seguente crea un'API completa con un metodo `OPTIONS` e un metodo `GET` con un'integrazione `HTTP`. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "cors-api" description: "cors-api" version: "2024-01-16T18:36:01Z" servers: - url: "/{basePath}" variables: basePath: default: "/test" paths: /: get: operationId: "GetPet" responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: schema: type: "string" content: {} x-amazon-apigateway-integration: httpMethod: "GET" uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Origin: "'*'" passthroughBehavior: "never" type: "http" options: responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: schema: type: "string" Access-Control-Allow-Methods: schema: type: "string" Access-Control-Allow-Headers: schema: type: "string" content: application/json: schema: $ref: "#/components/schemas/Empty" x-amazon-apigateway-integration: responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'" method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Origin: "'*'" requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" type: "mock" components: schemas: Empty: type: "object" ``` ------ #### [ OpenAPI 2.0 ] ``` swagger: "2.0" info: description: "cors-api" version: "2024-01-16T18:36:01Z" title: "cors-api" basePath: "/test" schemes: - "https" paths: /: get: operationId: "GetPet" produces: - "application/json" responses: "200": description: "200 response" headers: Access-Control-Allow-Origin: type: "string" x-amazon-apigateway-integration: httpMethod: "GET" uri: "http://petstore.execute-api.us-east-1.amazonaws.com/petstore/pets" responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Origin: "'*'" passthroughBehavior: "never" type: "http" options: consumes: - "application/json" produces: - "application/json" responses: "200": description: "200 response" schema: $ref: "#/definitions/Empty" headers: Access-Control-Allow-Origin: type: "string" Access-Control-Allow-Methods: type: "string" Access-Control-Allow-Headers: type: "string" x-amazon-apigateway-integration: responses: default: statusCode: "200" responseParameters: method.response.header.Access-Control-Allow-Methods: "'GET,OPTIONS'" method.response.header.Access-Control-Allow-Headers: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key'" method.response.header.Access-Control-Allow-Origin: "'*'" requestTemplates: application/json: "{\"statusCode\": 200}" passthroughBehavior: "never" type: "mock" definitions: Empty: type: "object" ``` ------ # Test di CORS per un'API di Gateway API È possibile testare la configurazione CORS dell'API richiamando l'API e controllando le intestazioni CORS nella risposta. Il comando `curl` seguente invia una richiesta OPTIONS a un'API distribuita. ``` curl -v -X OPTIONS https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name} ``` ``` < HTTP/1.1 200 OK < Date: Tue, 19 May 2020 00:55:22 GMT < Content-Type: application/json < Content-Length: 0 < Connection: keep-alive < x-amzn-RequestId: a1b2c3d4-5678-90ab-cdef-abc123 < Access-Control-Allow-Origin: * < Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token < x-amz-apigw-id: Abcd= < Access-Control-Allow-Methods: DELETE,GET,HEAD,OPTIONS,PATCH,POST,PUT ``` Le intestazioni `Access-Control-Allow-Origin`, `Access-Control-Allow-Headers` e `Access-Control-Allow-Methods` nella risposta mostrano che l'API supporta CORS. Per ulteriori informazioni, consulta [CORS per REST APIs in API Gateway](how-to-cors.md). # Tipi di supporti binari per REST APIs in API Gateway In API Gateway, la richiesta e la risposta delle API possono avere un payload binario o di testo. Il payload di testo è una stringa JSON in codifica `UTF-8`, mentre un payload binario è rappresentato da tutto ciò che non è un payload di testo. Il payload binario può essere, ad esempio, un file JPEG, un GZip file o un file XML. La configurazione API necessaria per supportare i supporti binari dipende dal fatto che l'API utilizzi integrazioni proxy o non proxy. Se utilizzate un'integrazione proxy con lo streaming di risposta del payload, non è necessario configurare i tipi di file multimediali binari. Per ulteriori informazioni, consulta [Trasmetti in streaming la risposta di integrazione per le integrazioni proxy in API Gateway](response-transfer-mode.md). ## AWS Lambda integrazioni proxy Per gestire i payload binari per le integrazioni AWS Lambda proxy, è necessario codificare in base 64 la risposta della funzione. È inoltre necessario configurare la per la propria API. [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes) La configurazione `binaryMediaTypes` dell'API è un elenco di tipi di contenuti che l'API considera come dati binari. I tipi di supporti binari di esempio includono `image/png` o `application/octet-stream`. È possibile utilizzare il carattere jolly (`*`) per includere più tipi di file multimediali. API Gateway utilizza la prima intestazione `Accept` dai client per determinare se una risposta deve restituire supporti binari. Per restituire un supporto binario quando non è possibile controllare l’ordine dei valori delle intestazioni `Accept`, ad esempio le richieste da un browser, impostare i tipi di supporti binari dell’API su `*/*`. Per il codice di esempio, consulta [Restituzione di supporti binari da un'integrazione proxy Lambda in Gateway API](lambda-proxy-binary-media.md). Se utilizzi un'integrazione proxy Lambda con lo streaming di risposta del payload, non è necessario configurare i tipi di media binari. Per ulteriori informazioni, consulta [Configura l'integrazione di un proxy Lambda con lo streaming della risposta del payload in API Gateway](response-transfer-mode-lambda.md). ## Integrazioni non proxy Per gestire i payload binari per le integrazioni non proxy, aggiungi i tipi di media all'elenco della [binaryMediaTypes](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#apigw-Type-RestApi-binaryMediaTypes)risorsa. `RestApi` La configurazione `binaryMediaTypes` dell'API è un elenco di tipi di contenuti che l'API considera come dati binari. [In alternativa, puoi impostare le proprietà [ContentHandling](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html#contentHandling) sull'integrazione e sulle risorse. [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) Il valore `contentHandling` può essere `CONVERT_TO_BINARY`, `CONVERT_TO_TEXT` o non definito. **Nota** Per le integrazioni `MOCK` o private, l’impostazione delle proprietà `contentHandling` non è supportata nella Console di gestione AWS. È necessario utilizzare AWS CLI CloudFormation, o un SDK per impostare le proprietà. `contentHandling` A seconda del valore `contentHandling` e se l'intestazione `Content-Type` della risposta o l'intestazione `Accept` della richiesta in entrata corrisponde a una voce dell'elenco `binaryMediaTypes`, API Gateway può codificare i byte binari grezzi come stringa con codifica base64, decodificare una stringa con codifica base64 di nuovo in byte grezzi oppure passare il corpo senza alcuna modifica. Devi configurare l'API come segue per supportare i payload binari per l'API in API Gateway: + Aggiungete i tipi di file multimediali binari desiderati all'`binaryMediaTypes`elenco della [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa. Se questa proprietà e la proprietà `contentHandling` non sono definite, i payload vengono gestiti come stringhe JSON in codifica UTF-8. + Indirizzare la proprietà `contentHandling` della risorsa [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html). + Per convertire il payload della richiesta da una stringa con codifica base64 nel relativo BLOB binario, impostare la proprietà su `CONVERT_TO_BINARY`. + Per convertire il payload della richiesta da un BLOB binario a una stringa con codifica base64, impostare la proprietà su `CONVERT_TO_TEXT`. + Per passare il payload senza modifiche, lasciare la proprietà indefinita. Per passare un payload binario senza modifiche, è inoltre necessario assicurarsi che `Content-Type` corrisponda a una delle voci `binaryMediaTypes` e che per l'API siano abilitati i [comportamenti passthrough](integration-passthrough-behaviors.md). + Imposta la `contentHandling` proprietà della [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html)risorsa. La proprietà `contentHandling`, l'intestazione `Accept` nelle richieste del client e i tipi `binaryMediaTypes` combinati dell'API determinano il modo in cui API Gateway gestisce le conversioni dei tipi di contenuto. Per informazioni dettagliate, vedi [Conversioni dei tipi di contenuto in API Gateway](api-gateway-payload-encodings-workflow.md). **Importante** Quando una richiesta contiene più tipi di supporto nell'intestazione `Accept`, API Gateway mantiene la conformità solo con il primo tipo di supporto `Accept`. Se non è possibile controllare l'ordine dei tipi di supporto `Accept` e il tipo di supporto del contenuto binario non è il primo dell'elenco, aggiungere il primo tipo di supporto `Accept` nell'elenco `binaryMediaTypes` dell'API. API Gateway gestisce tutti i tipi di contenuto in questo elenco come binari. Ad esempio, per inviare un file JPEG utilizzando un elemento `` in un browser, il browser potrebbe inviare `Accept:image/webp,image/*,*/*;q=0.8` in una richiesta. Aggiungendo `image/webp` all'elenco `binaryMediaTypes`, l'endpoint riceve il file JPEG come binario. Per informazioni dettagliate su come API Gateway gestisce i payload di testo e binari, consulta [Conversioni dei tipi di contenuto in API Gateway](api-gateway-payload-encodings-workflow.md). # Conversioni dei tipi di contenuto in API Gateway La combinazione di `binaryMediaTypes` dell'API, le intestazioni nelle richieste del client e la proprietà `contentHandling` di integrazione determinano il modo in cui API Gateway codifica i payload. [La tabella seguente mostra come API Gateway converte il payload della richiesta per configurazioni specifiche dell'`Content-Type`intestazione di una richiesta, l'`binaryMediaTypes`elenco di una [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa e il valore della `contentHandling` proprietà della risorsa di integrazione.](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) | Payload della richiesta di metodo | Intestazione `Content-Type` della richiesta | `binaryMediaTypes` | `contentHandling` | Payload della richiesta di integrazione | | --- | --- | --- | --- | --- | | Dati di testo | Qualsiasi tipo di dato | Undefined | Undefined | UTF8stringa codificata | | Dati di testo | Qualsiasi tipo di dato | Undefined | CONVERT\$1TO\$1BINARY | BLOB binario con codifica Base64 | | Dati di testo | Qualsiasi tipo di dato | Undefined | CONVERT\$1TO\$1TEXT | UTF8-stringa codificata | | Dati di testo | Un tipo di dati di testo | Imposta con tipi di supporto corrispondenti | Undefined | Dati di testo | | Dati di testo | Un tipo di dati di testo | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1BINARY | BLOB binario con codifica Base64 | | Dati di testo | Un tipo di dati di testo | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1TEXT | Dati di testo | | Dati binari | Un tipo di dati binari | Imposta con tipi di supporto corrispondenti | Undefined | Dati binari | | Dati binari | Un tipo di dati binari | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1BINARY | Dati binari | | Dati binari | Un tipo di dati binari | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1TEXT | Stringa con codifica Base64 | La tabella seguente mostra come API Gateway converte il payload di risposta per configurazioni specifiche dell'`Accept`intestazione di una richiesta, l'`binaryMediaTypes`elenco di una [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa e il valore della `contentHandling` proprietà della risorsa. [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) **Importante** Quando una richiesta contiene più tipi di supporto nell'intestazione `Accept`, API Gateway mantiene la conformità solo con il primo tipo di supporto `Accept`. Se non è possibile controllare l'ordine dei tipi di supporto `Accept` e il tipo di supporto del contenuto binario non è il primo dell'elenco, aggiungere il primo tipo di supporto `Accept` nell'elenco `binaryMediaTypes` dell'API. API Gateway gestisce tutti i tipi di contenuto in questo elenco come binari. Ad esempio, per inviare un file JPEG utilizzando un elemento `` in un browser, il browser potrebbe inviare `Accept:image/webp,image/*,*/*;q=0.8` in una richiesta. Aggiungendo `image/webp` all'elenco `binaryMediaTypes`, l'endpoint riceve il file JPEG come binario. | Payload della risposta di integrazione | Intestazione `Accept` della richiesta | `binaryMediaTypes` | `contentHandling` | Payload della risposta del metodo | | --- | --- | --- | --- | --- | | Dati di testo o binari | Un tipo di testo | Undefined | Undefined | UTF8stringa codificata | | Dati di testo o binari | Un tipo di testo | Undefined | CONVERT\$1TO\$1BINARY | BLOB con codifica Base64 | | Dati di testo o binari | Un tipo di testo | Undefined | CONVERT\$1TO\$1TEXT | UTF8-stringa codificata | | Dati di testo | Un tipo di testo | Imposta con tipi di supporto corrispondenti | Undefined | Dati di testo | | Dati di testo | Un tipo di testo | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1BINARY | BLOB con codifica Base64 | | Dati di testo | Un tipo di testo | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1TEXT | UTF8-stringa codificata | | Dati di testo | Un tipo binario | Imposta con tipi di supporto corrispondenti | Undefined | BLOB con codifica Base64 | | Dati di testo | Un tipo binario | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1BINARY | BLOB con codifica Base64 | | Dati di testo | Un tipo binario | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1TEXT | UTF8-stringa codificata | | Dati binari | Un tipo di testo | Imposta con tipi di supporto corrispondenti | Undefined | Stringa con codifica Base64 | | Dati binari | Un tipo di testo | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1BINARY | Dati binari | | Dati binari | Un tipo di testo | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1TEXT | Stringa con codifica Base64 | | Dati binari | Un tipo binario | Imposta con tipi di supporto corrispondenti | Undefined | Dati binari | | Dati binari | Un tipo binario | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1BINARY | Dati binari | | Dati binari | Un tipo binario | Imposta con tipi di supporto corrispondenti | CONVERT\$1TO\$1TEXT | Stringa con codifica Base64 | Quando converti un payload di testo in un BLOB binario, API Gateway assume che i dati di testo siano una stringa con codifica base64 e genera un output dei dati binari come BLOB con codifica base64. Se la conversione non va a buon fine, viene restituita una risposta `500` che indica un errore di configurazione dell'API. Non fornisci un modello di mappatura per una conversione di questo tipo, sebbene tu debba abilitare i [comportamenti passthrough](integration-passthrough-behaviors.md) sull'API. Quando converti un payload binario in una stringa di testo, API Gateway applica sempre una codifica base64 ai dati binari. Per tale payload puoi definire un modello di mappatura, ma puoi accedere alla stringa con codifica base64 nel modello di mappatura solo attraverso `$input.body`, come viene mostrato nel seguente estratto di un modello di mappatura di esempio. ``` { "data": "$input.body" } ``` Per fare in modo che il payload binario venga passato senza alcuna modifica, devi abilitare i [comportamenti passthrough](integration-passthrough-behaviors.md) sull'API. # Abilitazione del supporto binario tramite la console API Gateway In questa sezione viene descritto come abilitare il supporto binario tramite la console API Gateway. Come esempio, utilizziamo un'API integrata con Amazon S3. Ci focalizziamo sulle attività per impostare i tipi di supporti ammessi e per specificare come dovrebbe essere gestito il payload. Per informazioni dettagliate su come creare un'API integrata con Amazon S3, consulta [Tutorial: creazione di una REST API come un proxy Amazon S3](integrating-api-with-aws-services-s3.md). **Per abilitare il supporto binario mediante la console API Gateway** 1. Imposta i tipi di supporto binario per l'API: 1. Crea una nuova API o scegline una esistente. Ad esempio, noi utilizziamo l'API `FileMan`. 1. Nell'API selezionata nel pannello di navigazione principale scegli **Impostazioni API**. 1. Nel riquadro **Impostazioni API** scegli **Gestisci tipi di supporti** nella sezione **Tipi di media binari**. 1. Scegli **Aggiungi tipo di supporto binario**. 1. Immetti il tipo di supporto richiesto, ad esempio **image/png**, nel campo di input. Se necessario, ripeti questa fase per aggiungere altri tipi di supporto. Per supportare tutti i tipi di file multimediali binari, specifica `*/*`. 1. Scegli **Save changes** (Salva modifiche). 1. Imposta il modo in cui i payload dei messaggi vengono gestiti per il metodo API: 1. Crea una nuova risorsa o scegli una risorsa esistente dell'API. Ad esempio, noi utilizziamo la risorsa `/{folder}/{item}`. 1. Crea un nuovo metodo o scegli un metodo esistente della risorsa. Come esempio, utilizziamo il metodo `GET /{folder}/{item}` integrato nell'azione `Object GET` in Amazon S3. 1. Per **Gestione contenuti** scegli un'opzione. ![\[Impostare il metodo GET nella console API Gateway.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/binary-support-content-handling-on-method-new-console.png) Scegliere **Passthrough** se non si vuole convertire il corpo quando il client e il back-end accettano lo stesso formato binario. Scegli **Converti in testo** per convertire il corpo binario in una stringa con codifica base64 quando, ad esempio, il back-end richiede che il payload di una richiesta binaria venga passato come proprietà JSON. Scegli quindi **Converti in binario** quando il client invia una stringa con codifica base64 e il back-end richiede il formato binario originale o quando l'endpoint restituisce una stringa con codifica base64 e il client accetta solo l'output binario. 1. Per **Richiesta corpo passthrough** scegli **Quando non ci sono modelli definiti (consigliato)**. Puoi anche scegliere **Mai**. Ciò significa che l'API rifiuterà i dati con content-types che non dispongono di un modello di mappatura. 1. Mantieni l'intestazione `Accept` della richiesta in entrata nella richiesta di integrazione. Procedi in questo modo se hai impostato `contentHandling` su `passthrough` e vuoi sovrascrivere questa impostazione al runtime. ![\[Mantenimento dell'intestazione Accept nella richiesta di integrazione.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/binary-support-preserve-incoming-accept-header-new-console.png) 1. Per la conversione in testo, definisci un modello di mappatura per mettere i dati binari con codifica base64 nel formato richiesto. Un esempio di modello di mappatura per la conversione in testo è il seguente: ``` { "operation": "thumbnail", "base64Image": "$input.body" } ``` Il formato di questo modello di mappatura dipende dai requisiti dell'endpoint dell'input. 1. Scegli **Save** (Salva). # Abilitazione del supporto binario tramite l'API REST API Gateway Le seguenti attività mostrano come abilitare il supporto binario tramite le chiamate dell'API REST API Gateway. **Topics** + [Aggiungi e aggiorna i tipi di supporti binari esistenti per un'API](#api-gateway-payload-encodings-setup-with-api-set-encodings-map) + [Configurazione delle conversioni dei payload delle richieste](#api-gateway-payload-encodings-setup-with-api-set-integration-request-encoding) + [Configurazione delle conversioni dei payload delle risposte](#api-gateway-payload-encodings-setup-with-api-set-integration-response-encoding) + [Conversione dei dati binari in dati di testo](#api-gateway-payload-encodings-convert-binary-to-string) + [Conversione dei dati di testo in un payload binario](#api-gateway-payload-encodings-convert-string-to-binary) + [Passaggio attraverso un payload binario](#api-gateway-payload-encodings-pass-binary-as-is) ## Aggiungi e aggiorna i tipi di supporti binari esistenti per un'API Per fare in modo che API Gateway utilizzi un nuovo tipo di supporto binario, devi aggiungerlo all'elenco `binaryMediaTypes` della risorsa `RestApi`. Ad esempio, per fare in modo che API Gateway gestisca le immagini JPEG, invia una richiesta `PATCH` alla risorsa `RestApi`: ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/image~1jpeg" } ] } ``` La specifica di tipo MIME di `image/jpeg`, parte del valore della proprietà `path`, viene ignorata come `image~1jpeg`. Per aggiornare i tipi di supporto binario utilizzati, sostituisci o elimina i tipi di supporto dall'elenco `binaryMediaTypes` della risorsa `RestApi`. Ad esempio, per cambiare il supporto binario dai file JPEG ai byte non elaborati, invia una richiesta `PATCH` alla risorsa `RestApi`, come segue. ``` PATCH /restapis/ { "patchOperations" : [{ "op" : "replace", "path" : "/binaryMediaTypes/image~1jpeg", "value" : "application/octet-stream" }, { "op" : "remove", "path" : "/binaryMediaTypes/image~1jpeg" }] } ``` ## Configurazione delle conversioni dei payload delle richieste Se l'endpoint richiede un input binario, imposta la proprietà `contentHandling` della risorsa `Integration` su `CONVERT_TO_BINARY`. A tale scopo, invia una richiesta `PATCH`, come segue: ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Configurazione delle conversioni dei payload delle risposte Se il client accetta il risultato come BLOB binario invece del payload con codifica base64 restituito dall'endpoint, imposta la proprietà `contentHandling` della risorsa `IntegrationResponse` su `CONVERT_TO_BINARY`. A questo scopo, inviare una richiesta `PATCH`, come segue: ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }] } ``` ## Conversione dei dati binari in dati di testo Per inviare dati binari come proprietà JSON dell'input a AWS Lambda o Kinesis tramite API Gateway, procedi come segue: 1. Abilita il supporto del payload binario dell'API aggiungendo il nuovo tipo di supporto binario di `application/octet-stream` all'elenco `binaryMediaTypes` dell'API. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Imposta `CONVERT_TO_TEXT` per la proprietà `contentHandling` della risorsa `Integration` e fornisci un modello di mappatura per assegnare la stringa con codifica base64 dei dati binari alla proprietà JSON. Nell'esempio che segue, la proprietà JSON è `body` e `$input.body` detiene la stringa con codifica base64. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_TEXT" }, { "op" : "add", "path" : "/requestTemplates/application~1octet-stream", "value" : "{\"body\": \"$input.body\"}" } ] } ``` ## Conversione dei dati di testo in un payload binario Supponiamo che una funzione Lambda restituisca un file di immagine come stringa con codifica base64. Per passare questo output binario al client tramite API Gateway, procedi come segue: 1. Aggiorna l'elenco `binaryMediaTypes` dell'API aggiungendo il tipo di supporto binario di `application/octet-stream`, se non è già presente nell'elenco. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream", }] } ``` 1. Imposta la proprietà `contentHandling` della risorsa `Integration` su `CONVERT_TO_BINARY`. Non definire un modello di mappatura. Se non definisci un modello di mappatura, API Gateway chiede al modello passthrough di restituire il BLOB binario con codifica base64 come file immagine al client. ``` PATCH /restapis//resources//methods//integration/responses/ { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" } ] } ``` ## Passaggio attraverso un payload binario Per memorizzare un'immagine in un bucket Amazon S3 tramite API Gateway, procedi come segue: 1. Aggiorna l'elenco `binaryMediaTypes` dell'API aggiungendo il tipo di supporto binario di `application/octet-stream`, se non è già presente nell'elenco. ``` PATCH /restapis/ { "patchOperations" : [ { "op" : "add", "path" : "/binaryMediaTypes/application~1octet-stream" } ] } ``` 1. Imposta la proprietà `contentHandling` della risorsa `Integration` su `CONVERT_TO_BINARY`. Imposta `WHEN_NO_MATCH` come il valore della proprietà `passthroughBehavior` senza definire un modello di mappatura. Ciò consente ad API Gateway di richiamare il modello passthrough. ``` PATCH /restapis//resources//methods//integration { "patchOperations" : [ { "op" : "replace", "path" : "/contentHandling", "value" : "CONVERT_TO_BINARY" }, { "op" : "replace", "path" : "/passthroughBehaviors", "value" : "WHEN_NO_MATCH" } ] } ``` # Importazione ed esportazione di codifiche di contenuti per Gateway API Per importare l'`binaryMediaTypes`elenco su un [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), utilizzate la seguente estensione API Gateway nel file di definizione OpenAPI dell'API. L'estensione viene anche utilizzata per esportare le impostazioni dell'API. + [x-amazon-apigateway-binaryproprietà -media-types](api-gateway-swagger-extensions-binary-media-types.md) Per importare ed esportare il valore della proprietà `contentHandling` su una risorsa `Integration` o `IntegrationResponse`, utilizza le seguenti estensioni API Gateway per le definizioni OpenAPI: + [x-amazon-apigateway-integration oggetto](api-gateway-swagger-extensions-integration.md) + [x-amazon-apigateway-integrationoggetto.response](api-gateway-swagger-extensions-integration-response.md) # Restituzione di supporti binari da un'integrazione proxy Lambda in Gateway API Per restituire un supporto binario da un'[integrazione proxy AWS Lambda](set-up-lambda-proxy-integrations.md), codificare in base64 la risposta dalla funzione Lambda. È inoltre necessario [configurare i tipi di supporti binari dell'API](api-gateway-payload-encodings-configure-with-console.md). Quando si configurano i tipi di supporti binari dell’API, l’API tratta quel tipo di contenuto come dati binari. Il limite della dimensione del payload è 10 MB. **Nota** Per utilizzare un browser Web per richiamare un'API con questo esempio di integrazione, imposta i tipi di supporti binari dell'API su `*/*`. API Gateway utilizza la prima intestazione `Accept` dai client per determinare se una risposta deve restituire supporti binari. Per restituire un supporto binario quando non è possibile controllare l'ordine dei valori delle intestazioni `Accept`, ad esempio le richieste da un browser, impostare i tipi di supporti binari dell'API su `*/*` (per tutti i tipi di contenuto). Il seguente esempio di funzione Lambda può restituire ai client un'immagine binaria da Amazon S3 o del testo. La risposta della funzione include un'intestazione `Content-Type` per indicare al client il tipo di dati che restituisce. La funzione imposta in modo condizionale la proprietà `isBase64Encoded` nella risposta, a seconda del tipo di dati che restituisce. ------ #### [ Node.js ] ``` import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3" const client = new S3Client({region: 'us-east-2'}); export const handler = async (event) => { var randomint = function(max) { return Math.floor(Math.random() * max); } var number = randomint(2); if (number == 1){ const input = { "Bucket" : "bucket-name", "Key" : "image.png" } try { const command = new GetObjectCommand(input) const response = await client.send(command); var str = await response.Body.transformToByteArray(); } catch (err) { console.error(err); } const base64body = Buffer.from(str).toString('base64'); return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64body, 'isBase64Encoded': true } } else { return { 'headers': { "Content-Type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } } } ``` ------ #### [ Python ] ``` import base64 import boto3 import json import random s3 = boto3.client('s3') def lambda_handler(event, context): number = random.randint(0,1) if number == 1: response = s3.get_object( Bucket='bucket-name', Key='image.png', ) image = response['Body'].read() return { 'headers': { "Content-Type": "image/png" }, 'statusCode': 200, 'body': base64.b64encode(image).decode('utf-8'), 'isBase64Encoded': True } else: return { 'headers': { "Content-type": "text/html" }, 'statusCode': 200, 'body': "

This is text

", } ``` ------ Per ulteriori informazioni sui tipi di supporti binari, consulta [Tipi di supporti binari per REST APIs in API Gateway](api-gateway-payload-encodings.md). # Accesso a file binari in Amazon S3 tramite l'API di API Gateway Gli esempi seguenti mostrano il file OpenAPI utilizzato per accedere alle immagini in Amazon S3, come eseguire il download di un'immagine da Amazon S3 e come caricare un'immagine su Amazon S3. **Topics** + [File OpenAPI di un'API di esempio per accedere alle immagini in Amazon S3](#api-gateway-content-encodings-example-image-s3-swagger-file) + [Download di un'immagine da Amazon S3](#api-gateway-content-encodings-example-download-image-from-s3) + [Caricamento di un'immagine su Amazon S3](#api-gateway-content-encodings-example-upload-image-to-s3) ## File OpenAPI di un'API di esempio per accedere alle immagini in Amazon S3 Il seguente file OpenAPI mostra un'API di esempio che illustra il download di un file di immagine da Amazon S3 e il caricamento di un file di immagine su Amazon S3. Questa API espone i metodi `GET /s3?key={file-name}` e `PUT /s3?key={file-name}` per il download e il caricamento di un file di immagine specifico. Il metodo `GET` restituisce il file immagine come stringa con codifica base64, parte di un output JSON, seguita dal modello di mappatura fornito, in una risposta 200 OK. Il metodo `PUT` prende un BLOB binario non elaborato come input e restituisce una risposta 200 OK con un payload vuoto. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/s3": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling": "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/s3": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "GET", "type": "aws" } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } }, "requestParameters": { "integration.request.path.key": "method.request.querystring.key" }, "uri": "arn:aws:apigateway:us-west-2:s3:path/{key}", "passthroughBehavior": "when_no_match", "httpMethod": "PUT", "type": "aws", "contentHandling" : "CONVERT_TO_BINARY" } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Download di un'immagine da Amazon S3 Per eseguire il download di un file immagine (`image.jpg`) come BLOB binario da Amazon S3: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` La risposta andata a buon fine avrebbe questa struttura: ``` 200 OK HTTP/1.1 [raw bytes] ``` I byte non elaborati vengono restituiti perché l'intestazione `Accept` è impostata sul tipo di supporto binario `application/octet-stream` e il supporto binario è abilitato per l'API. In alternativa, per eseguire il download di un file di immagine (`image.jpg`) come stringa con codifica base64 (formattata come una proprietà JSON) da Amazon S3, aggiungi un modello di risposta alla risposta 200 di integrazione, come mostrato nel blocco di definizione OpenAPI in grassetto: ``` "x-amazon-apigateway-integration": { "credentials": "arn:aws:iam::123456789012:role/binarySupportRole", "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } }, ``` Di seguito è riportato l'aspetto della richiesta di download di un file di immagine: ``` GET /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Caricamento di un'immagine su Amazon S3 Per caricare un file immagine (`image.jpg`) come BLOB binario su Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK HTTP/1.1 ``` Per caricare un file immagine (`image.jpg`) come stringa con codifica base64 su Amazon S3: ``` PUT /v1/s3?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` Il payload di input deve essere una stringa con codifica base64, poiché il valore dell'intestazione `Content-Type` è impostato su `application/json`. L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK HTTP/1.1 ``` # Accesso a file binari in Lambda tramite l'API di API Gateway Il seguente esempio di OpenAPI dimostra come accedere a un file binario AWS Lambda tramite un'API API Gateway. Questa API espone i metodi `GET /lambda?key={file-name}` e `PUT /lambda?key={file-name}` per il download e il caricamento di un file di immagine specifico. Il metodo `GET` restituisce il file immagine come stringa con codifica base64, parte di un output JSON, seguita dal modello di mappatura fornito, in una risposta 200 OK. Il metodo `PUT` prende un BLOB binario non elaborato come input e restituisce una risposta 200 OK con un payload vuoto. Si crea la funzione Lambda chiamata dall'API che restituirà una stringa con codifica base64 con l'intestazione `Content-Type` di `application/json`. **Topics** + [File OpenAPI di un'API di esempio per accedere alle immagini in Lambda](#api-gateway-content-encodings-example-image-lambda-swagger-file) + [Download di un'immagine da Lambda](#api-gateway-content-encodings-example-download-image-from-lambda) + [Caricamento di un'immagine su Lambda](#api-gateway-content-encodings-example-upload-image-to-lambda) ## File OpenAPI di un'API di esempio per accedere alle immagini in Lambda Il seguente file OpenAPI mostra un'API di esempio che illustra il download di un file di immagine da Lambda e il caricamento di un file di immagine in Lambda. ------ #### [ OpenAPI 3.0 ] ``` { "openapi": "3.0.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "paths": { "/lambda": { "get": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "parameters": [ { "name": "key", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empty" } }, "application/octet-stream": { "schema": { "$ref": "#/components/schemas/Empty" } } } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling": "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types": [ "application/octet-stream", "image/jpeg" ], "servers": [ { "url": "https://abcdefghi.execute-api.us-east-1.amazonaws.com/{basePath}", "variables": { "basePath": { "default": "/v1" } } } ], "components": { "schemas": { "Empty": { "type": "object", "title": "Empty Schema" } } } } ``` ------ #### [ OpenAPI 2.0 ] ``` { "swagger": "2.0", "info": { "version": "2016-10-21T17:26:28Z", "title": "ApiName" }, "host": "abcdefghi.execute-api.us-east-1.amazonaws.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/lambda": { "get": { "produces": [ "application/json" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200", "responseTemplates": { "application/json": "{\n \"image\": \"$input.body\"\n}" } } } } }, "put": { "produces": [ "application/json", "application/octet-stream" ], "parameters": [ { "name": "key", "in": "query", "required": false, "type": "string" } ], "responses": { "200": { "description": "200 response", "schema": { "$ref": "#/definitions/Empty" } }, "500": { "description": "500 response" } }, "x-amazon-apigateway-integration": { "uri": "arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:123456789012:function:image/invocations", "type": "AWS", "credentials": "arn:aws:iam::123456789012:role/Lambda", "httpMethod": "POST", "contentHandling" : "CONVERT_TO_TEXT", "requestTemplates": { "application/json": "{\n \"imageKey\": \"$input.params('key')\", \"image\": \"$input.body\"\n}" }, "responses": { "default": { "statusCode": "500" }, "2\\d{2}": { "statusCode": "200" } } } } } }, "x-amazon-apigateway-binary-media-types" : ["application/octet-stream", "image/jpeg"], "definitions": { "Empty": { "type": "object", "title": "Empty Schema" } } } ``` ------ ## Download di un'immagine da Lambda Per eseguire il download di un file immagine (`image.jpg`) come BLOB binario da Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/octet-stream ``` L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK HTTP/1.1 [raw bytes] ``` Per eseguire il download di un file immagine (`image.jpg`) come stringa con codifica base64, formattato come proprietà JSON, da Lambda: ``` GET /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json ``` L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK HTTP/1.1 { "image": "W3JhdyBieXRlc10=" } ``` ## Caricamento di un'immagine su Lambda Per caricare un file immagine (`image.jpg`) come BLOB binario su Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/octet-stream Accept: application/json [raw bytes] ``` L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK ``` Per caricare un file immagine (`image.jpg`) come stringa con codifica base64 su Lambda: ``` PUT /v1/lambda?key=image.jpg HTTP/1.1 Host: abcdefghi.execute-api.us-east-1.amazonaws.com Content-Type: application/json Accept: application/json W3JhdyBieXRlc10= ``` L'aspetto di una risposta andata a buon fine è il seguente: ``` 200 OK ``` # Invocazione di REST API in Gateway API Per chiamare un'API distribuita, i client inviano richieste all'URL del servizio del componente API Gateway per l'esecuzione dell'API, ovvero `execute-api`. L'URL di base per le API REST si presenta nel formato seguente: ``` https://api-id.execute-api.region.amazonaws.com/stage/ ``` dove *api-id* è l'identificativo dell'API, *region* è la Regione AWS e *stage* è il nome della fase dell'implementazione dell'API. **Importante** Prima di invocare un'API, devi distribuirla in API Gateway. Per istruzioni sull'implementazione di un'API, consulta [Implementazione di REST API in Gateway API](how-to-deploy-api.md). **Topics** + [Ottenimento dell'URL di invocazione di un'API](#apigateway-how-to-call-rest-api) + [Invocazione di un'API](#apigateway-call-api) + [Utilizzo della console API Gateway per il test di un metodo API REST](how-to-test-method.md) + [Utilizzo di un SDK Java generato da API Gateway per un'API REST](how-to-call-apigateway-generated-java-sdk.md) + [Utilizzo di un SDK Android generato da API Gateway per un'API REST](how-to-generate-sdk-android.md) + [Usa un JavaScript SDK generato da API Gateway per un'API REST](how-to-generate-sdk-javascript.md) + [Utilizzo di un SDK Ruby generato da API Gateway per un'API REST](how-to-call-sdk-ruby.md) + [Uso dell'SDK iOS generato da API Gateway per un'API REST in Objective-C o Swift](how-to-generate-sdk-ios.md) ## Ottenimento dell'URL di invocazione di un'API Per ottenere l'URL di invocazione di un'API è possibile utilizzare la console, AWS CLI o una definizione OpenAPI esportata. ### Ottenimento dell'URL di invocazione di un'API tramite la console La procedura seguente mostra come ottenere l'URL di invocazione di un'API tramite la console REST API. **Per ottenere l'URL di invocazione di un'API tramite la console REST API** 1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Scegli un'API implementata. 1. Nel riquadro di navigazione principale, seleziona **Log**. 1. In **Dettagli fase**, scegli l'icona Copia per copiare l'URL di richiamo dell'API. Questo è l'URL per la risorsa root dell'API. ![\[Dopo aver creato la REST API, la console mostra il valore URL di richiamo dell'API.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/getting-started-rest-invoke-url.png) 1. Per ottenere l'URL di invocazione per un'altra risorsa dell'API, espandi la fase nel pannello di navigazione secondario, quindi seleziona un metodo. 1. Scegli l'icona Copia per copiare l'URL di invocazione a livello di risorsa dell'API. ![\[L'URL a livello di risorsa della REST API si trova nel pannello di navigazione secondario della fase.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/resource-level-invoke-url.png) #### Ottenimento dell'URL di invocazione di un'API tramite AWS CLI La procedura seguente mostra come ottenere l'URL di invocazione di un'API tramite AWS CLI. **Per ottenere l'URL di invocazione di un'API tramite AWS CLI** 1. Esegui il comando seguente per ottenere il valore `rest-api-id`. Questo comando restituisce tutti i valori `rest-api-id` presenti nella Regione in uso. Per ulteriori informazioni, consulta [get-rest-apis](https://docs.aws.amazon.com/cli/latest/reference/apigateway/get-rest-apis.html). ``` aws apigateway get-rest-apis ``` 1. Sostituisci il valore `rest-api-id` di esempio con il valore `rest-api-id` da utilizzare, il valore *\$1stage-name\$1* di esempio con il valore *\$1stage-name\$1* da utilizzare, quindi sostituisci *\$1region\$1* con la Regione in uso. ``` https://{restapi_id}.execute-api.{region}.amazonaws.com/{stage_name}/ ``` ##### Ottenimento dell'URL di invocazione di un'API tramite il file di definizione OpenAPI esportato dell'API È possibile anche creare l'URL root combinando i campi `host` e `basePath` di un file di definizione OpenAPI esportato dell'API. Per istruzioni su come esportare l'API, consulta [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md). ## Invocazione di un'API È possibile chiamare l'API implementata utilizzando il browser, curl o altre applicazioni, come [Postman](https://www.postman.com/). Inoltre, è possibile utilizzare la console Gateway API per testare una chiamata API. Il test sfrutta la funzionalità `TestInvoke` di Gateway API, che consente di testare l'API prima che sia implementata. Per ulteriori informazioni, consulta [Utilizzo della console API Gateway per il test di un metodo API REST](how-to-test-method.md). **Nota** I valori dei parametri delle stringe di query di un URL di chiamata non possono includere `%%`. ### Invocazione di un'API tramite un browser web Se l'API consente l'accesso anonimo, è possibile utilizzare qualsiasi browser web per invocare un metodo `GET`. Inserisci l'URL di invocazione completo nella barra degli indirizzi del browser. Per altri metodi o chiamate che richiedono l'autenticazione, è necessario specificare un payload oppure firmare le richieste. Puoi gestire queste operazioni in uno script di una pagina HTML o in un'applicazione client utilizzando uno degli SDK AWS. #### Invocazione di un'API tramite curl Per chiamare l'API è possibile utilizzare uno strumento come [curl](https://curl.se/) nel terminale. Il seguente comando curl di esempio invoca il metodo GET sulla risorsa `getUsers` della fase `prod` di un'API. ------ #### [ Linux or Macintosh ] ``` curl -X GET 'https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers' ``` ------ #### [ Windows ] ``` curl -X GET "https://b123abcde4.execute-api.us-west-2.amazonaws.com/prod/getUsers" ``` ------ # Utilizzo della console API Gateway per il test di un metodo API REST Utilizzo della console API Gateway per il test di un metodo API REST. **Topics** + [Prerequisiti](#how-to-test-method-prerequisites) + [Test di un metodo tramite la console API Gateway](#how-to-test-method-console) ## Prerequisiti + È necessario specificare le impostazioni per i metodi che si intende testare. Segui le istruzioni in [Metodi per REST APIs in API Gateway](how-to-method-settings.md). ## Test di un metodo tramite la console API Gateway **Importante** Quando si testano i metodi con la console Gateway API è possibile che alle risorse vengano apportate modifiche non annullabili. Eseguire il test di un metodo tramite la console API Gateway equivale a chiamare il metodo dall'esterno della console. Ad esempio, se si utilizza la console API Gateway per chiamare un metodo che elimina le risorse di un'API e la chiamata del metodo riesce, le risorse vengono eliminate. **Test del metodo** 1. Accedere alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Scegliere un'API REST. 1. Nel riquadro **Resources (Risorse)** scegliere il metodo che si desidera testare. 1. Seleziona la scheda **Test**. Potrebbe essere necessario scegliere il pulsante freccia destra per visualizzare la scheda. ![\[Utilizza la scheda Test per eseguire il test dell'API. Si trova accanto alla scheda Risposta metodo.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-gateway-test-new-console.png) Immetti i valori nelle caselle visualizzate, ad esempio **Stringhe di query**, **Intestazioni** e **Corpo della richiesta**. La console include tali valori della richiesta del metodo nel modulo dell'applicazione/json predefinito. Per specificare eventuali opzioni aggiuntive, contatta il proprietario dell'API. 1. Scegli **Test (Esegui test)**. Verranno visualizzate le seguenti informazioni: + **Request (Richiesta)** è il percorso della risorsa chiamato per il metodo. + **Status (Stato)** è il codice dello stato HTTP della risposta. + **Latenza in ms** è l'intervallo di tempo tra la ricezione della richiesta dal chiamante e la risposta restituita. + **Corpo della risposta** è il corpo della risposta HTTP. + **Intestazioni delle risposte** sono le intestazioni di risposta HTTP. **Suggerimento** A seconda della mappatura, il codice di stato HTTP, il testo della risposta e le intestazioni potrebbero essere diversi da quelli inviati dalla funzione Lambda, dal proxy HTTP o dal proxy dei servizi AWS. + I **log** sono le voci di Amazon CloudWatch Logs simulate che sarebbero state scritte se il metodo fosse stato chiamato dall'esterno della console API Gateway. **Nota** Anche se le voci di CloudWatch Logs sono simulate, i risultati della chiamata al metodo sono reali. Oltre alla console API Gateway, per testare l'invocazione di un metodo puoi usare la AWS CLI o un SDK AWS per API Gateway. Per informazioni su come usare AWS CLI per eseguire questa operazione, consulta [test-invoke-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/test-invoke-method.html). # Utilizzo di un SDK Java generato da API Gateway per un'API REST In questa sezione verranno illustrate, a titolo di esempio, le fasi necessarie per utilizzare un SDK Java generato da API Gateway per un'API REST mediante l'API del [calcolatore semplice](simple-calc-lambda-api-swagger-definition.md). Per poter procedere, è necessario avere completato le fasi descritte in [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md). **Per installare e utilizzare l'SDK Java generato da API Gateway** 1. Estrai il contenuto del file .zip generato da API Gateway scaricato precedentemente. 1. Scaricare e installare [Apache Maven](https://maven.apache.org/) (versione 3.5 o successiva). 1. Scaricare e installare [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html). 1. Imposta la variabile di ambiente `JAVA_HOME`. 1. Passa alla cartella dell'SDK decompressa in cui si trova il file pom.xml. Per impostazione predefinita, questa cartella è `generated-code`. Eseguire il comando **mvn install** per installare i file di artefatto compilati nel repository Maven locale. Viene creata una cartella `target` contenente la libreria SDK compilata. 1. Digita il comando seguente in una directory vuota per creare uno stub di progetto del client e chiamare l'API mediante la libreria SDK installata. ``` mvn -B archetype:generate \ -DarchetypeGroupdId=org.apache.maven.archetypes \ -DgroupId=examples.aws.apig.simpleCalc.sdk.app \ -DartifactId=SimpleCalc-sdkClient ``` **Nota** Nel comando precedente è stato inserito il separatore `\` per maggiore leggibilità. Il comando deve trovarsi su un'unica riga senza il separatore. Questo comando crea uno stub di applicazione. Lo stub di applicazione contiene un file `pom.xml` e una cartella `src` nella directory root del progetto (*SimpleCalc-sdkClient* nel comando precedente). Inizialmente sono presenti due file di origine: `src/main/java/{package-path}/App.java` e `src/test/java/{package-path}/AppTest.java`. In questo esempio *\$1package-path\$1* è `examples/aws/apig/simpleCalc/sdk/app`. Il precorso del pacchetto viene derivato dal valore `DarchetypeGroupdId`. Puoi usare il file `App.java` come modello per l'applicazione client e, se necessario, aggiungerne altri nella stessa cartella. Puoi usare il file `AppTest.java` come modello di test di unità per l'applicazione e, se necessario, aggiungere altri file di codice di test nella stessa cartella. 1. Aggiorna le dipendenze di pacchetto nel file `pom.xml` generato come segue sostituendo, se necessario, le proprietà `groupId`, `artifactId`, `version` e `name` del progetto: ``` 4.0.0 examples.aws.apig.simpleCalc.sdk.app SimpleCalc-sdkClient jar 1.0-SNAPSHOT SimpleCalc-sdkClient http://maven.apache.org com.amazonaws aws-java-sdk-core 1.11.94 my-apig-api-examples simple-calc-sdk 1.0.0 junit junit 4.12 test commons-io commons-io 2.5 org.apache.maven.plugins maven-compiler-plugin 3.5.1 1.8 1.8 ``` **Nota** Quando una versione più recente dell'artefatto dipendente di `aws-java-sdk-core` è incompatibile con la versione specificata sopra (`1.11.94`), è necessario aggiornare il tag `` alla nuova versione. 1. Quindi mostreremo come chiamare l'API mediante l'SDK chiamando i metodi `getABOp(GetABOpRequest req)`, `getApiRoot(GetApiRootRequest req)` e `postApiRoot(PostApiRootRequest req)` dell'SDK. Questi metodi corrispondono ai metodi `GET /{a}/{b}/{op}`, `GET /?a={x}&b={y}&op={operator}` e `POST /`, rispettivamente con un payload di richieste API `{"a": x, "b": y, "op": "operator"}`. Aggiorna il file `App.java` come segue: ``` package examples.aws.apig.simpleCalc.sdk.app; import java.io.IOException; import com.amazonaws.opensdk.config.ConnectionConfiguration; import com.amazonaws.opensdk.config.TimeoutConfiguration; import examples.aws.apig.simpleCalc.sdk.*; import examples.aws.apig.simpleCalc.sdk.model.*; import examples.aws.apig.simpleCalc.sdk.SimpleCalcSdk.*; public class App { SimpleCalcSdk sdkClient; public App() { initSdk(); } // The configuration settings are for illustration purposes and may not be a recommended best practice. private void initSdk() { sdkClient = SimpleCalcSdk.builder() .connectionConfiguration( new ConnectionConfiguration() .maxConnections(100) .connectionMaxIdleMillis(1000)) .timeoutConfiguration( new TimeoutConfiguration() .httpRequestTimeout(3000) .totalExecutionTimeout(10000) .socketTimeout(2000)) .build(); } // Calling shutdown is not necessary unless you want to exert explicit control of this resource. public void shutdown() { sdkClient.shutdown(); } // GetABOpResult getABOp(GetABOpRequest getABOpRequest) public Output getResultWithPathParameters(String x, String y, String operator) { operator = operator.equals("+") ? "add" : operator; operator = operator.equals("/") ? "div" : operator; GetABOpResult abopResult = sdkClient.getABOp(new GetABOpRequest().a(x).b(y).op(operator)); return abopResult.getResult().getOutput(); } public Output getResultWithQueryParameters(String a, String b, String op) { GetApiRootResult rootResult = sdkClient.getApiRoot(new GetApiRootRequest().a(a).b(b).op(op)); return rootResult.getResult().getOutput(); } public Output getResultByPostInputBody(Double x, Double y, String o) { PostApiRootResult postResult = sdkClient.postApiRoot( new PostApiRootRequest().input(new Input().a(x).b(y).op(o))); return postResult.getResult().getOutput(); } public static void main( String[] args ) { System.out.println( "Simple calc" ); // to begin App calc = new App(); // call the SimpleCalc API Output res = calc.getResultWithPathParameters("1", "2", "-"); System.out.printf("GET /1/2/-: %s\n", res.getC()); // Use the type query parameter res = calc.getResultWithQueryParameters("1", "2", "+"); System.out.printf("GET /?a=1&b=2&op=+: %s\n", res.getC()); // Call POST with an Input body. res = calc.getResultByPostInputBody(1.0, 2.0, "*"); System.out.printf("PUT /\n\n{\"a\":1, \"b\":2,\"op\":\"*\"}\n %s\n", res.getC()); } } ``` Nel'esempio precedente le impostazioni di configurazione utilizzate per creare istanze del client SDK hanno esclusivamente scopo illustrativo e non sono necessariamente best practice consigliate. Anche la chiamata a `sdkClient.shutdown()` è facoltativa, soprattutto se si ha necessità di esercitare un controllo accurato su quando liberare risorse. Abbiamo mostrato i modelli fondamentali per chiamare un'API utilizzando un SDK Java. Le istruzioni possono essere applicate per chiamare altri metodi API. # Utilizzo di un SDK Android generato da API Gateway per un'API REST In questa sezione verranno illustrate le fasi necessarie per utilizzare un SDK Android generato da API Gateway per un'API REST. Per poter procedere, è necessario avere già completato le fasi descritte in [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md). **Nota** L'SDK generato non è compatibile con Android 4.4 e versioni precedenti. Per ulteriori informazioni, consulta [Note importanti Amazon API Gateway](api-gateway-known-issues.md). **Per installare e utilizzare l'SDK Android generato da API Gateway** 1. Estrai il contenuto del file .zip generato da API Gateway scaricato precedentemente. 1. Scaricare e installare [Apache Maven](https://maven.apache.org/) (preferibilmente versione 3.x). 1. Scaricare e installare [JDK 8](https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html). 1. Imposta la variabile di ambiente `JAVA_HOME`. 1. Eseguire il comando **mvn install** per installare i file di artefatto compilati nel repository Maven locale. Viene creata una cartella `target` contenente la libreria SDK compilata. 1. Copiare il file SDK (il cui nome viene derivato dai valori specificati per **Artifact Id** (Id artefatto) e **Artifact Version** (Versione artefatto) durante la generazione dell'SDK, ad esempio `simple-calcsdk-1.0.0.jar`) dalla cartella `target`, insieme a tutte le altre librerie della cartella `target/lib`, nella cartella `lib` del progetto. Se usi Android Studio, crea una cartella `libs` nel modulo della tua app client e copia il file .jar richiesto in questa cartella. Verifica che la sezione delle dipendenze nel file gradle del modulo contenga il codice seguente. ``` compile fileTree(include: ['*.jar'], dir: 'libs') compile fileTree(include: ['*.jar'], dir: 'app/libs') ``` Assicurati che non siano dichiarati file .jar duplicati. 1. Usa la classe `ApiClientFactory` per inizializzare l'SDK generato da API Gateway. Ad esempio: ``` ApiClientFactory factory = new ApiClientFactory(); // Create an instance of your SDK. Here, 'SimpleCalcClient.java' is the compiled java class for the SDK generated by API Gateway. final SimpleCalcClient client = factory.build(SimpleCalcClient.class); // Invoke a method: // For the 'GET /?a=1&b=2&op=+' method exposed by the API, you can invoke it by calling the following SDK method: Result output = client.rootGet("1", "2", "+"); // where the Result class of the SDK corresponds to the Result model of the API. // // For the 'GET /{a}/{b}/{op}' method exposed by the API, you can call the following SDK method to invoke the request, Result output = client.aBOpGet(a, b, c); // where a, b, c can be "1", "2", "add", respectively. // For the following API method: // POST / // host: ... // Content-Type: application/json // // { "a": 1, "b": 2, "op": "+" } // you can call invoke it by calling the rootPost method of the SDK as follows: Input body = new Input(); input.a=1; input.b=2; input.op="+"; Result output = client.rootPost(body); // where the Input class of the SDK corresponds to the Input model of the API. // Parse the result: // If the 'Result' object is { "a": 1, "b": 2, "op": "add", "c":3"}, you retrieve the result 'c') as String result=output.c; ``` 1. Per usare un fornitore di credenziali Amazon Cognito per autorizzare le chiamate all'API, usa la classe `ApiClientFactory` per passare un insieme di credenziali AWS utilizzando l'SDK generato da API Gateway, come mostrato nell'esempio seguente. ``` // Use CognitoCachingCredentialsProvider to provide AWS credentials // for the ApiClientFactory AWSCredentialsProvider credentialsProvider = new CognitoCachingCredentialsProvider( context, // activity context "identityPoolId", // Cognito identity pool id Regions.US_EAST_1 // region of Cognito identity pool ); ApiClientFactory factory = new ApiClientFactory() .credentialsProvider(credentialsProvider); ``` 1. Per impostare una chiave API utilizzando l'SDK generato da API Gateway, usa un codice simile al seguente. ``` ApiClientFactory factory = new ApiClientFactory() .apiKey("YOUR_API_KEY"); ``` # Usa un JavaScript SDK generato da API Gateway per un'API REST La procedura seguente mostra come utilizzare un JavaScript SDK generato da API Gateway. **Nota** Queste istruzioni presuppongono che tu abbia già completato la procedura descritta in [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md). **Importante** Se l'API ha solo metodi ANY definiti, il pacchetto SDK generato non conterrà un file `apigClient.js` e sarà necessario definire i metodi ANY manualmente. **Per installare, avviare e chiamare un JavaScript SDK generato da API Gateway per un'API REST** 1. Estrai il contenuto del file .zip generato da API Gateway scaricato precedentemente. 1. Abilita la condivisione delle risorse multi-origine (CORS) per tutti i metodi che l'SDK generato da API Gateway chiamerà. Per istruzioni, consulta [CORS per REST APIs in API Gateway](how-to-cors.md). 1. Nella tua pagina Web, includi i riferimenti ai seguenti script. ``` ``` 1. Nel codice inizializza l'SDK generato da API Gateway tramite un codice simile al seguente. ``` var apigClient = apigClientFactory.newClient(); ``` Per inizializzare l'SDK generato da API Gateway con AWS credenziali, utilizzate un codice simile al seguente. Se utilizzi AWS le credenziali, tutte le richieste all'API verranno firmate. ``` var apigClient = apigClientFactory.newClient({ accessKey: 'ACCESS_KEY', secretKey: 'SECRET_KEY', }); ``` Per utilizzare una chiave API con l'SDK generato da API Gateway, passa la chiave API come parametro all'oggetto `Factory`, usando un codice simile al seguente. Se utilizzi una chiave API, viene specificato come parte dell'intestazione `x-api-key` e tutte le richieste all'API verranno firmate. Questo significa che devi impostare le intestazioni Accept corrette di CORS per ogni richiesta. ``` var apigClient = apigClientFactory.newClient({ apiKey: 'API_KEY' }); ``` 1. Chiama i metodi API in API Gateway tramite un codice simile al seguente. Ogni chiamata restituisce una promessa con callback di successo e di fallimento. ``` var params = { // This is where any modeled request parameters should be added. // The key is the parameter name, as it is defined in the API in API Gateway. param0: '', param1: '' }; var body = { // This is where you define the body of the request, }; var additionalParams = { // If there are any unmodeled query parameters or headers that must be // sent with the request, add them here. headers: { param0: '', param1: '' }, queryParams: { param0: '', param1: '' } }; apigClient.methodName(params, body, additionalParams) .then(function(result){ // Add success callback code here. }).catch( function(result){ // Add error callback code here. }); ``` Qui, *methodName* è costruito dal percorso di risorsa della richiesta del metodo e dal verbo HTTP. Per l' SimpleCalc API, i metodi SDK per i metodi API di ``` 1. GET /?a=...&b=...&op=... 2. POST / { "a": ..., "b": ..., "op": ...} 3. GET /{a}/{b}/{op} ``` metodi SDK corrispondenti sono i seguenti: ``` 1. rootGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the query parameters 2. rootPost(null, body); // where body={"a": ..., "b": ..., "op": ...} 3. aBOpGet(params); // where params={"a": ..., "b": ..., "op": ...} is resolved to the path parameters ``` # Utilizzo di un SDK Ruby generato da API Gateway per un'API REST La seguente procedura mostra come utilizzare un SDK Ruby generato da Gateway API. **Nota** Queste istruzioni presuppongono che sia già stata completata la procedura in [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md). **Per installare, creare istanze e chiamare un SDK Ruby generato da API Gateway per un'API REST** 1. Decomprimi il file SDK Ruby scaricato. L'origine dell'SDK generato viene mostrata come segue. ![\[Decomprimere il file SDK Ruby scaricato in un modulo Ruby\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/ruby-gem-of-generated-sdk-for-simplecalc.png) 1. Crea una gem Ruby dall'origine dell'SDK generato utilizzando i comandi della shell seguenti in una finestra del terminale: ``` # change to /simplecalc-sdk directory cd simplecalc-sdk # build the generated gem gem build simplecalc-sdk.gemspec ``` Dopo questa operazione, **simplecalc-sdk-1.0.0.gem** diventa disponibile. 1. Installa la gem: ``` gem install simplecalc-sdk-1.0.0.gem ``` 1. Crea un'applicazione client. Crea un'istanza e inizializza il client SDK Ruby nell'app: ``` require 'simplecalc-sdk' client = SimpleCalc::Client.new( http_wire_trace: true, retry_limit: 5, http_read_timeout: 50 ) ``` Se l'API dispone di un'autorizzazione del `AWS_IAM` tipo configurato, è possibile includere le AWS credenziali del chiamante fornendo `accessKey` e `secretKey` durante l'inizializzazione: ``` require 'pet-sdk' client = Pet::Client.new( http_wire_trace: true, retry_limit: 5, http_read_timeout: 50, access_key_id: 'ACCESS_KEY', secret_access_key: 'SECRET_KEY' ) ``` 1. Fai chiamate API mediante l'SDK nell'app. **Suggerimento** Se non hai familiarità con le convenzioni delle chiamate ai metodi SDK, esamina il file `client.rb` nella cartella `lib` dell'SDK generato. La cartella contiene la documentazione relativa a ciascuna chiamata ai metodi API supportati. Per conoscere le operazioni supportate: ``` # to show supported operations: puts client.operation_names ``` I risultati sono visualizzati di seguito e corrispondono ai metodi API rispettivamente di `GET /?a={.}&b={.}&op={.}`, `GET /{a}/{b}/{op}` e `POST /`, oltre a un payload del formato `{a:"…", b:"…", op:"…"}`: ``` [:get_api_root, :get_ab_op, :post_api_root] ``` Per invocare il metodo API `GET /?a=1&b=2&op=+`, chiama il metodo SDK Ruby seguente: ``` resp = client.get_api_root({a:"1", b:"2", op:"+"}) ``` Per invocare il metodo API `POST /` con un payload di `{a: "1", b: "2", "op": "+"}`, chiama il metodo SDK Ruby seguente: ``` resp = client.post_api_root(input: {a:"1", b:"2", op:"+"}) ``` Per invocare il metodo API `GET /1/2/+`, chiama il metodo SDK Ruby seguente: ``` resp = client.get_ab_op({a:"1", b:"2", op:"+"}) ``` Le chiamate ai metodi SDK che riescono restituiscono la risposta seguente: ``` resp : { result: { input: { a: 1, b: 2, op: "+" }, output: { c: 3 } } } ``` # Uso dell'SDK iOS generato da API Gateway per un'API REST in Objective-C o Swift In questo tutorial mostreremo come usare un SDK iOS generato da API Gateway per un'API REST in un'app Objective-C o Swift per chiamare l'API sottostante. Useremo l'[SimpleCalc API](simple-calc-lambda-api.md) come esempio per illustrare i seguenti argomenti: + Come installare i componenti AWS Mobile SDK richiesti nel tuo progetto Xcode + Come creare l'oggetto client dell'API prima di chiamare i metodi dell'API + Come chiamare i metodi API attraverso i metodi SDK corrispondenti nell'oggetto client dell'API + Come preparare un input di metodo e analizzare il risultato utilizzando le classi di modello corrispondenti dell'SDK **Topics** + [Utilizzo di un SDK iOS (Objective-C) generato per chiamare l'API](#how-to-use-sdk-ios-objc) + [Utilizzo di un SDK iOS (Swift) generato per chiamare l'API](#how-to-generate-sdk-ios-swift) ## Utilizzo di un SDK iOS (Objective-C) generato per chiamare l'API Prima di iniziare la procedura seguente, è necessario completare le fasi descritte in [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md) per iOS in Objective-C e scaricare il file .zip dell'SDK generato. ### Installa l'SDK AWS mobile e un SDK iOS generato da API Gateway in un progetto Objective-C La procedura seguente descrive come installare l'SDK. **Per installare e utilizzare un SDK iOS generato da API Gateway in Objective-C** 1. Estrai il contenuto del file .zip generato da API Gateway scaricato precedentemente. Utilizzando l'[SimpleCalc API](simple-calc-lambda-api.md), potresti voler rinominare la cartella SDK decompressa con qualcosa del genere. **sdk\$1objc\$1simple\$1calc** In questa cartella SDK sono presenti un file `README.md` e un file `Podfile`. Il file `README.md` contiene le istruzioni per installare e usare l'SDK. Questo tutorial fornisce i dettagli relativi alle istruzioni. L'installazione consente di [CocoaPods](https://cocoapods.org)importare le librerie API Gateway richieste e altri componenti AWS Mobile SDK dipendenti. Devi aggiornare il file `Podfile` per importarlo SDKs nel progetto Xcode della tua app. La cartella SDK non archiviata contiene anche una cartella `generated-src` con il codice sorgente dell'SDK generato dell'API. 1. Avvia Xcode e crea un nuovo progetto Objective-C per iOS. Prendi nota della destinazione del progetto. Dovrai specificare questa impostazione nel `Podfile`. ![\[Trovare la destinazione in Xcode.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-find-target.png) 1. Per AWS Mobile SDK for iOS importarlo nel progetto Xcode utilizzando CocoaPods, procedi come segue: 1. Installa CocoaPods eseguendo il seguente comando in una finestra di terminale: ``` sudo gem install cocoapods pod setup ``` 1. Copia il file `Podfile` dalla cartella SDK estratta nella stessa directory in cui si trova il file di progetto Xcode. Sostituisci il blocco seguente: ``` target '' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` con il nome di destinazione del progetto: ``` target 'app_objc_simple_calc' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` Se il progetto Xcode già contiene un file denominato `Podfile`, aggiungi la riga di codice seguente: ``` pod 'AWSAPIGateway', '~> 2.4.7' ``` 1. Apri una finestra del terminale ed esegui il comando seguente: ``` pod install ``` Questo installa il componente API Gateway e altri componenti AWS Mobile SDK dipendenti. 1. Chiudi il progetto Xcode e apri il file `.xcworkspace` per riavviare Xcode. 1. Aggiungi tutti i file `.h` e `.m` dalla directory `generated-src` estratta dell'SDK nel progetto Xcode. ![\[I file .h e .m si trovano nella directory generated-src\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/use-sdk-in-ios-objc-project-add-sdk-src.png) *Per importare AWS Mobile SDK for iOS Objective-C nel tuo progetto scaricando esplicitamente AWS Mobile SDK o utilizzando [Carthage](https://github.com/Carthage/Carthage#installing-carthage), segui le istruzioni nel file README.md.* Assicurati di utilizzare solo una di queste opzioni per importare Mobile SDK. AWS ### Chiamata ai metodi API mediante l'SDK iOS generato da API Gateway in un progetto Objective-C Quando avete generato l'SDK con il prefisso di `SIMPLE_CALC` for questa [SimpleCalc API](simple-calc-lambda-api.md) con due modelli per l'input (`Input`) e l'output (`Result`) dei metodi, nell'SDK, la classe client API risultante diventa `SIMPLE_CALCSimpleCalcClient` e le classi di dati corrispondenti sono `SIMPLE_CALCInput` e, rispettivamente. `SIMPLE_CALCResult` Le richieste e le risposte API sono mappate ai metodi SDK come segue: + La richiesta API di ``` GET /?a=...&b=...&op=... ``` diventa il metodo SDK di ``` (AWSTask *)rootGet:(NSString *)op a:(NSString *)a b:(NSString *)b ``` La proprietà `AWSTask.result` è del tipo `SIMPLE_CALCResult`, se il modello `Result` è stato aggiunto alla risposta del metodo. In caso contrario, è del tipo `NSDictionary`. + Questa richiesta API di ``` POST / { "a": "Number", "b": "Number", "op": "String" } ``` diventa il metodo SDK di ``` (AWSTask *)rootPost:(SIMPLE_CALCInput *)body ``` + La richiesta API di ``` GET /{a}/{b}/{op} ``` diventa il metodo SDK di ``` (AWSTask *)aBOpGet:(NSString *)a b:(NSString *)b op:(NSString *)op ``` La procedura seguente descrive come chiamare i metodi API nel codice di origine delle app Objective-C, ad esempio nell'ambito del delegato `viewDidLoad` in un file `ViewController.m`. **Per chiamare l'API mediante l'SDK iOS generato da API Gateway** 1. Importa il file di intestazione della classe client dell'API per rendere tale classe chiamabile nell'app: ``` #import "SIMPLE_CALCSimpleCalc.h" ``` L'istruzione `#import` inoltre importa `SIMPLE_CALCInput.h` e `SIMPLE_CALCResult.h` per le due classi di modelli. 1. Crea un'istanza della classe client dell'API: ``` SIMPLE_CALCSimpleCalcClient *apiInstance = [SIMPLE_CALCSimpleCalcClient defaultClient]; ``` Per utilizzare Amazon Cognito con l'API, impostare la proprietà `defaultServiceConfiguration` sull'oggetto `AWSServiceManager` predefinito, come mostrato di seguito, prima di chiamare il metodo `defaultClient` per creare l'oggetto client dell'API (mostrato nell'esempio precedente): ``` AWSCognitoCredentialsProvider *creds = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1 identityPoolId:your_cognito_pool_id]; AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1 credentialsProvider:creds]; AWSServiceManager.defaultServiceManager.defaultServiceConfiguration = configuration; ``` 1. Chiama il metodo `GET /?a=1&b=2&op=+` per eseguire `1+2`: ``` [[apiInstance rootGet: @"+" a:@"1" b:@"2"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField1.text = [self handleApiResponse:task]; return nil; }]; ``` dove la funzione dell'helper `handleApiResponse:task` formatta il risultato come stringa da visualizzare in un campo di testo (`_textField1`). ``` - (NSString *)handleApiResponse:(AWSTask *)task { if (task.error != nil) { return [NSString stringWithFormat: @"Error: %@", task.error.description]; } else if (task.result != nil && [task.result isKindOfClass:[SIMPLE_CALCResult class]]) { return [NSString stringWithFormat:@"%@ %@ %@ = %@\n",task.result.input.a, task.result.input.op, task.result.input.b, task.result.output.c]; } return nil; } ``` Il risultato visualizzato è `1 + 2 = 3`. 1. Chiama `POST /` con un payload per eseguire `1-2`: ``` SIMPLE_CALCInput *input = [[SIMPLE_CALCInput alloc] init]; input.a = [NSNumber numberWithInt:1]; input.b = [NSNumber numberWithInt:2]; input.op = @"-"; [[apiInstance rootPost:input] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField2.text = [self handleApiResponse:task]; return nil; }]; ``` Il risultato visualizzato è `1 - 2 = -1`. 1. Chiama `GET /{a}/{b}/{op}` per eseguire `1/2`: ``` [[apiInstance aBOpGet:@"1" b:@"2" op:@"div"] continueWithBlock:^id _Nullable(AWSTask * _Nonnull task) { _textField3.text = [self handleApiResponse:task]; return nil; }]; ``` Il risultato visualizzato è `1 div 2 = 0.5`. Nell'esempio, `div` viene usato al posto di `/` perché la [funzione Lambda semplice](simple-calc-nodejs-lambda-function.md) nel back-end non gestisce le variabili di percorso con codifica URL. ## Utilizzo di un SDK iOS (Swift) generato per chiamare l'API Prima di iniziare la procedura seguente, devi completare le fasi descritte in [Genera SDKs per REST APIs in API Gateway](how-to-generate-sdk.md) per iOS in Swift e scaricare il file .zip dell'SDK generato. **Topics** + [Installa SDK AWS mobile e SDK generato da API Gateway in un progetto Swift](#use-sdk-ios-swift-install-sdk) + [Chiamata ai metodi API mediante l'SDK iOS generato da API Gateway in un progetto Swift](#use-sdk-ios-swift-call-api) ### Installa SDK AWS mobile e SDK generato da API Gateway in un progetto Swift La procedura seguente descrive come installare l'SDK. **Per installare e utilizzare un SDK iOS generato da API Gateway in Swift** 1. Estrai il contenuto del file .zip generato da API Gateway scaricato precedentemente. Utilizzando l'[SimpleCalc API](simple-calc-lambda-api.md), potresti voler rinominare la cartella SDK decompressa con qualcosa del genere. **sdk\$1swift\$1simple\$1calc** In questa cartella SDK sono presenti un file `README.md` e un file `Podfile`. Il file `README.md` contiene le istruzioni per installare e usare l'SDK. Questo tutorial fornisce i dettagli relativi alle istruzioni. L'installazione consente di importare i componenti Mobile [CocoaPods](https://cocoapods.org)SDK richiesti. AWS Devi aggiornare il file `Podfile` per importarli SDKs nel progetto Xcode della tua app Swift. La cartella SDK non archiviata contiene anche una cartella `generated-src` con il codice sorgente dell'SDK generato dell'API. 1. Avvia Xcode e crea un nuovo progetto Swift per iOS. Prendi nota della destinazione del progetto. Dovrai specificare questa impostazione nel `Podfile`. ![\[Trovare la destinazione in Xcode.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-find-target.png) 1. Per importare i componenti AWS Mobile SDK richiesti nel progetto Xcode utilizzando CocoaPods, procedi come segue: 1. Se non è installato, installalo CocoaPods eseguendo il seguente comando in una finestra di terminale: ``` sudo gem install cocoapods pod setup ``` 1. Copia il file `Podfile` dalla cartella SDK estratta nella stessa directory in cui si trova il file di progetto Xcode. Sostituisci il blocco seguente: ``` target '' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` con il nome di destinazione del progetto, come mostrato ``` target 'app_swift_simple_calc' do pod 'AWSAPIGateway', '~> 2.4.7' end ``` Se il progetto Xcode già contiene un `Podfile` con la destinazione corretta, puoi semplicemente aggiungere la riga di codice seguente al loop `do ... end`: ``` pod 'AWSAPIGateway', '~> 2.4.7' ``` 1. Apri una finestra del terminale ed esegui il comando seguente nella directory dell'app: ``` pod install ``` Questo installa il componente API Gateway e tutti i componenti AWS Mobile SDK dipendenti nel progetto dell'app. 1. Chiudi il progetto Xcode e apri il file `*.xcworkspace` per riavviare Xcode. 1. Aggiungi tutti i file di intestazione dell'SDK (`.h`) e i file del codice di origine Swift (`.swift`) dalla directory `generated-src` estratta nel progetto Xcode. ![\[I file .h e .swift si trovano nella directory generated-src\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-add-sdk-src.png) 1. Per abilitare la chiamata alle librerie Objective-C di AWS Mobile SDK dal tuo progetto di codice Swift, imposta il percorso del `Bridging_Header.h` file nella proprietà **Objective-C Bridging Header** sotto **Swift** Compiler - Impostazione generale della configurazione del tuo progetto Xcode: ![\[Impostare il percorso del file Bridging_Header.h in Compilatore Swift - Generale.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-bridging-header.png) **Suggerimento** È possibile digitare **bridging** nella casella di ricerca di Xcode per trovare la proprietà **Objective-C Bridging Header (Intestazione bridging Objective-C)**. 1. Prima di procedere, crea il progetto Xcode per verificare che sia configurato correttamente. Se il tuo Xcode utilizza una versione di Swift più recente di quella supportata per Mobile SDK, otterrai errori nel compilatore Swift. AWS In questo caso, impostare la proprietà **Use Legacy Swift Language Version (Usa versione linguaggio Swift legacy)** su **Yes (Sì)** in **Swift Compiler - Version (Compilatore Swift - Versione)**: ![\[Impostare la proprietà Versione linguaggio Swift legacy su Sì.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/use-sdk-in-ios-swift-project-set-legacy-swift-version.png) Per importare AWS Mobile SDK for iOS in Swift nel tuo progetto AWS scaricando esplicitamente Mobile SDK o [utilizzando](https://github.com/Carthage/Carthage#installing-carthage) Carthage, segui le istruzioni nel `README.md` file fornito con il pacchetto SDK. Assicurati di utilizzare solo una di queste opzioni per importare Mobile SDK. AWS ### Chiamata ai metodi API mediante l'SDK iOS generato da API Gateway in un progetto Swift Quando avete generato l'SDK con il prefisso di `SIMPLE_CALC` for questa [SimpleCalc API](simple-calc-lambda-api.md) con due modelli per descrivere l'input (`Input`) e l'output (`Result`) delle richieste e delle risposte dell'API, nell'SDK, la classe client API risultante diventa `SIMPLE_CALCSimpleCalcClient` e le classi di dati corrispondenti sono `SIMPLE_CALCInput` e, rispettivamente. `SIMPLE_CALCResult` Le richieste e le risposte API sono mappate ai metodi SDK come segue: + La richiesta API di ``` GET /?a=...&b=...&op=... ``` diventa il metodo SDK di ``` public func rootGet(op: String?, a: String?, b: String?) -> AWSTask ``` La proprietà `AWSTask.result` è del tipo `SIMPLE_CALCResult`, se il modello `Result` è stato aggiunto alla risposta del metodo. In caso contrario, è del tipo `NSDictionary`. + Questa richiesta API di ``` POST / { "a": "Number", "b": "Number", "op": "String" } ``` diventa il metodo SDK di ``` public func rootPost(body: SIMPLE_CALCInput) -> AWSTask ``` + La richiesta API di ``` GET /{a}/{b}/{op} ``` diventa il metodo SDK di ``` public func aBOpGet(a: String, b: String, op: String) -> AWSTask ``` La procedura seguente descrive come chiamare i metodi API nel codice di origine delle app Swift, ad esempio nell'ambito del delegato `viewDidLoad()` in un file `ViewController.m`. **Per chiamare l'API mediante l'SDK iOS generato da API Gateway** 1. Crea un'istanza della classe client dell'API: ``` let client = SIMPLE_CALCSimpleCalcClient.default() ``` Per utilizzare Amazon Cognito con l'API, imposta una configurazione di AWS servizio predefinita (mostrata di seguito) prima di ottenere il `default` metodo (mostrato in precedenza): ``` let credentialsProvider = AWSCognitoCredentialsProvider(regionType: AWSRegionType.USEast1, identityPoolId: "my_pool_id") let configuration = AWSServiceConfiguration(region: AWSRegionType.USEast1, credentialsProvider: credentialsProvider) AWSServiceManager.defaultServiceManager().defaultServiceConfiguration = configuration ``` 1. Chiama il metodo `GET /?a=1&b=2&op=+` per eseguire `1+2`: ``` client.rootGet("+", a: "1", b:"2").continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` dove la funzione dell'helper `self.showResult(task)` stampa il risultato o l'errore nella console, ad esempio: ``` func showResult(task: AWSTask) { if let error = task.error { print("Error: \(error)") } else if let result = task.result { if result is SIMPLE_CALCResult { let res = result as! SIMPLE_CALCResult print(String(format:"%@ %@ %@ = %@", res.input!.a!, res.input!.op!, res.input!.b!, res.output!.c!)) } else if result is NSDictionary { let res = result as! NSDictionary print("NSDictionary: \(res)") } } } ``` In un'app di produzione puoi visualizzare il risultato o l'errore in un campo di testo. Il risultato visualizzato è `1 + 2 = 3`. 1. Chiama `POST /` con un payload per eseguire `1-2`: ``` let body = SIMPLE_CALCInput() body.a=1 body.b=2 body.op="-" client.rootPost(body).continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` Il risultato visualizzato è `1 - 2 = -1`. 1. Chiama `GET /{a}/{b}/{op}` per eseguire `1/2`: ``` client.aBOpGet("1", b:"2", op:"div").continueWithBlock {(task: AWSTask) -> AnyObject? in self.showResult(task) return nil } ``` Il risultato visualizzato è `1 div 2 = 0.5`. Nell'esempio, `div` viene usato al posto di `/` perché la [funzione Lambda semplice](simple-calc-nodejs-lambda-function.md) nel back-end non gestisce le variabili di percorso con codifica URL. # Sviluppa REST APIs utilizzando OpenAPI in API Gateway Puoi utilizzare API Gateway per importare un'API REST da un file di definizione esterno in API Gateway. Attualmente, API Gateway supporta i file di definizione [v2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) e [OpenAPI v3.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.1.md) con le eccezioni elencate in [Note importanti su Amazon API Gateway per REST APIs](api-gateway-known-issues.md#api-gateway-known-issues-rest-apis). Puoi aggiornare un'API sovrascrivendola con una nuova definizione oppure puoi unire la definizione a quella di un'API esistente. Puoi specificare le opzioni utilizzando un parametro di query `mode` nell'URL di richiesta. Per un tutorial sull'utilizzo della caratteristica Importa API dalla console API Gateway, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Importazione di un'API ottimizzata per l'edge in API Gateway](import-edge-optimized-api.md) + [Importazione di un'API regionale in Gateway API](import-export-api-endpoints.md) + [Importazione di un file OpenAPI per aggiornare una definizione API esistente](api-gateway-import-api-update.md) + [Impostare la proprietà openAPI `basePath`](api-gateway-import-api-basePath.md) + [AWS variabili per l'importazione OpenAPI](import-api-aws-variables.md) + [Errori e avvisi relativi all'importazione dell'API in Gateway API](api-gateway-import-api-errors-warnings.md) + [Esportazione di un'API REST da API Gateway](api-gateway-export-api.md) # Importazione di un'API ottimizzata per l'edge in API Gateway Puoi importare un file di definizione OpenAPI dell'API per creare una nuova API ottimizzata per gli edge specificando il tipo di endpoint `EDGE` come input aggiuntivo, oltre al file OpenAPI, nell'operazione di importazione. Puoi farlo utilizzando la console API Gateway o un AWS SDK. AWS CLI Per un tutorial sull'utilizzo della caratteristica Importa API dalla console API Gateway, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Importazione di un'API ottimizzata per l'edge mediante la console API Gateway](#import-edge-optimized-api-with-console) + [Importa un'API ottimizzata per i dispositivi periferici utilizzando AWS CLI](#import-edge-optimized-api-with-awscli) ## Importazione di un'API ottimizzata per l'edge mediante la console API Gateway Per importare un'API ottimizzata per l'edge tramite la console API Gateway, procedi nel seguente modo: 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona **Create API** (Crea API). 1. In **API REST**, scegliere **Import (Importa)**. 1. Copia una definizione OpenAPI dell'API e incollala nell'editor di codice o seleziona **Scegli il file** per caricare un file OpenAPI da un'unità locale. 1. In **Tipo di endpoint**, scegli **Ottimizzato per gli edge**. 1. Scegli **Crea API** per iniziare a importare le definizioni OpenAPI. ## Importa un'API ottimizzata per i dispositivi periferici utilizzando AWS CLI Il [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)comando seguente importa un'API da un file di definizione OpenAPI per creare una nuova API ottimizzata per i bordi: ``` aws apigateway import-rest-api \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` oppure specificando esplicitamente il parametro della stringa di query `endpointConfigurationTypes` come `EDGE`: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=EDGE \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importazione di un'API regionale in Gateway API Quando importi un'API, puoi scegliere la configurazione dell'endpoint regionale per l'API. Puoi utilizzare la console API Gateway AWS CLI, o un AWS SDK. Quando esporti un'API, la configurazione dell'endpoint dell'API non è inclusa nelle definizioni dell'API esportate. Per un tutorial sull'utilizzo della caratteristica Importa API dalla console API Gateway, consulta [Tutorial: creazione di un'API REST mediante l'importazione di un esempio](api-gateway-create-api-from-example.md). **Topics** + [Importazione di un'API regionale tramite la console API Gateway](#import-regional-api-with-console) + [Importa un'API regionale utilizzando AWS CLI](#import-regional-api-with-awscli) ## Importazione di un'API regionale tramite la console API Gateway Per importare un'API di un endpoint regionale mediante la console API Gateway, procedi come indicato di seguito: 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Seleziona **Create API** (Crea API). 1. In **API REST**, scegliere **Import (Importa)**. 1. Copia una definizione OpenAPI dell'API e incollala nell'editor di codice o seleziona **Scegli il file** per caricare un file OpenAPI da un'unità locale. 1. In **Tipo di endpoint**, scegli**Regionale**. 1. Scegli **Crea API** per iniziare a importare le definizioni OpenAPI. ## Importa un'API regionale utilizzando AWS CLI Il [import-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/import-rest-api.html)comando seguente importa un file di definizione OpenAPI e imposta il tipo di endpoint su Regional: ``` aws apigateway import-rest-api \ --parameters endpointConfigurationTypes=REGIONAL \ --fail-on-warnings \ --body 'file://path/to/API_OpenAPI_template.json' ``` # Importazione di un file OpenAPI per aggiornare una definizione API esistente Puoi importare le definizioni API solo per aggiornare un'API esistente, senza cambiare la configurazione del suo endpoint, le fasi, le variabili di fase o i riferimenti alle chiavi API. L' import-to-updateoperazione può avvenire in due modalità: unione o sovrascrittura. Quando un'API (`A`) viene unita a un'altra (`B`), l'API risultante mantiene le definizioni di entrambe `A` e `B` se le due APIs non condividono definizioni in conflitto. Quando si verificano dei conflitti, le definizioni di metodo dell'API di unione (`A`) sostituisce le definizioni di metodo corrispondenti dell'API unita (`B`). Ad esempio, supponiamo che `B` abbia dichiarato i seguenti metodi per restituire le risposte `200` e `206`: ``` GET /a POST /a ``` e `A` dichiari il metodo seguente per restituire le risposte `200` e `400`: ``` GET /a ``` Quando `A` viene unita a `B`, l'API risultante produrrà i seguenti metodi: ``` GET /a ``` che restituisce le risposte `200` e `400` e ``` POST /a ``` che restituisce le risposte `200` e `206`. Unire un'API è utile quando hai scomposto le definizioni API esterne in molteplici parti più piccole e vuoi applicare le modifiche solo a una parte per volta. Ad esempio, questo può succedere se più team sono responsabili di parti diverse di un'API e hanno modifiche disponibili a tariffe diverse. In questo modo, gli item dell'API esistente che non vengono esplicitamente indicati nella definizione importata saranno tralasciati. Quando un'API (`A`) sovrascrive un'altra API (`B`), l'API risultante prende le definizioni dell'API di sovrascrittura (`A`). Sovrascrivere un'API è utile quando una definizione API esterna ne contiene la definizione completa. In questo modo, gli item dell'API esistente che non vengono esplicitamente indicati nella definizione importata saranno eliminati. Per unire un'API, invia una richiesta `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=merge`. Il valore del parametro percorso `restapi_id` specifica l'API con cui la definizione API fornita si unirà. Il seguente frammento di codice mostra un esempio della richiesta `PUT` di unione di una definizione API OpenAPI in JSON, come payload, con l'API specificata già presente in API Gateway. ``` PUT /restapis/?mode=merge Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` L'operazione di aggiornamento dell'unione consiste nell'unione di due definizioni API complete. Per una modifica piccola e incrementale, puoi utilizzare l'operazione di [aggiornamento risorsa](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateResource.html). Per sovrascrivere un'API, invia una richiesta `PUT` a `https://apigateway..amazonaws.com/restapis/?mode=overwrite`. Il parametro percorso `restapi_id` specifica l'API che verrà sovrascritta dalle definizioni API fornite. Il seguente frammento di codice mostra un esempio di richiesta di sovrascrittura con il payload di una definizione OpenAPI in formato JSON: ``` PUT /restapis/?mode=overwrite Host:apigateway..amazonaws.com Content-Type: application/json Content-Length: ... An OpenAPI API definition in JSON ``` Se il parametro di query `mode` non viene specificato, si procede con l'unione. **Nota** Le operazioni `PUT` sono idempotenti, ma non atomiche. Ciò significa che se si verifica un errore prima della fine dell'elaborazione, l'API può risultare in uno stato non valido. Tuttavia, ripetendo l'operazione con successo, l'API potrà essere nello stesso stato finale che avrebbe avuto se la prima operazione fosse riuscita. # Impostare la proprietà openAPI `basePath` In [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md) è possibile usare la proprietà `basePath` per specificare una o più parti di percorso che precedono ogni percorso definito nella proprietà `paths`. Poiché API Gateway include diversi modi per esprimere il percorso di una risorsa, la caratteristica Importa API offre queste opzioni per interpretare la proprietà `basePath` durante l'importazione: ignore, prepend e split. In [https://swagger.io/docs/specification/api-host-and-base-path/](https://swagger.io/docs/specification/api-host-and-base-path/) `basePath` non è più una proprietà di primo livello. Al contrario, API Gateway usa una [variabile server](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#serverVariableObject) come convenzione. La funzionalità Import API (Importa API) offre le stesse opzioni per interpretare il percorso di base durante l'importazione. Il percorso di base può essere identificato in questo modo: + Se l'API non contiene variabili `basePath`, la funzionalità Import API (Importa API) controlla la stringa `server.url` per verificare se contiene un percorso dopo `"/"`. Se sì, il percorso viene usato come percorso di base. + Se l'API contiene solo una variabile `basePath`, la funzionalità Import API (Importa API) la usa come percorso di base, anche se alla variabile non viene fatto riferimento in `server.url`. + Se l'API contiene più variabili `basePath`, la funzionalità Import API (Importa API) usa solo la prima come percorso di base. ## Ignorare Se nel file OpenAPI il valore di `basePath` è `/a/b/c` e la proprietà `paths` contiene `/e` e `/f`, la richiesta `POST` o `PUT` seguente: ``` POST /restapis?mode=import&basepath=ignore ``` ``` PUT /restapis/api_id?basepath=ignore ``` porterà le seguenti risorse nell'API: + `/` + `/e` + `/f` Il punto è trattare il `basePath` come se non fosse presente e tutte le risorse API dichiarate vengono servite in relazione all'host. Questo può essere utile, ad esempio, quando hai un nome di dominio personalizzato con una mappatura API che non include un *Percorso di base* e un valore della *Fase* che si riferisce alla fase di produzione. **Nota** API Gateway creerà automaticamente una risorsa root, anche se non è stato dichiarato in modo esplicito nel file di definizione. In assenza di specifiche, `basePath` seleziona `ignore` per impostazione predefinita. ## Metti come prefisso Se nel file OpenAPI il valore di `basePath` è `/a/b/c` e la proprietà `paths` contiene `/e` e `/f`, la richiesta `POST` o `PUT` seguente: ``` POST /restapis?mode=import&basepath=prepend ``` ``` PUT /restapis/api_id?basepath=prepend ``` porterà le seguenti risorse nell'API: + `/` + `/a` + `/a/b` + `/a/b/c` + `/a/b/c/e` + `/a/b/c/f` L'effetto è trattare il `basePath` come se specificasse risorse aggiuntive (senza metodo) e aggiungerle al set di risorse dichiarato. Questo può essere utile, ad esempio, quando team diversi sono responsabili di parti diverse di un'API e il `basePath` potrebbe riferirsi al percorso della parte dell'API di ogni team. **Nota** API Gateway creerà automaticamente le risorse intermedie, anche se non sono dichiarate in modo esplicito nella definizione. ## Split Se nel file OpenAPI il valore di `basePath` è `/a/b/c` e la proprietà `paths` contiene `/e` e `/f`, la richiesta `POST` o `PUT` seguente: ``` POST /restapis?mode=import&basepath=split ``` ``` PUT /restapis/api_id?basepath=split ``` porterà le seguenti risorse nell'API: + `/` + `/b` + `/b/c` + `/b/c/e` + `/b/c/f` L'effetto è trattare la parte più alta del percorso, `/a`, come l'inizio del percorso di ogni risorsa e creare risorse aggiuntive (senza metodo) all'interno dell'API stessa. Questo potrebbe, ad esempio, essere utilizzato quando `a` è il nome di una fase che vuoi esporre come parte dell'API. # AWS variabili per l'importazione OpenAPI È possibile utilizzare le seguenti AWS variabili nelle definizioni OpenAPI. API Gateway risolve le variabili quando l'API viene importata. Per specificare una variabile, utilizzare `${variable-name}`. La tabella seguente descrive le AWS variabili disponibili. | Nome della variabile | Description | | --- | --- | | AWS::AccountId | L'ID AWS dell'account che importa l'API. Ad esempio, 123456789012. | | AWS::Partition | La AWS partizione in cui viene importata l'API. Per le AWS regioni standard, la partizione è. aws | | AWS::Region | La AWS regione in cui viene importata l'API. Ad esempio, us-east-2. | ## AWS esempio di variabili L'esempio seguente utilizza AWS le variabili per specificare una AWS Lambda funzione per un'integrazione. ------ #### [ OpenAPI 3.0 ] ``` openapi: "3.0.1" info: title: "tasks-api" version: "v1.0" paths: /: get: summary: List tasks description: Returns a list of tasks responses: 200: description: "OK" content: application/json: schema: type: array items: $ref: "#/components/schemas/Task" 500: description: "Internal Server Error" content: {} x-amazon-apigateway-integration: uri: arn:${AWS::Partition}:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:${AWS::Partition}:lambda:${AWS::Region}:${AWS::AccountId}:function:LambdaFunctionName/invocations responses: default: statusCode: "200" passthroughBehavior: "when_no_match" httpMethod: "POST" contentHandling: "CONVERT_TO_TEXT" type: "aws_proxy" components: schemas: Task: type: object properties: id: type: integer name: type: string description: type: string ``` ------ # Errori e avvisi relativi all'importazione dell'API in Gateway API Quando si importa il file di definizione esterno in Gateway API è possibile che vengano generati avvisi ed errori. Nelle sezioni seguenti vengono descritti gli errori e gli avvisi che possono essere restituiti durante l'importazione. ## Errori durante l'importazione Nel corso dell'importazione, possono essere generati errori per problematiche rilevanti come nel caso di un documento OpenAPI non valido. Gli errori vengono restituiti come eccezioni (ad esempio, `BadRequestException`) in una risposta non andata a buon fine. Quando si verifica un errore, la nuova definizione dell'API viene scartata e all'API esistente non viene apportata alcuna modifica. ## Avvisi durante l'importazione Nel corso dell'importazione, gli avvisi possono essere generati per problematiche minori come nel caso di un riferimento mancante a un modello. In presenza di un avviso, l'operazione proseguirà se l'espressione di query `failonwarnings=false` viene aggiunta all'URL della richiesta. In caso contrario, gli aggiornamenti verranno ripristinati. Per impostazione predefinita, `failonwarnings` è impostato su `false`. In questi casi, gli avvisi vengono restituiti come campo nella [RestApi](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html)risorsa risultante. In caso contrario, gli avvisi vengono restituiti come messaggio nell'eccezione. # Esportazione di un'API REST da API Gateway Dopo aver creato e configurato un'API REST in API Gateway tramite la console API Gateway o in un altro modo, puoi esportarla in un file OpenAPI usando l'API di esportazione di API Gateway integrata nel servizio di controllo di Amazon API Gateway. Per utilizzare l'API di Gateway Amazon API, è necessario firmare le richieste API. Per ulteriori informazioni sulla firma delle richieste, consulta [Signing AWS API requests](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) nella *IAM User Guide*. Puoi scegliere di includere le estensioni di integrazione di API Gateway, nonché le estensioni [Postman](https://www.postman.com), nel file di definizione OpenAPI esportato. **Nota** Quando esporti l'API utilizzando il AWS CLI, assicurati di includere il parametro extensions come mostrato nell'esempio seguente, per assicurarti che l'`x-amazon-apigateway-request-validator`estensione sia inclusa: ``` aws apigateway get-export --parameters extensions='apigateway' --rest-api-id abcdefg123 --stage-name dev --export-type swagger latestswagger2.json ``` Non puoi esportare un'API se i suoi payload non sono di tipo `application/json`. Se ci provi, verrà restituita una risposta di errore che indica che non è stato possibile trovare i modelli di corpo JSON. ## Richiesta di esportazione di un'API REST Con l'API Export, puoi esportare un'API REST esistente inviando una richiesta GET, specificando l' to-be-exportedAPI come parte dei percorsi URL. L'URL della richiesta ha il formato seguente: ------ #### [ OpenAPI 3.0 ] ``` https:///restapis//stages//exports/oas30 ``` ------ #### [ OpenAPI 2.0 ] ``` https:///restapis//stages//exports/swagger ``` ------ Puoi aggiungere la stringa di query `extensions` per specificare se includere le estensioni API Gateway (con il valore `integration`) o le estensioni Postman (con il valore `postman`). Inoltre, puoi impostare l'intestazione `Accept` su `application/json` o `application/yaml` per ricevere l'output della definizione API rispettivamente in formato JSON o YAML. Per ulteriori informazioni sull'invio di richieste GET utilizzando l'API API Gateway Export, vedere [GetExport](https://docs.aws.amazon.com/apigateway/latest/api/API_GetExport.html). **Nota** Se definisci modelli nell'API, questi devono essere per il tipo di contenuto "application/json" perché API Gateway possa esportare il modello. In caso contrario, API Gateway genera un'eccezione con un messaggio di errore che indica che sono stati trovati solo modelli di corpo non JSON. I modelli devono contenere proprietà o essere definiti come un JSONSchema tipo particolare. ## Download della definizione OpenAPI dell'API REST in JSON Per esportare e scaricare un'API REST nelle definizioni OpenAPI in formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/json ``` ------ Qui `` può essere, ad esempio, `us-east-1`. Per l'elenco di tutte le Regioni in cui Gateway API è disponibile, consulta [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#apigateway_region). ## Download della definizione OpenAPI dell'API REST in YAML Per esportare e scaricare un'API REST nelle definizioni OpenAPI in formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30 Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Download della definizione OpenAPI dell'API REST con estensioni Postman in JSON Per esportare e scaricare un'API REST nelle definizioni OpenAPI con Postman in formato JSON: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=postman Host: apigateway..amazonaws.com Accept: application/json ``` ------ ## Download della definizione OpenAPI dell'API REST con l'integrazione di API Gateway in YAML Per esportare e scaricare un'API REST nelle definizioni OpenAPI con l'integrazione di API Gateway in formato YAML: ------ #### [ OpenAPI 3.0 ] ``` GET /restapis//stages//exports/oas30?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ #### [ OpenAPI 2.0 ] ``` GET /restapis//stages//exports/swagger?extensions=integrations Host: apigateway..amazonaws.com Accept: application/yaml ``` ------ ## Esportazione di un'API REST tramite la console API Gateway Dopo aver [distribuito l'API REST in una fase](set-up-deployments.md#create-deployment), puoi procedere all'esportazione dell'API nella fase in un file OpenAPI usando la console API Gateway. Nel riquadro **Fasi** della console Gateway API, scegli **Operazioni fase**, **Esporta**. ![\[Esportazione di un'API REST tramite la console API Gateway\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/export-new-console.png) Specifica un valore in **Tipo di specifica API**, **Formato** ed **Estensioni** per scaricare la definizione OpenAPI dell'API.