Armazenando Respostas no Cache para Melhorar o Desempenho

Para ativar e configurar o armazenamento em cache de resposta para um gateway de API usando a Console:

1. Crie ou atualize um gateway de API usando a Console.

   Para obter mais informações, consulte Criando um Gateway de API e Atualizando um Gateway de API.

2. Na seção Opções Avançadas da caixa de diálogo Criar Gateway, selecione o botão Ativar ao lado de Armazenamento em Cache de Resposta e:

   1. Especifique as opções do Servidor de Cache, da seguinte forma:
      • Host: O nome do host do servidor de cache. Por exemplo, "cache.example.com".
      • Número da Porta: O número da porta no servidor de cache. Por exemplo, 6379.
   2. Especifique as opções de Credenciais do Servidor de Cache, da seguinte forma:
      • Vault: O nome do vault no serviço Vault que contém as credenciais para fazer log-in no servidor de cache.
      • Segredo do Vault: O nome do segredo no vault especificado que contém as credenciais para fazer log-in no servidor de cache.
      • Número da Versão do Segredo do Vault: A versão do segredo a ser usado.
   3. Especifique as opções de Conexão do Servidor de Cache, da seguinte forma:
      • Usar SSL/TLS em Solicitações: Se o servidor de cache está ativado para TLS e, portanto, se deve configurar uma conexão segura entre o gateway de API e o servidor de cache por TLS (anteriormente SSL).
      • Verificar Certificado SSL/TLS: Se o gateway de API verifica o certificado TLS (anteriormente SSL) do servidor de cache. Observe que somente certificados assinados por autoridades de certificação públicas são verificados no momento.
      • Timeout de Conexão: Quanto tempo de espera antes de abandonar uma tentativa de conexão com o servidor de cache, em milissegundos. Se o gateway de API não puder se conectar ao servidor de cache dentro desse período, o gateway de API não recuperará dados armazenados no cache anteriormente do servidor de cache e não gravará novos dados no servidor de cache para possível reutilização futura.
      • Timeout de Leitura: Quanto tempo de espera antes de abandonar uma tentativa de ler dados do servidor de cache, em milissegundos. Se o gateway de API não puder recuperar dados do servidor de cache dentro desse período, o gateway de API enviará uma solicitação ao serviço de back-end.
      • Timeout de Envio: Quanto tempo de espera antes de abandonar uma tentativa de gravar dados no servidor de cache, em milissegundos. Se o gateway de API não puder enviar dados para o servidor de cache dentro desse período, uma resposta não será armazenada em cache para reutilização futura potencial.
3. Selecione Criar ou Salvar Alterações para criar ou atualizar o gateway de API.

Para ativar e configurar o armazenamento em cache de resposta para um gateway de API usando a CLI e um arquivo JSON:

