Inserimento delle risposte nella cache per migliorare le prestazioni

Per abilitare e configurare l'inserimento delle risposte nella cache per un gateway API utilizzando la console:

1. Crea o aggiorna un gateway API utilizzando la console.

   Per ulteriori informazioni, vedere Creazione di un gateway API e Aggiornamento di un gateway API o di una distribuzione API.

2. Nella sezione Opzioni avanzate della finestra di dialogo Crea gateway, fare clic sul pulsante Abilita accanto a Inserimento nella cache delle risposte e:

   1. Specificare le opzioni del server cache, come indicato di seguito.
      • Host: il nome host del server cache. Ad esempio, "cache.example.com".
      • Numero di porta: il numero di porta sul server cache. Ad esempio, 6379.
   2. Specificare le opzioni Credenziali server cache, come indicato di seguito.
      • Vault: il nome del vault nel servizio Vault che contiene le credenziali per eseguire il login al server cache.
      • Segreto vault: il nome del segreto nel vault specificato che contiene le credenziali per eseguire il login al server cache.
      • Numero versione del segreto vault: la versione del segreto da utilizzare.
   3. Specificare le opzioni di Connessione al server cache, come indicato di seguito.
      • Usa SSL/TLS nelle richieste: indica se il server cache è abilitato per TLS e quindi se impostare una connessione sicura tra il gateway API e il server cache su TLS (precedentemente SSL).
      • Verifica certificato SSL/TLS: indica se il gateway API verifica il certificato TLS (precedentemente SSL) del server cache. Si noti che al momento vengono verificati solo i certificati firmati dalle autorità di certificazione pubbliche.
      • Timeout connessione: tempo di attesa prima di abbandonare un tentativo di connessione al server cache, in millisecondi. Se il gateway API non è in grado di connettersi al server cache entro questo periodo di tempo, il gateway API non recupera i dati precedentemente inseriti nella cache dal server cache e non scrive nuovi dati nel server cache per un potenziale futuro riutilizzo.
      • Timeout lettura: tempo di attesa prima di abbandonare un tentativo di lettura dei dati dal server cache, in millisecondi. Se il gateway API non è in grado di recuperare i dati dal server cache entro questo periodo di tempo, il gateway API invia invece una richiesta al servizio backend.
      • Timeout invio: tempo di attesa prima di abbandonare un tentativo di scrittura dei dati nel server cache, in millisecondi. Se il gateway API non è in grado di inviare dati al server cache entro questo periodo di tempo, una risposta non viene inserita nella cache per un potenziale riutilizzo futuro.
3. Fare clic su Crea o su Salva modifiche per creare o aggiornare il gateway API.

Per abilitare e configurare l'inserimento delle risposte nella cache per un gateway API utilizzando l'interfaccia CLI e un file JSON, effettuare le operazioni riportate di seguito.

