Impostazioni della cache per le API REST in API Gateway

Si può abilitare il caching dell'API in Amazon API Gateway per memorizzare nella cache le risposte dell'endpoint. Con il caching, puoi ridurre i 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 and 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.

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.

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.

Abilitazione del caching di Amazon API Gateway

In API Gateway, puoi abilitare la memorizzazione nella cache 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, cacheClusterSizeconsulta 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à?.

Nella console API Gateway, è possibile configurare la memorizzazione nella cache nella pagina Stages. Si effettua il provisioning della cache dello stage e si specifica un'impostazione di cache predefinita a livello di metodo. Se attivate la cache a livello di metodo predefinita, la memorizzazione nella cache a livello di metodo viene attivata per tutti i GET metodi sullo stage, a meno che tale metodo non disponga di un'alternativa al metodo. Tutti GET i metodi aggiuntivi che distribuirete sullo stage avranno una cache a livello di metodo. Per configurare l'impostazione della memorizzazione nella cache a livello di metodo per metodi specifici dello stage, puoi utilizzare le sostituzioni dei metodi. Per ulteriori informazioni sulle sostituzioni dei metodi, consulta. Sostituisci la memorizzazione nella cache a livello di fase di API Gateway per la memorizzazione nella cache a livello di metodo

Per configurare il caching dell'API per una fase specifica:

1. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Scegliere Stages (Fasi).

3. Nell'elenco Stages (Fasi) dell'API, selezionare la fase.

4. Nella sezione Dettagli fase scegli Modifica.

5. In Impostazioni aggiuntive, per Impostazioni cache, attiva Provision API cache.

   In questo modo viene fornito un cluster di cache per il tuo stage.

6. Per attivare la memorizzazione nella cache per lo stage, attiva la memorizzazione nella cache a livello di metodo predefinito.

   Questo attiva la memorizzazione nella cache a livello di metodo per tutti i metodi sullo stage. GET Tutti GET i metodi aggiuntivi distribuiti in questa fase avranno una cache a livello di metodo.

   Nota

   Se si dispone di un'impostazione esistente per una cache a livello di metodo, la modifica dell'impostazione predefinita della memorizzazione nella cache a livello di metodo non influisce sull'impostazione esistente.

   

7. Seleziona Salvataggio delle modifiche.

Nota

Per completare la creazione o l'eliminazione di una cache, API Gateway impiega circa 4 minuti.

Quando viene creata una cache, il valore del cluster di cache cambia da a. Create in progress Active Una volta completata l'eliminazione della cache, il valore del cluster di cache cambia da Delete in progress aInactive.

Quando attivate la memorizzazione nella cache a livello di metodo per tutti i metodi sullo stage, il valore predefinito di memorizzazione nella cache a livello di metodo cambia in. Active Se disattivate la memorizzazione nella cache a livello di metodo per tutti i metodi sullo stage, il valore di memorizzazione nella cache a livello di metodo predefinito cambia in. Inactive Se disponete di 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.

Puoi verificare che il caching funzioni come previsto in due modi:

• Esamina le CloudWatch metriche di CacheHitCounte CacheMissCountper l'API e lo stage.

• Inserisci un timestamp nella risposta.

Nota

Non dovresti usare l'X-Cacheintestazione della CloudFront risposta per determinare se la tua API viene servita dall'istanza della cache di API Gateway.

Sostituisci la memorizzazione nella cache a livello di fase di API Gateway per la memorizzazione nella cache a livello di metodo

È possibile sovrascrivere le impostazioni della cache a livello di fase attivando o disattivando la memorizzazione nella cache per un metodo specifico. È inoltre possibile modificare il periodo TTL o attivare o disattivare la crittografia per le risposte memorizzate nella cache.

Se modificate l'impostazione predefinita della memorizzazione nella cache a livello di metodo nei dettagli dello stage, ciò non influirà sulle impostazioni della cache a livello di metodo che hanno delle 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. Accedere alla console API Gateway all'indirizzo https://console.aws.amazon.com/apigateway.

2. Selezionare l'API.

3. Scegliere Stages (Fasi).

4. Nell'elenco Stages (Fasi) dell'API, espandere la fase e scegliere un metodo nell'API.

5. Nella sezione Sostituzioni del metodo, scegli Modifica.

6. Nella sezione Impostazioni metodo, attiva o disattiva Abilita cache metodo o personalizza le altre opzioni desiderate.

   Nota

   La memorizzazione nella cache non è attiva finché non si effettua il provisioning di un cluster di cache per lo stage.

7. Selezionare Salva.

Uso dei parametri di metodo o di integrazione come chiavi di cache per indicizzare le risposte memorizzate nella cache

Quando in un metodo o in un'integrazione memorizzati nella cache sono presenti parametri che si presentano come intestazioni personalizzate, percorsi di URL o stringhe di query, puoi usare alcuni di essi o tutti per formare le chiavi di cache. API Gateway può memorizzare nella cache le risposte del metodo, a seconda dei valori di parametro utilizzati.

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
...
        

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.

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.

Per svuotare la cache della fase API, scegli il menu Operazioni fase, quindi seleziona Svuota cache della fase.

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.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "execute-api:InvalidateCache"
      ],
      "Resource": [
        "arn:aws:execute-api:region:account-id: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 (*) 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 Controlla l'accesso a un'API REST con autorizzazioni IAM.

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.

Puoi controllare come vengono gestite le richieste non autorizzate scegliendo un'opzione da Gestione delle richieste non autorizzate nella console API Gateway.

Le tre opzioni risultano nei comportamenti seguenti:

• Fail the request with 403 status code (Richiesta non riuscita con codice stato 403): restituisce una risposta di tipo non autorizzato 403.

  Per impostare questa opzione utilizzando l'API, usa FAIL_WITH_403.

• Ignore cache control header; Add a warning in response header (Ignora intestazione di controllo cache; aggiungi avviso in intestazione risposta): elabora la richiesta e aggiunge un'intestazione di avviso nella risposta.

  Per impostare questa opzione utilizzando l'API, usa SUCCEED_WITH_RESPONSE_HEADER.

• Ignore cache control header (Ignora intestazione di controllo cache): elabora la richiesta senza aggiungere un'intestazione di avviso nella risposta.

  Per impostare questa opzione utilizzando l'API, usa SUCCEED_WITHOUT_RESPONSE_HEADER.