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à. # Ottimizzazione delle prestazioni di REST APIs Dopo aver reso disponibile la tua API per essere chiamata, potrebbe essere necessario ottimizzarla per renderla più reattività. API Gateway fornisce alcune strategie per ottimizzare l'API, come il caching delle risposte e la compressione del payload. In questa sezione viene descritto come abilitare queste funzionalità. **Topics** + [Impostazioni della cache per REST APIs in API Gateway](api-gateway-caching.md) + [Compressione del payload per REST APIs in API Gateway](api-gateway-gzip-compression-decompression.md) # Impostazioni della cache per REST APIs in API Gateway Puoi abilitare il caching delle API in Gateway API per memorizzare nella cache le risposte dell'endpoint. Con il caching, è possibile ridurre il numero di chiamate effettuate all'endpoint e migliorare la latenza delle richieste all'API. Quando abiliti la memorizzazione nella cache per una fase, API Gateway memorizza nella cache le risposte dall'endpoint per un periodo specificato time-to-live (TTL), in secondi. Per rispondere alla richiesta, API Gateway ricerca la risposta dell'endpoint nella cache anziché effettuare una richiesta all'endpoint. Il valore predefinito di TTL per il caching dell'API è 300 secondi. Il valore massimo di TTL è 3600 secondi. TTL=0 indica che il caching è disabilitato. **Nota** Il caching è il miglior tentativo. Puoi utilizzare le `CacheMissCount` metriche `CacheHitCount` e in Amazon CloudWatch per monitorare le richieste che API Gateway fornisce dalla cache delle API. La dimensione massima di una risposta che può essere memorizzata nella cache è 1048576 byte. la crittografia dei dati della cache può aumentare le dimensioni della risposta quando viene memorizzata nella cache. Questo è un servizio idoneo ai fini HIPAA. [Per ulteriori informazioni sull' AWS U.S. Health Insurance Portability and Accountability Act del 1996 (HIPAA) e sull'utilizzo AWS dei servizi per elaborare, archiviare e trasmettere informazioni sanitarie protette (PHI), vedere Panoramica HIPAA.](https://aws.amazon.com/compliance/hipaa-compliance/) **Importante** Quando abiliti il caching per una fase, il sistema di caching sarà abilitato per impostazione predefinita solo per i metodi `GET`. Ciò consente di garantire la sicurezza e la disponibilità dell'API. Puoi abilitare il caching per altri metodi [ignorando le impostazioni del metodo](#override-api-gateway-stage-cache-for-method-cache). **Importante** Per il caching viene applicato un addebito orario in base alle dimensioni della cache selezionata. Il caching non è idoneo per il piano gratuito. AWS Per ulteriori informazioni, consulta [Prezzi di API Gateway](https://aws.amazon.com/api-gateway/pricing/). ## Abilitazione del caching di Amazon API Gateway In Gateway API è possibile abilitare il caching per una fase specifica. Quando abiliti il caching, devi scegliere una capacità di cache. In generale, una capacità più ampia garantisce prestazioni migliori ma comporta costi più alti. Per le dimensioni della cache supportate, [cacheClusterSize](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateStage.html#apigw-CreateStage-request-cacheClusterSize)consulta l'*API Gateway API Reference*. Il caching in API Gateway è consentito mediante la creazione di un'istanza di cache dedicata. Questo processo può richiedere fino a 4 minuti. La capacità di caching può essere modificata in API Gateway rimuovendo l'istanza di cache esistente e creandone una nuova con una capacità modificata. Tutti i dati esistenti memorizzati nella cache vengono eliminati. **Nota** La capacità della cache influisce sulla CPU, sulla memoria e sulla larghezza di banda della rete dell'istanza della cache. Di conseguenza, la capacità della cache può influire sulle prestazioni della cache. API Gateway consiglia di eseguire un test di caricamento di 10 minuti per verificare che la capacità della cache sia appropriata per il carico di lavoro. Assicurati che il traffico durante il test di carico rispecchi il traffico di produzione. Ad esempio, includi un aumento graduale, un traffico costante e picchi di traffico. Il test di caricamento deve includere risposte che possono essere fornite dalla cache, nonché risposte univoche che aggiungono elementi alla cache. Durante il test di caricamento, monitora i parametri di latenza, 4xx, 5xx, hit della cache e mancato riscontro nella cache. In base a questi parametri, regola la capacità della cache a seconda delle esigenze. Per ulteriori informazioni sul test di carico, consulta [Come faccio a selezionare la migliore capacità di Amazon API Gateway Cache per evitare di raggiungere un limite di velocità?](https://repost.aws/knowledge-center/api-gateway-cache-capacity). ------ #### [ Console di gestione AWS ] Nella console Gateway API, è possibile configurare il caching nella pagina **Fasi**. Viene effettuato il provisioning della cache della fase desiderata e specificata un'impostazione di cache predefinita a livello di metodo. Attivando la cache predefinita a livello di metodo, il caching a livello di metodo viene attivato per tutti i metodi `GET` nella fase, a meno che il metodo in questione non disponga di una sostituzione dedicata. Tutti i metodi `GET` aggiuntivi che implementi nella fase disporranno di una cache a livello di metodo. Per configurare l'impostazione del caching a livello di metodo per metodi specifici nella fase, è possibile utilizzare le sostituzioni dei metodi. Per ulteriori informazioni sulle sostituzioni dei metodi, consulta [Sostituzione del caching a livello di fase di Gateway API per il caching a livello di metodo](#override-api-gateway-stage-cache-for-method-cache). **Per configurare il caching dell'API per una fase specifica:** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere **Stages (Fasi)**. 1. Nell'elenco **Stages (Fasi)** dell'API, selezionare la fase. 1. Nella sezione **Dettagli fase** scegli **Modifica**. 1. In **Impostazioni aggiuntive**, per **Impostazioni cache** attiva **Cache API con provisioning**. In questo modo viene effettuato il provisioning di un cluster di cache per la fase. 1. Per attivare il caching per la fase, attiva **Memorizzazione nella cache predefinita a livello di metodo**. In questo modo viene attivato il caching a livello di metodo per tutti i metodi `GET` nella fase. Tutti i metodi `GET` aggiuntivi che implementi nella fase disporranno di una cache a livello di metodo. **Nota** Se hai un'impostazione esistente per una cache a livello di metodo, la modifica dell'impostazione del caching predefinito a livello di metodo non influisce sull'impostazione esistente. ![\[Attiva la cache API con provisioning e il caching predefinito a livello di metodo.\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-caching-stage-flow.png) 1. Scegli **Save changes** (Salva modifiche). ------ #### [ AWS CLI ] Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente aggiorna una fase per allocare una cache e attiva il caching a livello di metodo per tutti i metodi `GET` della fase: ``` aws apigateway update-stage \ --rest-api-id a1b2c3 \ --stage-name 'prod' \ --patch-operations file://patch.json ``` Il contenuto di `patch.json` è il seguente: ``` [ { "op": "replace", "path": "/cacheClusterEnabled", "value": "true" }, { "op": "replace", "path": "/cacheClusterSize", "value": "0.5" }, { "op": "replace", "path": "/*/*/caching/enabled", "value": "true" } ] ``` **Nota** Se hai un'impostazione esistente per una cache a livello di metodo, la modifica dell'impostazione del caching predefinito a livello di metodo non influisce sull'impostazione esistente. ------ **Nota** Per completare la creazione o l'eliminazione di una cache, API Gateway impiega circa 4 minuti. Una volta creata la cache, il valore **Cluster di cache** cambia da `Create in progress` a `Active`. Quando invece viene completata l'eliminazione della cache, il valore **Cluster di cache** cambia da `Delete in progress` a `Inactive`. Quando attivi il caching a livello di metodo per tutti i metodi della fase, il valore **Memorizzazione nella cache predefinita a livello di metodo** cambia in `Active`. Se disattivi il caching a livello di metodo per tutti i metodi della fase, il valore **Memorizzazione nella cache predefinita a livello di metodo** cambia in `Inactive`. Se hai un'impostazione esistente per una cache a livello di metodo, la modifica dello stato della cache non influisce su tale impostazione. Se abiliti il caching in **Impostazioni cache** di una fase, vengono memorizzati nella cache solo i metodi `GET`. Per garantire la sicurezza e la disponibilità dell'API, ti consigliamo di non modificare questa impostazione. Tuttavia, puoi abilitare il caching per altri metodi [ignorando le impostazioni del metodo](#override-api-gateway-stage-cache-for-method-cache). Puoi verificare che il caching funzioni come previsto in due modi: + Ispeziona le CloudWatch metriche di e per la tua API **CacheHitCount**e il tuo stage **CacheMissCount**. + Inserisci un timestamp nella risposta. **Nota** Non utilizzare l'`X-Cache`intestazione della CloudFront risposta per determinare se l'API viene fornita dall'istanza della cache di API Gateway. ## Sostituzione del caching a livello di fase di Gateway API per il caching a livello di metodo Puoi ignorare le impostazioni della cache a livello di fase attivando o disattivando il caching per un metodo specifico. È possibile anche modificare il periodo TTL oppure attivare o disattivare la crittografia per le risposte memorizzate nella cache. Se si prevede che nelle risposte di un metodo che si sta memorizzando nella cache siano inclusi dati sensibili, crittografare i dati della cache. Potrebbe essere necessario eseguire questa operazione per rispettare vari framework di conformità. Per ulteriori informazioni, consultare [Amazon API Gateway controls](https://docs.aws.amazon.com/securityhub/latest/userguide/apigateway-controls.html) nella *Guida per l’utente di AWS Security Hub *. ------ #### [ Console di gestione AWS ] La modifica dell'impostazione del caching predefinito a livello di metodo nei **dettagli della fase** non influisce sulle impostazioni della cache a livello di metodo che dispongono di sostituzioni. Se prevedi che nelle risposte di un metodo che si sta memorizzando nella cache siano inclusi dati sensibili, in **Cache Settings (Impostazioni cache)**, scegliere **Encrypt cache data (Crittografa dati cache)**. **Per configurare il caching dell'API per i singoli metodi utilizzando la console:** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Selezionare l'API. 1. Scegliere **Stages (Fasi)**. 1. Nell'elenco **Stages (Fasi)** dell'API, espandere la fase e scegliere un metodo nell'API. 1. Nella sezione **Sostituzioni del metodo**, scegli **Modifica**. 1. Nella sezione **Impostazioni metodo**, attiva o disattiva **Abilita cache metodo** o personalizza le altre opzioni desiderate. **Nota** Il caching non è attivo finché non si effettua il provisioning di un cluster di cache per la fase. 1. Scegli **Save** (Salva). ------ #### [ AWS CLI ] Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente disattiva la cache solo per il metodo `GET /pets`: ``` aws apigateway update-stage / --rest-api-id a1b2c3 / --stage-name 'prod' / --patch-operations file://patch.json ``` Il contenuto di `patch.json` è il seguente: ``` [{ "op": "replace", "path": "/~1pets/GET/caching/enabled", "value": "false" }] ``` ------ ## Uso dei parametri di metodo o di integrazione come chiavi di cache per indicizzare le risposte memorizzate nella cache Puoi utilizzare parametri di metodo o di integrazione come chiavi di cache per indicizzare le risposte memorizzate nella cache Sono inclusi: intestazioni personalizzate, percorsi URL o stringhe di query. È possibile specificare alcuni o tutti i parametri come chiave di cache, ma è necessario specificare almeno un valore. Se disponi di una chiave di cache, Gateway API memorizza nella cache le risposte di ciascun valore di chiave separatamente, anche quando la chiave di cache non è presente. **Nota** Le chiavi di cache sono necessarie per la configurazione del caching su una risorsa. Ad esempio, supponiamo di avere una richiesta espressa nel seguente formato: ``` GET /users?type=... HTTP/1.1 host: example.com ... ``` In questa richiesta `type` può assumere il valore `admin` o `regular`. Se includi il parametro `type` come parte della chiave di cache, le risposte da `GET /users?type=admin` vengono memorizzate nella cache separatamente da quelle di `GET /users?type=regular`. Quando una richiesta di metodo o di integrazione usa più di un parametro, puoi scegliere di includere alcuni di essi o tutti per creare la chiave di cache. Ad esempio puoi includere solo il parametro `type` nella chiave di cache per la richiesta seguente, eseguita nell'ordine elencato in un periodo TTL: ``` GET /users?type=admin&department=A HTTP/1.1 host: example.com ... ``` La risposta da questa richiesta viene memorizzata nella cache e utilizzata per servire la seguente richiesta: ``` GET /users?type=admin&department=B HTTP/1.1 host: example.com ... ``` ------ #### [ Console di gestione AWS ] Per includere un parametro della richiesta di metodo o di integrazione in una chiave di cache nella console API Gateway, seleziona **Caching** dopo avere aggiunto il parametro. ![\[Inclusione dei parametri di metodo o di integrazione come chiavi di cache per indicizzare la risposta memorizzata nella cache\]](http://docs.aws.amazon.com/it_it/apigateway/latest/developerguide/images/api-caching-including-parameter-as-cache-key-new-console.png) ------ #### [ AWS CLI ] Il comando [put-method](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-method.html) seguente crea un metodo `GET` e richiede il parametro della stringa di query `type`: ``` aws apigateway put-method / --rest-api-id a1b2c3 / --resource-id aaa111 / --http-method GET / --authorization-type "NONE" / --request-parameters "method.request.querystring.type=true" ``` Il comando [put-integration](https://docs.aws.amazon.com/cli/latest/reference/apigateway/put-integration.html) seguente crea un’integrazione per il metodo `GET` con un endpoint HTTP e specifica che Gateway API memorizza nella cache il parametro della richiesta di metodo `type`. ``` aws apigateway put-integration / --rest-api-id a1b2c3 / --resource-id aaa111 / --http-method GET / --type HTTP / --integration-http-method GET / --uri 'https://example.com' / --cache-key-parameters "method.request.querystring.type" ``` Per specificare che Gateway API memorizzi nella cache un parametro della richiesta di integrazione, utilizzare `integration.request.location.name` come parametro della chiave di cache. ------ ## Scaricare la cache della fase API in API Gateway Quando il caching dell'API è abilitato, puoi scaricare la cache della fase API per garantire che i client dell'API ricevano le risposte più recenti dagli endpoint di integrazione. ------ #### [ Console di gestione AWS ] **Per svuotare la cache della fase 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 che abbia una fase con una cache. 1. Nel riquadro di navigazione principale scegliere **Fasi**, quindi scegliere una fase con una cache. 1. Scegliere il menu **Operazioni fase**, quindi selezionare **Svuota cache della fase**. ------ #### [ AWS CLI ] Il [flush-stage-cache](https://docs.aws.amazon.com/cli/latest/reference/apigateway/flush-stage-cache.html)comando seguente svuota la cache dello stage: ``` aws apigateway flush-stage-cache \ --rest-api-id a1b2c3 \ --stage-name prod ``` ------ **Nota** Una volta scaricata la cache, le risposte vengono servite dall'endpoint di integrazione fino a quando la cache non viene creata nuovamente. Durante questo periodo, il numero di richieste inviate all'endpoint di integrazione potrebbe aumentare. L'operazione potrebbe aumentare temporaneamente la latenza complessiva delle API. ## Invalidare una voce della cache di API Gateway Un client dell'API può invalidare una voce cache esistente e ricaricarla dall'endpoint di integrazione per le singole richieste. Il client deve inviare una richiesta contenente l'intestazione `Cache-Control: max-age=0`. Il client riceve la risposta direttamente dall'endpoint di integrazione anziché dalla cache, a condizione che il client sia autorizzato a eseguire questa operazione. In questo modo, la voce di cache esistente viene sostituita con la nuova risposta recuperata dall'endpoint di integrazione. Per concedere l'autorizzazione per un client, collegare una policy del formato seguente a un ruolo di esecuzione IAM per l'utente. **Nota** La convalida della cache tra più account non è supportata. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:InvalidateCache" ], "Resource": [ "arn:aws:execute-api:us-east-1:111111111111:api-id/stage-name/GET/resource-path-specifier" ] } ] } ``` ------ Questa policy consente al servizio di esecuzione API Gateway di invalidare la cache per le richieste nella risorsa o nelle risorse specificate. Per specificare un gruppo di risorse di destinazione, usa un carattere jolly (\$1) per `account-id`, `api-id` e altre voci nel valore ARN di `Resource`. Per ulteriori informazioni su come impostare le autorizzazioni per il servizio di esecuzione API Gateway, consulta [Controllo degli accessi a una REST API con le autorizzazioni IAM](permissions.md). Se non imponi una policy `InvalidateCache` (o scegli la casella di controllo **Require authorization (Richiedi autorizzazione)** nella console), qualsiasi client può invalidare la cache di API. Se tutti i client o la maggior parte di essi invalidano la cache dell'API, si potrebbe avere un aumento significativo sulla latenza dell'API. Quando la policy è attiva, il caching è abilitato e l'autorizzazione è richiesta. È possibile specificare il modo in cui Gateway API gestisce le richieste non autorizzate scegliendo tra le seguenti opzioni: **Col codice stato 403 la richiesta ha esito negativo** Gateway API restituisce una risposta `403 Unauthorized`. Per impostare questa opzione utilizzando l'API, usa `FAIL_WITH_403`. **Ignora intestazione controllo cache, aggiungi un avviso nell’intestazione della risposta** Gateway API elabora la richiesta e aggiunge un’intestazione di avviso nella risposta. Per impostare questa opzione utilizzando l'API, usa `SUCCEED_WITH_RESPONSE_HEADER`. **Ignora intestazione controllo cache** Gateway API elabora la richiesta senza aggiungere un’intestazione di avviso nella risposta. Per impostare questa opzione utilizzando l'API, usa `SUCCEED_WITHOUT_RESPONSE_HEADER`. È possibile impostare il comportamento di gestione delle richieste non autorizzate tramite la console Gateway API o AWS CLI. ------ #### [ Console di gestione AWS ] **Per specificare come vengono gestite le richieste non autorizzate** 1. Accedi alla console API Gateway all'indirizzo [https://console.aws.amazon.com/apigateway.](https://console.aws.amazon.com/apigateway) 1. Scegliere un’API che abbia una fase con una cache. 1. Nel riquadro di navigazione principale scegliere **Fasi**, quindi scegliere una fase con una cache. 1. Per **Dettagli fase**, scegliere **Modifica**. 1. Per **Gestione delle richieste non autorizzate**, selezionare un’opzione. 1. Scegli **Continua**. 1. Esamina le modifiche e scegli **Salva modifiche**. ------ #### [ AWS CLI ] Il comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) seguente aggiorna una fase per gestire le richieste non autorizzate con esito negativo della richiesta e codice di stato 403: ``` aws apigateway update-stage / --rest-api-id a1b2c3 / --stage-name 'prod' / --patch-operations 'op=replace,path=/*/*/caching/unauthorizedCacheControlHeaderStrategy,value="FAIL_WITH_403"' ``` ------ ## CloudFormation esempio di stage con cache Il CloudFormation modello seguente crea un'API di esempio, fornisce una cache `0.5` da GB per lo `Prod` stage e attiva la memorizzazione nella cache a livello di metodo per tutti i metodi. `GET` **Importante** Per il caching viene applicato un addebito orario in base alle dimensioni della cache selezionata. Il caching non rientra nel piano gratuito di AWS . Per ulteriori informazioni, consulta [Prezzi di API Gateway](https://aws.amazon.com/api-gateway/pricing/). ### CloudFormation Modello di esempio ``` AWSTemplateFormatVersion: 2010-09-09 Resources: Api: Type: 'AWS::ApiGateway::RestApi' Properties: Name: cache-example 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: true AuthorizationType: NONE Integration: Type: HTTP_PROXY IntegrationHttpMethod: GET Uri: http://petstore-demo-endpoint.execute-api.com/petstore/pets/ ApiDeployment: Type: 'AWS::ApiGateway::Deployment' DependsOn: - PetsMethodGet Properties: RestApiId: !Ref Api ApiStage: Type: 'AWS::ApiGateway::Stage' Properties: StageName: Prod Description: Prod Stage with a cache RestApiId: !Ref Api DeploymentId: !Ref ApiDeployment CacheClusterEnabled: True CacheClusterSize: 0.5 MethodSettings: - ResourcePath: /* HttpMethod: '*' CachingEnabled: True ``` # Compressione del payload per REST APIs in API Gateway API Gateway permette al client di chiamare l'API con payload compressi usando una delle [codifiche di contenuto supportate](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Per impostazione predefinita, API Gateway supporta la decompressione del payload di richiesta del metodo. È tuttavia necessario configurare l'API per abilitare la compressione del payload di risposta del metodo. Per abilitare la compressione in un'[https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html), imposta la proprietà [https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize](https://docs.aws.amazon.com/apigateway/latest/api/API_RestApi.html#minimumCompressionSize) su un valore intero non negativo compreso tra 0 e 10485760 (10 milioni di byte) quando crei l'API oppure dopo averla creata. Per disabilitare la compressione nell'API, imposta la proprietà `minimumCompressionSize` su null oppure rimuovila. È possibile abilitare o disabilitare la compressione per un'API utilizzando la console API Gateway AWS CLI, o l'API REST di API Gateway. Se desideri che la compressione venga applicata a payload di qualsiasi dimensione, imposta il valore di `minimumCompressionSize` su zero. La compressione di dati di piccole dimensioni può tuttavia comportare un aumento della dimensione finale dei dati. La compressione in API Gateway e la decompressione nel client possono inoltre comportare un aumento della latenza globale e richiedere tempi di elaborazione maggiori. Esegui test case sull'API per determinare un valore ottimale. Il client può inviare una richiesta API con un payload compresso e un'intestazione `Content-Encoding` appropriata per consentire a Gateway API di decomprimere e applicare i modelli di mappatura appropriati prima di passare la richiesta all'endpoint di integrazione. Dopo che la compressione è stata abilitata e l'API distribuita, il client può ricevere una risposta API con un payload compresso se specifica un'intestazione `Accept-Encoding` appropriata nella richiesta del metodo. Quando l'endpoint di integrazione prevede e restituisce payload JSON non compressi, un modello di mappatura configurato per un payload JSON non compresso è applicabile al payload compresso. Per un payload di richiesta del metodo compresso, API Gateway decomprime il payload, applica il modello di mappatura e passa la richiesta mappata all'endpoint di integrazione. Per un payload di risposta di integrazione non compresso, API Gateway applica il modello di mappatura, comprime il payload mappato e restituisce il payload compresso al client. **Topics** + [Abilitazione della compressione del payload per un'API in Gateway API](api-gateway-enable-compression.md) + [Chiamata di un metodo API con un payload compresso in Gateway API](api-gateway-make-request-with-compressed-payload.md) + [Ricezione di una risposta API con un payload compresso in Gateway API](api-gateway-receive-response-with-compressed-payload.md) # Abilitazione della compressione del payload per un'API in Gateway API Puoi abilitare la compressione per un'API utilizzando la console API Gateway AWS CLI, o un AWS SDK. Per un'API esistente, dopo aver abilitato la compressione, è necessario distribuire l'API per rendere effettiva la modifica. Per una nuova API, puoi distribuirla dopo aver terminato la configurazione. **Nota** La codifica dei contenuti con la massima priorità deve essere supportata da API Gateway. In caso contrario, la compressione non viene applicata al payload della risposta. **Topics** + [Abilitazione della compressione dei payload per un'API mediante la console API Gateway](#api-gateway-enable-compression-console) + [Abilita la compressione del payload per un'API utilizzando il AWS CLI](#api-gateway-enable-compression-cli) + [Codifiche di contenuto supportate da API Gateway](#api-gateway-supported-content-encodings) ## Abilitazione della compressione dei payload per un'API mediante la console API Gateway Nella procedura seguente viene descritto come abilitare la compressione del payload per un'API. **Per abilitare la compressione del payload usando 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. Seleziona un'API esistente o creane una nuova. 1. Nel riquadro di navigazione principale, scegli **Impostazioni API**. 1. Nella sezione **Dettagli API**, scegli **Modifica**. 1. Attiva l'opzione **Codifica contenuto** per abilitare la compressione del payload. In **Dimensione corpo minima**, immetti un numero per la dimensione di compressione minima (in byte). Per disattivare la compressione, disattiva l'opzione **Codifica contenuto**. 1. Scegli **Save changes** (Salva modifiche). ## Abilita la compressione del payload per un'API utilizzando il AWS CLI Il [create-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-rest-api.html)comando seguente crea un'API con compressione del payload: ``` aws apigateway create-rest-api \ --name "My test API" \ --minimum-compression-size 0 ``` Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente abilita la compressione del payload per un'API esistente: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value=0 ``` La proprietà `minimumCompressionSize` ha un valore intero non negativo compreso tra 0 e 10485760 (10M byte). Misura la soglia di compressione. Se la dimensione del payload è inferiore a questo valore, la compressione o la decompressione non vengono applicate al payload. Impostando il valore su zero, la compressione viene applicata per qualsiasi dimensione di payload. Il [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html)comando seguente disattiva la compressione del payload: ``` aws apigateway update-rest-api \ --rest-api-id 1234567890 \ --patch-operations op=replace,path=/minimumCompressionSize,value= ``` È anche possibile impostare `value` su una stringa vuota `""` o omettere completamente la proprietà `value` nella chiamata precedente. ## Codifiche di contenuto supportate da API Gateway API Gateway supporta le codifiche di contenuto seguenti: + `deflate` + `gzip` + `identity` API Gateway supporta anche il formato di intestazione `Accept-Encoding` seguente, in base alla specifica [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4): + `Accept-Encoding:deflate,gzip` + `Accept-Encoding:` + `Accept-Encoding:*` + `Accept-Encoding:deflate;q=0.5,gzip;q=1.0` + `Accept-Encoding:gzip;q=1.0,identity;q=0.5,*;q=0` # Chiamata di un metodo API con un payload compresso in Gateway API Per effettuare una richiesta API con un payload compresso, il client deve impostare l'intestazione `Content-Encoding` con una delle [codifiche di contenuto supportate](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). Supponiamo che tu sia un client API e desideri chiamare il metodo PetStore API (`POST /pets`). Il metodo non deve essere chiamato usando l'output JSON seguente: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Length: ... { "type": "dog", "price": 249.99 } ``` Deve invece essere chiamato con lo stesso payload compresso usando la codifica GZIP: ``` POST /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Content-Encoding:gzip Content-Length: ... ���RPP*�,HU�RPJ�OW��e&���L,�,-y�j ``` Quando API Gateway riceve la richiesta, verifica se la codifica di contenuto specificata è supportata. Tenta quindi di decomprimere il payload con la codifica di contenuto specificata. Se la decompressione ha esito positivo, la richiesta viene inviata all'endpoint di integrazione. Se la codifica specificata non è supportata oppure se il payload fornito non è compresso con la codifica specificata, API Gateway restituisce la risposta di errore `415 Unsupported Media Type`. L'errore non viene registrato in CloudWatch Logs, se si verifica nella fase iniziale della decompressione prima che l'API e la fase vengano identificate. # Ricezione di una risposta API con un payload compresso in Gateway API Quando effettua una richiesta in un'API abilitata per la compressione, il client può scegliere di ricevere un payload di risposta compresso con un determinato formato specificando un'intestazione `Accept-Encoding` con una [codifica di contenuto supportata](api-gateway-enable-compression.md#api-gateway-supported-content-encodings). API Gateway comprime il payload di risposta solo quando vengono soddisfatte le condizioni seguenti: + La richiesta in ingresso ha l'intestazione `Accept-Encoding` con una codifica di contenuto e un formato supportati. **Nota** Se l'intestazione non è impostata, il valore predefinito è `*`, come definito in [RFC 7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.3.4). In tal caso, API Gateway non comprime il payload. Alcuni browser o client possono aggiungere `Accept-Encoding` (ad esempio, `Accept-Encoding:gzip, deflate, br`) automaticamente alle richieste abilitate per la compressione. Ciò può attivare la compressione del payload in Gateway API. Se i valori dell'intestazione `Accept-Encoding` supportati non sono specificati in modo esplicito, API Gateway non comprime il payload. + La proprietà `minimumCompressionSize` è impostata nell'API per abilitare la compressione. + La risposta di integrazione non ha un'intestazione `Content-Encoding`. + La dimensione di un payload di risposta di integrazione, dopo l'applicazione del modello di mappatura applicabile, è maggiore o uguale al valore di `minimumCompressionSize` specificato. API Gateway applica l'eventuale modello di mappatura configurato per la risposta di integrazione prima della compressione del payload. Se la risposta di integrazione contiene un'intestazione `Content-Encoding`, API Gateway presuppone che il payload di risposta di integrazione sia già compresso e ignora l'elaborazione della compressione. Un esempio è l'esempio di PetStore API e la seguente richiesta: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept: application/json ``` Il back-end risponde alla richiesta con un payload JSON non compresso simile a quanto segue: ``` 200 OK [ { "id": 1, "type": "dog", "price": 249.99 }, { "id": 2, "type": "cat", "price": 124.99 }, { "id": 3, "type": "fish", "price": 0.99 } ] ``` Per ricevere l'output come payload compresso, il client API può inviare una richiesta come illustrato di seguito: ``` GET /pets Host: {petstore-api-id}.execute-api.{region}.amazonaws.com Accept-Encoding:gzip ``` Il client riceve la risposta con un'intestazione `Content-Encoding` e un payload con codifica GZIP simile a quanto segue: ``` 200 OK Content-Encoding:gzip ... ���RP� J�)JV �:P^IeA*������+(�L �X�YZ�ku0L0B7!9��C#�&����Y��a���^�X ``` Quando il payload di risposta è compresso, solo la dimensione dei dati compressi viene fatturata per il trasferimento dati.