1. Utilizzando l'editor JSON preferito, creare un file di configurazione della cache nel formato seguente:

   {
     "type" : "EXTERNAL_RESP_CACHE",
     "servers" : [
       {
         "host" : "<cache-server-hostname>",
         "port" : <port-number>
       }
     ],
     "authenticationSecretId" : "<secret-ocid>",
     "authenticationSecretVersionNumber" : <secret-version-number>,
     "isSSLEnabled" : <true|false>,
     "isSSLVerifyDisabled" : <true|false>,
     "connectTimeoutInMs" : <milliseconds>,
     "readTimeoutInMs" : <milliseconds>,
     "readTimeoutInMs" : <milliseconds>
   }

   dove:

   • "type" : "EXTERNAL_RESP_CACHE" indica che l'inserimento delle risposte nella cache deve essere abilitato. Se non è impostata, l'impostazione predefinita è "type" : "NONE", a indicare che l'inserimento delle risposte nella cache è disabilitato.
   • "host" : "<cache-server-hostname>" è il nome host del server cache. Ad esempio, "host" : "cache.example.com".
   • "port" : <port-number> è il numero di porta sul server cache. Ad esempio, "port" : 6379.
   • "authenticationSecretId" : "<secret-ocid>" è l'OCID del segreto definito in un vault nel servizio Vault che contiene le credenziali per eseguire il login al server cache. Ad esempio, "authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn"
   • "authenticationSecretVersionNumber" : <secret-version-number> è la versione del segreto da utilizzare. Ad esempio, "authenticationSecretVersionNumber" : 1
   • "isSSLEnabled" : <true|false> indica se il server cache è abilitato per TLS e quindi se impostare una connessione sicura tra il gateway API e il server cache su TLS (precedentemente SSL). Se non è impostata, l'impostazione predefinita è false
   • "isSSLVerifyDisabled" : <true|false> indica se il gateway API verifica il certificato TLS (precedentemente SSL) del server cache. Si noti che al momento vengono verificati solo i certificati firmati dalle autorità di certificazione pubbliche. Se non è impostata, l'impostazione predefinita è false
   • "connectTimeoutInMs" : <milliseconds> indica il tempo di attesa prima di abbandonare un tentativo di connessione al server cache, in millisecondi. Se il gateway API non è in grado di connettersi al server cache entro questo periodo di tempo, il gateway API non recupera i dati precedentemente inseriti nella cache dal server cache e non scrive nuovi dati nel server cache per un potenziale futuro riutilizzo. Se non è impostata, l'impostazione predefinita è 1000. Ad esempio, "connectTimeoutInMs" : 1500
   • "readTimeoutInMs" : <milliseconds> indica il tempo di attesa prima di abbandonare un tentativo di lettura dei dati dal server cache, in millisecondi. Se il gateway API non è in grado di recuperare i dati dal server cache entro questo periodo di tempo, il gateway API invia invece una richiesta al servizio backend. Se non è impostata, l'impostazione predefinita è 1000. Ad esempio, "readTimeoutInMs" : 250
   • "sendTimeoutInMs" : <milliseconds> indica il tempo di attesa prima di abbandonare un tentativo di scrittura dei dati nel server cache, in millisecondi. Se il gateway API non è in grado di inviare dati al server cache entro questo periodo di tempo, le risposte non vengono inserite nella cache per un potenziale futuro riutilizzo. Se non è impostata, l'impostazione predefinita è 1000. Ad esempio, "sendTimeoutInMs" : 1250

   Ad esempio:

   {
     "type" : "EXTERNAL_RESP_CACHE",
     "servers" : [
       {
         "host" : "cache.example.com",
         "port" : 6379
       }
     ],
     "authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn",
     "authenticationSecretVersionNumber" : 1,
     "isSSLEnabled" : true,
     "isSSLVerifyDisabled" : false,
     "connectTimeoutInMs" : 1000,
     "readTimeoutInMs" : 250,
     "sendTimeoutInMs" : 1000
   }

2. Salvare il file di configurazione della cache con il nome desiderato. Ad esempio, resp-cache-config.json
3. Utilizzare il file di configurazione della cache quando si crea o si aggiorna un gateway API utilizzando l'interfaccia CLI:
   • Per creare un nuovo gateway API con l'inserimento delle risposte nella cache abilitato, seguire le istruzioni CLI in Creazione di un gateway API e impostare il parametro --response-cache-details sul nome e sulla posizione del file di configurazione della cache. Ad esempio:

     oci api-gateway gateway create --display-name "Hello World Gateway" --compartment-id ocid1.compartment.oc1..aaaaaaaa7______ysq --endpoint-type "PRIVATE" --subnet-id ocid1.subnet.oc1.iad.aaaaaaaaz______rca --response-cache-details file:///etc/caches/resp-cache-config.json

   • Per aggiornare un gateway API esistente per abilitare l'inserimento delle risposte nella cache o modificare le impostazioni di inserimento delle risposte nella cache, seguire le istruzioni CLI in Aggiornamento di un gateway API o di una distribuzione API e impostare il parametro --response-cache-details sul nome e sulla posizione del file di configurazione della cache. Ad esempio:

     oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --response-cache-details file:///etc/caches/resp-cache-config.json