1. Usando seu editor de JSON preferido, crie um arquivo de configuração de cache no formato:

   {
     "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>
   }

   em que:

   • "type" : "EXTERNAL_RESP_CACHE" indica que o armazenamento no cache de resposta deve ser ativado. Se não for definido, o padrão será "type" : "NONE", indicando que o armazenamento no cache de resposta está desativado.
   • "host" : "<cache-server-hostname>" é o nome do host do servidor de cache. Por exemplo, "host" : "cache.example.com".
   • "port" : <port-number> é o número da porta no servidor de cache. Por exemplo, "port" : 6379.
   • "authenticationSecretId" : "<secret-ocid>" é o OCID do segredo definido em um vault no serviço Vault que contém as credenciais para fazer log-in no servidor de cache. Por exemplo, "authenticationSecretId" : "ocid.oc1.sms.secret.aaaaaa______gbdn"
   • "authenticationSecretVersionNumber" : <secret-version-number> é a versão do segredo a ser usada. Por exemplo, "authenticationSecretVersionNumber" : 1
   • "isSSLEnabled" : <true|false> indica se o servidor de cache está ativado para TLS e, portanto, se deseja configurar uma conexão segura entre o gateway de API e o servidor de cache por meio de TLS (anteriormente SSL). Se não for definido, o padrão será false
   • "isSSLVerifyDisabled" : <true|false> indica se o gateway de API verifica o certificado TLS (anteriormente SSL) do servidor de cache. Observe que somente certificados assinados por autoridades de certificação públicas são verificados no momento. Se não for definido, o padrão será false
   • "connectTimeoutInMs" : <milliseconds> indica quanto tempo esperar antes de abandonar uma tentativa de conexão com o servidor de cache, em milissegundos. Se o gateway de API não puder estabelecer conexão com o servidor de cache dentro desse período, o gateway de API não recuperará dados armazenados no cache anteriormente do servidor de cache e não gravará novos dados no servidor de cache para potencial reutilização futura. Se não for definido, o padrão será 1000. Por exemplo, "connectTimeoutInMs" : 1500
   • "readTimeoutInMs" : <milliseconds> indica quanto tempo esperar antes de abandonar uma tentativa de ler dados do servidor de cache, em milissegundos. Se o gateway de API não puder recuperar dados do servidor de cache dentro desse período, o gateway de API enviará uma solicitação ao serviço de back-end. Se não for definido, o padrão será 1000. Por exemplo, "readTimeoutInMs" : 250
   • "sendTimeoutInMs" : <milliseconds> indica quanto tempo esperar antes de abandonar uma tentativa de gravar dados no servidor de cache, em milissegundos. Se o gateway de API não puder enviar dados para o servidor de cache dentro desse período, as respostas não serão armazenadas em cache para potencial reutilização futura. Se não for definido, o padrão será 1000. Por exemplo, "sendTimeoutInMs" : 1250

   Por exemplo:

   {
     "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. Salve o arquivo de configuração do cache com o nome de sua escolha. Por exemplo, resp-cache-config.json
3. Use o arquivo de configuração do cache ao criar ou atualizar um gateway de API usando a CLI:
   • Para criar um novo gateway de API com cache de resposta ativado, siga as instruções da CLI em Criando um Gateway de API e defina o parâmetro --response-cache-details como o nome e o local do arquivo de configuração do cache. Por exemplo:

     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

   • Para atualizar um gateway de API existente para ativar o armazenamento em cache da resposta ou alterar as definições de armazenamento em cache da resposta, siga as instruções da CLI em Atualizando um Gateway de API e defina o parâmetro --response-cache-details com o nome e o local do arquivo de configuração do cache. Por exemplo:

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

Para adicionar solicitações de armazenamento em cache de resposta e políticas de resposta a uma especificação de implantação de API usando a Console:

1. Crie ou atualize uma implantação de API usando a Console. Selecione a opção Totalmente Nova e insira os detalhes na página Informações Básicas.

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

2. Selecione Próximo para informar detalhes de rotas individuais na página Rotas e selecione Armazenamento em Cache de Resposta.

3. Selecione a opção Armazenando em Cache para esta Rota e especifique as opções de armazenamento em cache de resposta que se aplicam a esta rota específica:
   • TTL (Tempo de Vida) para Respostas Armazenadas em Cache em Segundos: Por quanto tempo os dados armazenados em cache estão disponíveis no servidor de cache para essa rota específica.
   • Adições de Chave de Cache: Uma ou mais variáveis de contexto a serem adicionadas à chave de cache padrão para associar mais de perto uma resposta em cache a uma solicitação específica. Por exemplo, request.headers[X-Username]. Você pode selecionar em uma lista de variáveis de contexto comumente usadas ou inserir uma variável de contexto de sua escolha. Não preceda a variável de contexto com um símbolo $ ou coloque-a entre chaves (como faria se estivesse adicionando a variável de contexto a um URL em uma especificação de implantação de API em um arquivo JSON). Para obter mais informações, consulte Observações sobre a Personalização de Chaves de Cache.
4. Se quiser armazenar em cache respostas para solicitações que contenham um cabeçalho de autorização, ou que contenham um cabeçalho ou parâmetro de consulta identificado em uma política de autenticação, selecione a opção Armazenar em Cache Respostas com Cabeçalhos de Autorização.

   Observe que o armazenamento em cache das respostas para essas solicitações pode comprometer a segurança dos dados. Para obter mais informações, consulte Observações sobre Respostas de Armazenamento no Cache para Solicitações que Contêm Credenciais (Armazenamento no Cache Privado).

5. Selecione Próximo para revisar os detalhes informados para a implantação de API.
6. Selecione Criar ou Salvar Alterações para criar ou atualizar a implantação de API.
7. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).

