Impostazioni della cache per REST API in Gateway API

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 il caching per una fase, le risposte dall'endpoint vengono memorizzate da API Gateway nella cache per un periodo TTL (time-to-live) specificato espresso 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. È possibile utilizzare i parametri CacheHitCount e CacheMissCount in Amazon CloudWatch per monitorare le richieste inviate da API Gateway 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 maggiori informazioni su AWS, sull'Health Insurance Portability and Accountability Act statunitense del 1996 (HIPAA) e sull'utilizzo dei servizi AWS per elaborare, archiviare e trasmettere informazioni sanitarie protette (Protected Health Information, PHI), consulta Panoramica di 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 rientra nel piano gratuito di AWS. Per ulteriori informazioni, consulta Prezzi di API Gateway.

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, consulta cacheClusterSize nella Documentazione di riferimento delle API di API Gateway.

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

AWS Management Console

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.

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 Cache API con provisioning.

   In questo modo viene effettuato il provisioning di un cluster di cache per la fase.

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

   

7. Scegli Save changes (Salva modifiche).

AWS CLI

Il comando update-stage 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.

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

• Ispeziona i parametri CloudWatch di CacheHitCount e CacheMissCount per l'API e la fase.

• Inserisci un timestamp nella risposta.

Nota

Non utilizzare l’intestazione X-Cache dalla risposta CloudFront per stabilire se l’API viene servita dall’istanza della cache di Gateway API.

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 nella Guida per l’utente di AWS Security Hub.

AWS Management Console

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

   Il caching non è attivo finché non si effettua il provisioning di un cluster di cache per la fase.

7. Selezionare Salva.

AWS CLI

Il comando update-stage 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
...
        

AWS Management Console

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.

AWS CLI

Il comando put-method 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 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.

AWS Management Console

Per svuotare la cache della fase API

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

2. Scegliere un’API che abbia una fase con una cache.

3. Nel riquadro di navigazione principale scegliere Fasi, quindi scegliere una fase con una cache.

4. Scegliere il menu Operazioni fase, quindi selezionare Svuota cache della fase.

AWS CLI

Il comando flush-stage-cache seguente svuota la cache della fase:

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 (*) 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.

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

AWS Management Console

Per specificare come vengono gestite le richieste non autorizzate

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

2. Scegliere un’API che abbia una fase con una cache.

3. Nel riquadro di navigazione principale scegliere Fasi, quindi scegliere una fase con una cache.

4. Per Dettagli fase, scegliere Modifica.

5. Per Gestione delle richieste non autorizzate, selezionare un’opzione.

6. Scegli Continua.

7. Esamina le modifiche e scegli Salva modifiche.

AWS CLI

Il comando update-stage 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"'

Esempio di fase con cache di AWS CloudFormation

Il modello AWS CloudFormation seguente crea un’API di esempio, alloca una cache di 0.5 GB per la fase Prod e attiva il caching 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.

Modello AWS CloudFormation 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