Per aggiungere criteri di richiesta e risposta di inserimento delle risposte nella cache a una specifica di distribuzione API utilizzando la console, procedere come segue.

1. Creare o aggiornare una distribuzione API utilizzando la console, selezionare l'opzione Da zero e immettere i dettagli nella pagina Informazioni di base.

   Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.

2. Fare clic su Successivo per immettere i dettagli relativi ai singoli instradamenti nella distribuzione API nella pagina Instradamenti e fare clic su Inserimento nella cache delle risposte.

3. Selezionare l'opzione Inserimento nella cache per questo instradamento e specificare le opzioni di inserimento nella cache delle risposte che si applicano a questo instradamento specifico:
   • TTL (Time To Live) per le risposte inserite nella cache in secondi: per quanto tempo i dati inseriti nella cache sono disponibili nel server cache per questo instradamento specifico.
   • Aggiunte di chiavi della cache: una o più variabili di contesto da aggiungere alla chiave cache predefinita per associare più da vicino una risposta memorizzata nella cache a una richiesta specifica. Ad esempio, request.headers[X-Username]. È possibile effettuare una selezione da un elenco di variabili di contesto comunemente utilizzate oppure immettere una variabile di contesto di propria scelta. Non precedere la variabile di contesto con il simbolo $ o racchiuderla tra parentesi graffe (come si farebbe se si aggiungesse la variabile di contesto a un URL in una specifica di distribuzione API in un file JSON). Per ulteriori informazioni, vedere Note sulla personalizzazione delle chiavi della cache.
4. Se si desidera inserire nella cache le risposte per le richieste che contengono un'intestazione di autorizzazione o che contengono un'intestazione o un parametro di query identificato in un criterio di autenticazione, selezionare l'opzione Inserisci nella cache risposte con intestazioni di autorizzazione.

   Tenere presente che l'inserimento delle risposte nella cache per tali richieste potrebbe compromettere la sicurezza dei dati. Per ulteriori informazioni, vedere Note sull'inserimento delle risposte nella cache per le richieste contenenti credenziali (inserimento nella cache privato).

5. Fare clic su Successivo per esaminare i dettagli immessi per la distribuzione API.
6. Fare clic su Crea o su Salva modifiche per creare o aggiornare la distribuzione API.
7. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).

Per aggiungere l'inserimento delle risposte nella cache a un determinato instradamento, è necessario aggiungere sia un criterio di richiesta che un criterio di risposta.

Per aggiungere la richiesta e il criterio di risposta di inserimento nella cache delle risposte a una specifica di distribuzione API in un file JSON, effettuare le operazioni riportate di seguito.