Para adicionar cache de resposta a uma rota específica, adicione uma política de solicitação e uma política de resposta.

Para adicionar a solicitação de cache de resposta e a política de resposta a uma especificação de implantação de API em um arquivo JSON:

1. Usando seu editor JSON preferido, edite a especificação de implantação de API existente à qual você deseja adicionar armazenamento em cache de resposta ou crie uma nova especificação de implantação de API (consulte Criando uma Especificação de Implantação de API).

   Por exemplo, a seguinte especificação básica de implantação de API define uma função simples sem servidor Hello World no OCI Functions como um único back-end:

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

2. Para especificar a solicitação de cache de resposta e a política de resposta que se aplica a uma rota individual:

   1. Insira uma seção requestPolicies e uma seção responsePolicies após a seção de backend para a rota à qual você deseja que a política se aplique. Por exemplo:

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

   2. Adicione a seguinte política de solicitação responseCacheLookup à nova seção requestPolicies para aplicar à rota:

      {
        "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": {}
          }
        ]
      }

      em que:

      • "type": "SIMPLE_LOOKUP_POLICY" é o tipo de cache de resposta a ser implementado. Somente "SIMPLE_LOOKUP_POLICY" é suportado no momento.
      • "isEnabled": true indica que o armazenamento no cache de resposta está ativado para a rota. Se quiser desativar temporariamente o armazenamento no cache de resposta, defina "isEnabled": false. Se não for especificado, o padrão será true.
      • "isPrivateCachingEnabled": <true|false> indica se as respostas devem ser armazenadas em cache para solicitações que contêm um cabeçalho de autorização ou que contêm um cabeçalho ou parâmetro de consulta identificado em uma política de autenticação. Observe que o armazenamento em cache das respostas para essas solicitações pode comprometer a segurança dos dados. Se não for especificado, o padrão será false indicando que as respostas para essas solicitações não são armazenadas em cache. Para obter mais informações, consulte Observações sobre Respostas de Armazenamento no Cache para Solicitações que Contêm Credenciais (Armazenamento no Cache Privado).
      • "cacheKeyAdditions": [<list-of-context-variables>] é uma lista opcional separada por vírgulas de variáveis de contexto a serem adicionadas à chave de cache padrão para associar mais de perto uma resposta em cache a uma solicitação específica. Por exemplo, "cacheKeyAdditions": ["request.headers[Accept]"]. Não preceda a variável de contexto com um símbolo $ ou coloque-a entre chaves (como faria se estivesse adicionando a variável de contexto a um URL em uma especificação de implantação de API em um arquivo JSON). Para obter mais informações, consulte Observações sobre como Personalizar Chaves de Cache.
   3. Adicione a seguinte política de resposta responseCacheStorage à nova seção responsePolicies para aplicar à rota:

      {
        "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>
              }
            }
          }
        ]
      }

      em que:

      • "type": "FIXED_TTL_STORE_POLICY" é o tipo de cache de resposta no qual as respostas serão armazenadas. Somente "FIXED_TTL_STORE_POLICY" é suportado no momento.
      • "timeToLiveInSeconds": <seconds> especifica por quanto tempo os dados armazenados no cache estão disponíveis no servidor de cache para essa rota específica. Por exemplo, "timeToLiveInSeconds": 300

   Por exemplo:

   {
     "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. Salve o arquivo JSON que contém a especificação de implantação de API.

4. Use a especificação de implantação de API ao criar ou atualizar uma implantação de API das seguintes formas:

   • especificando o arquivo JSON na Console quando você selecionar a opção Carregar uma API existente
   • especificando o arquivo JSON em uma solicitação à API REST do serviço API Gateway

   Para obter mais informações, consulte Implantando uma API em um Gateway de API por meio da Criação de uma Implantação de API e Atualizando um Gateway de API.

5. (Opcional) Confirme se a API foi implantada com êxito, chamando-a (consulte Chamando uma API Implantada em um Gateway de API).