1. Utilizzando l'editor JSON preferito, modificare la specifica di distribuzione API esistente alla quale si desidera aggiungere l'inserimento delle risposte nella cache o creare una nuova specifica di distribuzione API (vedere Creazione di una specifica di distribuzione API).

   Ad esempio, la seguente specifica di distribuzione API di base definisce una semplice funzione serverless Hello World in Funzioni OCI come un singolo backend:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Per specificare la richiesta di inserimento nella cache delle risposte e il criterio di risposta che si applica a un singolo instradamento:

   1. Inserire sia una sezione requestPolicies che una sezione responsePolicies dopo la sezione backend per l'instradamento a cui si desidera applicare il criterio. Ad esempio:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {},
            "responsePolicies": {}
          }
        ]
      }

   2. Aggiungere il seguente criterio di richiesta responseCacheLookup alla nuova sezione requestPolicies da applicare all'instradamento:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "responseCacheLookup": {
                "type": "SIMPLE_LOOKUP_POLICY",
                "isEnabled": true,
                "isPrivateCachingEnabled": <true|false>,
                "cacheKeyAdditions": [<list-of-context-variables>]
              }
            },
            "responsePolicies": {}
          }
        ]
      }

      dove:

      • "type": "SIMPLE_LOOKUP_POLICY" è il tipo di inserimento nella cache delle risposte da implementare. Attualmente è supportata solo "SIMPLE_LOOKUP_POLICY".
      • "isEnabled": true indica che l'inserimento delle risposte nella cache è abilitato per l'instradamento. Se si desidera disabilitare temporaneamente l'inserimento delle risposte nella cache, impostare "isEnabled": false. Se non viene specificato, il valore predefinito è true.
      • "isPrivateCachingEnabled": <true|false> indica se inserire nella cache le risposte per le richieste che contengono un'intestazione di autorizzazione o che contengono un'intestazione o un parametro di query identificato in un criterio di autenticazione. Tenere presente che l'inserimento delle risposte nella cache per tali richieste potrebbe compromettere la sicurezza dei dati. Se non specificato, l'impostazione predefinita è false, a indicare che le risposte per tali richieste non vengono inserite nella cache. Per ulteriori informazioni, vedere Note sull'inserimento delle risposte nella cache per le richieste contenenti credenziali (inserimento nella cache privato).
      • "cacheKeyAdditions": [<list-of-context-variables>] è un elenco facoltativo di variabili di contesto separate da virgole da aggiungere alla chiave cache predefinita per associare più da vicino una risposta memorizzata nella cache a una richiesta specifica. Ad esempio, "cacheKeyAdditions": ["request.headers[Accept]"]. Non precedere la variabile di contesto con il simbolo $ o racchiuderla tra parentesi graffe (come si farebbe se si aggiungesse la variabile di contesto a un URL in una specifica di distribuzione API in un file JSON). Per ulteriori informazioni, vedere Note sulla personalizzazione delle chiavi della cache.
   3. Aggiungere il seguente criterio di risposta responseCacheStorage alla nuova sezione responsePolicies da applicare all'instradamento:

      {
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "responseCacheLookup": {
                "type": "SIMPLE_LOOKUP_POLICY",
                "isEnabled": true,
                "isPrivateCachingEnabled": false,
                "cacheKeyAdditions": ["request.headers[Accept]"]
              }
            },
            "responsePolicies": {
              "responseCacheStorage": {
                "type": "FIXED_TTL_STORE_POLICY",
                "timeToLiveInSeconds": <seconds>
              }
            }
          }
        ]
      }

      dove:

      • "type": "FIXED_TTL_STORE_POLICY" è il tipo di cache delle risposte in cui memorizzare le risposte. Attualmente è supportata solo "FIXED_TTL_STORE_POLICY".
      • "timeToLiveInSeconds": <seconds> specifica la durata della disponibilità dei dati inseriti nella cache nel server cache per questo instradamento specifico. Ad esempio, "timeToLiveInSeconds": 300

   Ad esempio:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         },
         "requestPolicies": {
           "responseCacheLookup": {
             "type": "SIMPLE_LOOKUP_POLICY",
             "isEnabled": true,
             "isPrivateCachingEnabled": false,
             "cacheKeyAdditions": ["request.headers[Accept]"]
           }
         },
         "responsePolicies": {
           "responseCacheStorage": {
             "type":"FIXED_TTL_STORE_POLICY",
             "timeToLiveInSeconds": 300
           }
         }
       }
     ]
   }

3. Salvare il file JSON contenente la specifica di distribuzione API.

4. Utilizzare la specifica di distribuzione API quando si crea o si aggiorna una distribuzione API nei modi riportati di seguito.

   • specificando il file JSON nella console quando si seleziona l'opzione Carica un'interfaccia API esistente
   • specificando il file JSON in una richiesta all'API REST del gateway API

   Per ulteriori informazioni, vedere Distribuzione di un'interfaccia API in un gateway API mediante la creazione di una distribuzione API e Aggiornamento di un gateway API o di una distribuzione API.

5. (Facoltativo) Confermare che l'interfaccia API sia stata distribuita correttamente chiamandola (vedere Chiamata di un'interfaccia API distribuita in un gateway API).