Criar e gerenciar caches com o Rapid Cache

É possível criar e gerenciar instâncias de cache com o Rapid Cache para reduzir a latência e otimizar o acesso aos dados de objetos armazenados no Cloud Storage. Essa solução de armazenamento em cache ajuda a melhorar a performance dos aplicativos ao acelerar a recuperação de dados.

Nesta página, mostramos como criar e gerenciar instâncias de cache com o Rapid Cache. Para informações sobre como usar e gerenciar operações de longa duração iniciadas pelo Rapid Cache operações de cache assíncronas, consulte Usar operações de longa duração.

Antes de usar o Rapid Cache, consulte as limitações e restrições.

Antes de começar

Antes de começar a criar e gerenciar caches, conclua as seções a seguir.

Acessar os papéis necessários

Para receber as permissões necessárias para criar e gerenciar caches do Rapid Cache, peça ao administrador para conceder a você o papel do IAM de Administrador do Storage (roles/storage.admin) no bucket em que você quer criar caches.

Esse papel predefinido contém as permissões necessárias para criar e gerenciar caches do Rapid Cache. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para criar e gerenciar caches do Rapid Cache:

  • storage.anywhereCaches.create (necessário para criar caches)
  • storage.anywhereCaches.disable (necessário para desativar caches)
  • storage.anywhereCaches.get (obrigatório para receber caches)
  • storage.anywhereCaches.list (necessário para listar caches)
  • storage.anywhereCaches.resume (obrigatório para retomar caches)
  • storage.anywhereCaches.update (necessário para atualizar caches)
  • storage.managedFolders.create (necessário apenas para ativar o comportamento de ingestão na gravação de um cache)
  • storage.managedFolders.update (obrigatório apenas para atualizar o comportamento de ingestão na gravação de um cache)

Também é possível receber essas permissões com funções personalizadas.

Para informações sobre como conceder papéis nos buckets, consulte Definir e gerenciar políticas do IAM em buckets.

Para gerenciar operações de longa duração iniciadas por métodos do Rapid Cache, talvez seja necessário ter outras funções e permissões. Consulte papéis necessários para operações de longa duração para saber mais.

Noções básicas sobre as configurações de ingestão na gravação

Ao criar ou atualizar um cache, é possível ativar a ingestão de dados no momento em que eles são gravados no bucket. Essa capacidade é conhecida como "ingest-on-write". Se você planeja ativar a ingestão na gravação usando a API JSON, recomendamos que primeiro entenda os comportamentos das configurações usadas para ingestão na gravação.

Criar um cache

Console

Criar um cache para um bucket atual

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket em que você quer armazenar dados em cache.

  3. Na página Detalhes do bucket, clique na guia Configuração.

  4. Na seção Rapid Cache, clique em Configurar cache.

    A página Configurar cache aparece para seu bucket.

  5. Na seção Regiões de cache, clique na região que contém as zonas em que você quer criar um cache.

  6. Na seção Zonas de cache, selecione as zonas em que você quer criar um cache. Para cada cache criado em uma zona, siga estas etapas opcionais:

    • Opcional: é possível definir um time to live (TTL) personalizado que determina quando os dados são removidos do cache desde a última leitura. Por padrão, o TTL de um cache é definido como um dia.

      Para definir um TTL personalizado:

      1. Na coluna Time to live (TTL), especifique um valor de duração (por exemplo, 48) e uma unidade de tempo (por exemplo, hours).

      2. Clique em Salvar configuração.

    • Opcional: é possível ativar o cache para ingerir dados na gravação, além de ingerir dados na primeira leitura. Por padrão, os caches são configurados apenas para ingerir dados na primeira leitura.

      Para ativar o cache e ingerir dados na gravação:

      1. Na coluna Critérios de ingestão, clique em Editar critérios de ingestão de cache editar.

        A página Definir critérios de ingestão é exibida.

      2. Marque a caixa de seleção Ingerir dados na gravação.

        • Para ativar a ingestão na gravação em todos os objetos recém-gravados no bucket, clique em Bucket inteiro.

        • Para ativar a ingestão na gravação apenas para objetos recém-gravados que tenham um prefixo específico no nome, clique em Pastas selecionadas e insira o prefixo do nome do objeto. O prefixo do nome do objeto também é conhecido como "caminho da pasta".

        Para inserir vários prefixos de nome de objeto, clique em Adicionar add.

        Para remover um prefixo, clique em Excluir item excluir.

      3. Clique em Concluído.

  7. Clique em Salvar configuração.

  8. Na caixa de diálogo que aparece, clique em Confirmar.

    A guia Operações na página Detalhes do bucket é aberta, mostrando o status do job da operação de criação de cache.

Criar um cache para um novo bucket

Para criar um cache como parte da criação de um novo bucket, siga as instruções em Criar um novo bucket.

Para conferir o status do cache de um bucket na página Lista de buckets:

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Clique no ícone Mostrar coluna (), selecione Cache e clique em OK.

Linha de comando

Use o comando gcloud storage buckets anywhere-caches create:

gcloud storage buckets anywhere-caches create gs://BUCKET_NAME CACHE_ZONE \
[--ttl=TTL] [--enable-ingest-on-write]

Substitua:

  • BUCKET_NAME com o nome do bucket para o qual você quer armazenar dados em cache. Por exemplo, my-bucket.

  • CACHE_ZONE pela zona em que o cache será executado. Por exemplo, us-east1-b.

    Para criar vários caches de uma só vez, especifique várias zonas. Por exemplo, us-east1-b us-east1-c us-east1-d.

  • TTL (opcional) com o time to live (TTL) dos dados no cache. O valor pode estar entre 1 e 7 dias, inclusive. O valor pode ser expresso em segundos, minutos, horas e dias. Exemplo:

    • 86400s por 86.400 segundos
    • 1440m por 1.440 minutos
    • 24h por 24 horas
    • 1d por 1 dia

    Se não for especificado, o padrão será 86400s (1 dia).

Para configurar o cache para ingerir dados no momento em que eles são gravados no bucket, especifique a flag opcional --enable-ingest-on-write. Essa flag permite que o cache ingira todos os objetos quando eles são gravados no bucket.

Se bem-sucedido, o comando vai retornar o ID da operação de longa duração associada à operação de criação do AnywhereCache. É possível ver detalhes sobre a operação de longa duração ou cancelar a operação de longa duração para interromper a operação de criação do AnywhereCaches antes que ela seja concluída.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name, std::string const& cache_name,
   std::string const& zone_name) {
  google::storage::control::v2::AnywhereCache cache;
  cache.set_name(cache_name);
  cache.set_zone(zone_name);

  google::storage::control::v2::CreateAnywhereCacheRequest request;
  request.set_parent(std::string{"projects/_/buckets/"} + bucket_name);
  *request.mutable_anywhere_cache() = cache;

  // Start a create operation and block until it completes. Real applications
  // may want to setup a callback, wait on a coroutine, or poll until it
  // completes.
  auto anywhere_cache = client.CreateAnywhereCache(request).get();
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Created anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

import com.google.api.gax.longrunning.OperationFuture;
import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.CreateAnywhereCacheMetadata;
import com.google.storage.control.v2.CreateAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public final class AnywhereCacheCreate {

  public static void anywhereCacheCreate(String bucketName, String cacheName, String zoneName)
      throws InterruptedException, ExecutionException, IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      CreateAnywhereCacheRequest request =
          CreateAnywhereCacheRequest.newBuilder()
              // Set project to "_" to signify globally scoped bucket
              .setParent(BucketName.format("_", bucketName))
              .setAnywhereCache(
                  AnywhereCache.newBuilder().setName(cacheName).setZone(zoneName).build())
              .build();

      // Start a long-running operation (LRO).
      OperationFuture<AnywhereCache, CreateAnywhereCacheMetadata> operation =
          storageControl.createAnywhereCacheAsync(request);

      // Await the LROs completion.
      AnywhereCache anywhereCache = operation.get();
      System.out.printf("Created anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_lro::Poller;
use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::AnywhereCache;

pub async fn sample(client: &StorageControl, bucket_id: &str, zone: &str) -> anyhow::Result<()> {
    let cache = client
        .create_anywhere_cache()
        .set_parent(format!("projects/_/buckets/{bucket_id}"))
        .set_anywhere_cache(AnywhereCache::new().set_zone(zone).set_name(format!(
            "projects/_/buckets/{bucket_id}/anywhereCaches/{zone}"
        )))
        .poller()
        .until_done()
        .await?;
    println!("Created anywhere cache: {cache:?}");
    Ok(())
}

Terraform

Consulte a documentação do Terraform google_storage_anywhere_cache para detalhes sobre como usar o Rapid Cache com o Terraform.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Crie um arquivo JSON com as informações a seguir:

    {
   "zone": "ZONE",
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}

    Substitua:

    • ZONE com a zona em que o cache será executado. Por exemplo, us-east1-b.

    • TIME_TO_LIVE com o time to live (TTL) dos dados no cache. Os valores podem ser expressos em segundos, minutos, horas e dias. Exemplo:

      • 86400s por 86.400 segundos
      • 1440m por 1.440 minutos
      • 24h por 24 horas
      • 1d por 1 dia

      Se não for especificado, o padrão será 86400s (1 dia). O valor máximo é de 7 dias.

    • INGEST_SETTING com true ou false para especificar se o cache vai ingerir dados na gravação.

      Se definido como true, a ingestão na gravação será ativada para todos os objetos gravados no bucket. Se definido como false, o recurso de ingestão na gravação poderá ser ativado seletivamente para objetos gravados em um prefixo ou desativado para todo o bucket.

      Para saber mais sobre as configurações usadas para ativar a ingestão na gravação, consulte os requisitos para ativar a ingestão na gravação.

      Para ativar a ingestão na gravação no nível do bucket ou do prefixo, ou para desativar completamente a ingestão na gravação, use um dos seguintes conjuntos de instruções.

      Ativar a ingestão na gravação para o bucket

      1. Para ativar a ingestão na gravação de todos os objetos gravados no bucket, defina o valor de INGEST_SETTINGS como true.

      2. Siga a etapa 3 para concluir sua solicitação de cache.

      Ativar a ingestão na gravação seletivamente para objetos em um prefixo

      1. Defina o valor de INGEST_SETTINGS como false.

      2. Siga a etapa 3 para concluir sua solicitação de cache.

      3. Crie uma pasta gerenciada que use o prefixo como nome, se ela ainda não existir.

      4. Envie uma solicitação de pasta gerenciada PATCH que inclua uma configuração rapidCacheConfig. Defina os valores dos campos na configuração usando as orientações em Entenda como usar a ingestão na gravação.

      Para instruções detalhadas sobre como usar uma configuração rapidCacheConfig, consulte Atualizar a ingestão na gravação em uma pasta gerenciada.

      Criar um cache sem ativar a ingestão na gravação

      1. Defina o valor de INGEST_SETTINGS como false.

      2. Siga a etapa 3 para concluir sua solicitação de cache.

  3. Use cURL para chamar a API JSON com uma solicitação para criar um cache:

    curl -X POST --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches"

    Substitua:

    • JSON_FILE_NAME com o nome do arquivo JSON criado na Etapa 2.

    • BUCKET_NAME com o nome do bucket para o qual você quer armazenar dados em cache. Por exemplo, my-bucket.

Se for bem-sucedida, a operação vai retornar um google.longrunning.Operation. É possível ver detalhes sobre a operação de longa duração ou cancelar a operação de longa duração para interromper a operação de criação do AnywhereCaches antes que ela seja concluída.

Ver um cache

Console

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado ao cache que você quer visualizar.

  3. Na página Detalhes do bucket, clique na guia Configuração.

  4. Na seção Rapid Cache, clique em Editar ao lado do campo Cache.

  5. Na página Editar configuração, selecione uma região para conferir todos os caches nas zonas dela.

    No painel Zonas de cache, é possível conferir detalhes sobre cada cache disponível.

Linha de comando

Use o comando gcloud storage buckets anywhere-caches describe:

gcloud storage buckets anywhere-caches describe CACHE_ID

Substitua:

  • CACHE_ID com o identificador da instância de cache, formulado como BUCKET_NAME/CACHE_ZONE. Por exemplo, my-bucket/us-east1-b.

Use a flag opcional raw para gerar uma resposta bruta da API em vez de uma resposta padronizada.

Se o comando for bem-sucedido, ele vai retornar um recurso AnywhereCache.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  auto anywhere_cache = client.GetAnywhereCache(cache_name);
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Got anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.GetAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class AnywhereCacheGet {

  public static void anywhereCacheGet(String cacheName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      GetAnywhereCacheRequest request =
          GetAnywhereCacheRequest.newBuilder().setName(cacheName).build();

      AnywhereCache anywhereCache = storageControl.getAnywhereCache(request);

      System.out.printf("Got anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let cache = client
        .get_anywhere_cache()
        .set_name(format!(
            "projects/_/buckets/{bucket_id}/anywhereCaches/{cache_id}"
        ))
        .send()
        .await?;
    println!("Got anywhere cache: {:?}", cache);
    Ok(())
}

Terraform

Consulte a documentação do Terraform google_storage_anywhere_cache para detalhes sobre como usar o Rapid Cache com o Terraform.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com uma solicitação para receber um cache:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/RAPID_CACHE_ID"

    Substitua:

    • BUCKET_NAME com o nome do bucket associado ao cache que você quer recuperar. Por exemplo, my-bucket.

    • RAPID_CACHE_ID pela zona em que o cache está localizado. Por exemplo, us-east1-b.

Se for bem-sucedida, essa operação vai retornar um recurso AnywhereCache.

Listar caches

Console

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado aos caches que você quer visualizar.

  3. Na página Detalhes do bucket, clique na guia Configuração.

  4. Na seção Rapid Cache, clique em Editar ao lado do campo Cache.

  5. Na página Editar configuração, selecione uma região para ver todos os caches nas zonas dela.

    Todos os caches disponíveis para zonas na região aparecem no painel Zonas de cache.

Linha de comando

Use o comando gcloud storage buckets anywhere-caches list:

gcloud storage buckets anywhere-caches list gs://BUCKET_NAME

Substitua:

  • BUCKET_NAME com o nome do bucket associado aos caches que você quer listar. Por exemplo, my-bucket.

Se o comando for bem-sucedido, ele vai retornar uma lista de recursos do AnywhereCache.

Você pode usar a flag --raw para retornar uma resposta bruta da API em vez de uma resposta padronizada. Para mais informações sobre como controlar comportamentos de listagem, como paginação de resultados, consulte a documentação do gcloud storage ls.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& bucket_name) {
  auto const parent = std::string{"projects/_/buckets/"} + bucket_name;
  for (auto anywhere_cache : client.ListAnywhereCaches(parent)) {
    if (!anywhere_cache) throw std::move(anywhere_cache).status();
    std::cout << anywhere_cache->name() << "\n";
  }
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.BucketName;
import com.google.storage.control.v2.ListAnywhereCachesRequest;
import com.google.storage.control.v2.StorageControlClient;
import com.google.storage.control.v2.StorageControlClient.ListAnywhereCachesPagedResponse;
import java.io.IOException;

public final class AnywhereCacheList {

  public static void anywhereCacheList(String bucketName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      ListAnywhereCachesRequest request =
          ListAnywhereCachesRequest.newBuilder()
              .setParent(BucketName.format("_", bucketName))
              .build();

      ListAnywhereCachesPagedResponse page = storageControl.listAnywhereCaches(request);
      for (AnywhereCache anywhereCache : page.iterateAll()) {
        System.out.println(anywhereCache.getName());
      }
    }
  }
}

Rust

use google_cloud_gax::paginator::ItemPaginator;
use google_cloud_storage::client::StorageControl;

pub async fn sample(client: &StorageControl, bucket_id: &str) -> anyhow::Result<()> {
    let mut stream = client
        .list_anywhere_caches()
        .set_parent(format!("projects/_/buckets/{}", bucket_id))
        .by_item();
    while let Some(cache) = stream.next().await {
        println!("Found cache: {:?}", cache?);
    }
    Ok(())
}

Terraform

Consulte a documentação do Terraform google_storage_anywhere_cache para detalhes sobre como usar o Rapid Cache com o Terraform.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com uma solicitação para listar caches:

    curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches"

    Substitua:

    • BUCKET_NAME com o nome do bucket associado aos caches que você quer recuperar. Por exemplo, my-bucket.

    Ao listar vários caches, é possível paginar os resultados.

Se for bem-sucedida, essa operação vai retornar uma lista de recursos AnywhereCache. Para detalhes sobre a estrutura dessa resposta, consulte a resposta na documentação da lista AnywhereCaches.

Atualizar um cache

Console

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado ao cache que você quer atualizar.

  3. Na página Detalhes do bucket, clique na guia Configuração.

  4. Na seção Rapid Cache, clique em Gerenciar caches.

  5. No painel Gerenciar caches, clique em Editar ou criar caches.

  6. Na página Editar configuração que aparece, atualize as propriedades do cache:

    • Para atualizar o TTL do cache, localize a coluna Time to live, especifique uma duração e selecione uma unidade de tempo (por exemplo, minutos).

    • Para configurar o comportamento de ingestão na gravação do cache, incluindo se todos os objetos gravados são armazenados em cache ou apenas objetos seletivos gravados em um prefixo:

      1. Localize a coluna Critérios de ingestão e clique em Editar critérios de ingestão de cache.

      2. No painel Definir critérios de ingestão:

      • Para ativar ou desativar a ingestão na gravação, marque ou desmarque a caixa de seleção Ingerir dados na gravação e clique em Concluído.

      • Para atualizar o cache e ingerir todos os objetos no bucket na gravação, marque a caixa de seleção Ingerir dados na gravação e selecione Bucket inteiro. Depois, clique em Concluído.

      • Para atualizar o cache e ingerir apenas objetos que contenham um prefixo especificado no nome, marque a caixa de seleção Ingerir dados na gravação e selecione Pastas selecionadas.

        • Para especificar um prefixo, insira um ou vários prefixos no campo de caminho da pasta e clique em Concluído.

        • Para remover um prefixo, clique em Excluir item ao lado dele.

  7. Na página Editar configuração, clique em Salvar.

  8. Na caixa de diálogo que aparece, clique em Confirmar.

Linha de comando

Use o comando gcloud storage buckets anywhere-caches update:

gcloud storage buckets anywhere-caches update CACHE_ID \
[--ttl=TTL] [--[no-]enable-ingest-on-write]

Substitua:

  • CACHE_ID com o identificador da instância de cache, formulado como BUCKET_NAME/CACHE_ZONE. Por exemplo, my-bucket/us-east1-b.

    Para atualizar vários caches de uma só vez, especifique vários identificadores. Por exemplo, my-bucket/us-east1-b my-bucket/us-east1-c.

  • TTL (opcional) com o time to live (TTL) dos dados no cache. O valor pode estar entre 1 e 7 dias, inclusive. O valor pode ser expresso em segundos, minutos, horas e dias. Exemplo:

    • 86400s por 86.400 segundos
    • 1440m por 1.440 minutos
    • 24h por 24 horas
    • 1d por 1 dia

Para configurar o cache para ingerir dados no momento em que eles são gravados no bucket, especifique a flag --enable-ingest-on-write. Essa flag permite que o cache ingira todos os objetos quando eles são gravados no bucket. Para desativar o cache de ingestão de dados na gravação, especifique a flag --no-enable-ingest-on-write.

Se for bem-sucedido, o comando vai retornar o ID da operação bruta de longa duração associada à operação de atualização do AnywhereCache. É possível acessar detalhes sobre a operação de longa duração.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  google::storage::control::v2::AnywhereCache cache;
  google::protobuf::FieldMask field_mask;
  field_mask.add_paths("ttl");
  cache.set_name(cache_name);
  cache.mutable_ttl()->set_seconds(86400);
  // Start an update operation and block until it completes. Real applications
  // may want to setup a callback, wait on a coroutine, or poll until it
  // completes.
  auto anywhere_cache = client.UpdateAnywhereCache(cache, field_mask).get();
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Updated anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 


import com.google.api.gax.longrunning.OperationFuture;
import com.google.protobuf.FieldMask;
import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.StorageControlClient;
import com.google.storage.control.v2.UpdateAnywhereCacheMetadata;
import com.google.storage.control.v2.UpdateAnywhereCacheRequest;
import java.io.IOException;
import java.util.concurrent.ExecutionException;

public final class AnywhereCacheUpdate {

  public static void anywhereCacheUpdate(String cacheName, String admissionPolicy)
      throws InterruptedException, ExecutionException, IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      AnywhereCache pendingUpdate =
          AnywhereCache.newBuilder().setName(cacheName).setAdmissionPolicy(admissionPolicy).build();

      UpdateAnywhereCacheRequest request =
          UpdateAnywhereCacheRequest.newBuilder()
              .setAnywhereCache(pendingUpdate)
              .setUpdateMask(FieldMask.newBuilder().addPaths("admission_policy").build())
              .build();

      // Start a long-running operation (LRO).
      OperationFuture<AnywhereCache, UpdateAnywhereCacheMetadata> operation =
          storageControl.updateAnywhereCacheAsync(request);

      // Await the LROs completion.
      AnywhereCache updatedAnywhereCache = operation.get();
      System.out.printf("Updated anywhere cache: %s%n", updatedAnywhereCache.getName());
    }
  }
}

Rust

use google_cloud_lro::Poller;
use google_cloud_storage::client::StorageControl;
use google_cloud_storage::model::AnywhereCache;
use google_cloud_wkt::FieldMask;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let anywhere_cache = AnywhereCache::new()
        .set_name(format!(
            "projects/_/buckets/{}/anywhereCaches/{}",
            bucket_id, cache_id
        ))
        .set_admission_policy("ADMIT_ON_SECOND_MISS".to_string());
    let operation = client
        .update_anywhere_cache()
        .set_anywhere_cache(anywhere_cache)
        .set_update_mask(FieldMask::default().set_paths(["admission_policy"]))
        .poller()
        .until_done()
        .await?;
    println!("Updated anywhere cache: {:?}", operation);
    Ok(())
}

Terraform

Consulte a documentação do Terraform google_storage_anywhere_cache para detalhes sobre como usar o Rapid Cache com o Terraform.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Crie um arquivo JSON que inclua mudanças nas propriedades de cache que você quer atualizar.

    {
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}

    Substitua:

    • TIME_TO_LIVE com o TTL dos dados no cache. O valor pode estar entre 1 e 7 dias, inclusive. O valor pode ser expresso em segundos, minutos, horas e dias. Exemplo:

      • 86400s por 86.400 segundos
      • 1440m por 1.440 minutos
      • 24h por 24 horas
      • 1d por 1 dia

    • INGEST_SETTING com true ou false para especificar se o cache ingere dados na gravação.

      Se definido como true, a ingestão na gravação será ativada para todos os objetos gravados no bucket. Se definido como false, a ingestão na gravação poderá ser ativada seletivamente para objetos gravados em um prefixo ou desativada completamente.

      Para saber mais sobre as configurações usadas para ativar a ingestão na gravação no nível do bucket ou do prefixo, consulte Entenda como ativar a ingestão na gravação.

      Para ativar a ingestão na gravação no nível do bucket ou do prefixo, ou para desativar completamente a ingestão na gravação, use um dos seguintes conjuntos de instruções.

      Ativar a ingestão na gravação para o bucket

      1. Para ativar a ingestão na gravação de todos os objetos gravados no bucket, defina o valor de INGEST_SETTINGS como true.

      2. Siga a etapa 3 para concluir sua solicitação de cache.

      3. Se a ingestão na gravação foi ativada para um prefixo, uma pasta gerenciada com uma configuração rapidCacheConfig existe. Faça uma solicitação de pasta gerenciada PATCH que defina o mapa policies na configuração rapidCacheConfig como null.

      Para instruções detalhadas sobre como usar uma configuração rapidCacheConfig, consulte Atualizar a ingestão na gravação em uma pasta gerenciada.

      Ativar a ingestão na gravação seletivamente para objetos em um prefixo

      1. Defina o valor de INGEST_SETTINGS como false.

      2. Siga a etapa 3 para concluir sua solicitação de cache.

      3. Crie uma pasta gerenciada que use o prefixo como nome, se ela ainda não existir.

      4. Envie uma solicitação de pasta gerenciada PATCH que inclua uma configuração rapidCacheConfig. Defina os valores dos campos na configuração usando as orientações em Configurações e comportamentos de ingestão na gravação.

      O mapa policies de uma configuração rapidCacheConfig pode conter um ou vários IDs de cache (por exemplo, us-east1-a e us-east1-b). Para ativar a ingestão na gravação de determinados caches, defina a configuração ingestOnWrite do cache individual como enabled. Para desativar a ingestão na gravação em determinados caches, defina a configuração ingestOnWrite de cada cache como unspecified. Leia com atenção sobre a herança de ingestão na gravação para entender como uma política de ingestão na gravação de um cache pode ser afetada quando a configuração ingestOnWrite do cache é definida como unspecified.

      Para instruções detalhadas sobre como usar uma configuração rapidCacheConfig, consulte Atualizar a ingestão na gravação em uma pasta gerenciada.

      Desativar a ingestão na gravação

      1. Defina o valor de INGEST_SETTINGS como false. Essa configuração desativa a ingestão na gravação no nível do bucket.

      2. Siga a etapa 3 para concluir sua solicitação de cache.

      3. Para desativar a ingestão na gravação no nível do prefixo, localize a pasta gerenciada em que a ingestão na gravação no nível do prefixo está configurada. Faça uma solicitação de pasta gerenciada PATCH que defina o mapa policies na configuração rapidCacheConfig como null. Ou exclua a configuração rapidCacheConfig do recurso de pasta gerenciada em uma solicitação PATCH.

      Para instruções detalhadas sobre como usar uma configuração rapidCacheConfig, consulte Atualizar a ingestão na gravação em uma pasta gerenciada.

    O exemplo a seguir atualiza o TTL do cache para dois dias e ativa a ingestão na gravação para todos os objetos gravados no bucket:

    {
   "ttl": "172800s",
   "ingestOnWrite": true
}

  3. Para aplicar as novas propriedades, use cURL para chamar a API JSON com uma solicitação para atualizar o cache:

    curl -X PATCH --data-binary @JSON_FILE_NAME \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/RAPID_CACHE_ID"

    Substitua:

    • JSON_FILE_NAME com o nome do arquivo JSON criado na Etapa 2.

    • BUCKET_NAME com o nome do bucket associado ao cache que você quer atualizar. Por exemplo, my-bucket.

    • RAPID_CACHE_ID com o identificador do cache. Por exemplo, us-east1-b.

Se for bem-sucedida, a operação vai retornar um google.longrunning.Operation. É possível ver detalhes sobre a operação de longa duração.

Retomar um cache

Console

Para retomar um cache pausado ou desativado, siga estas instruções:

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado ao cache que você quer retomar.

  3. Na página Detalhes do bucket, clique na guia Configuração.

  4. Na seção Cache rápido, clique em Gerenciar caches.

  5. No painel Gerenciar caches, clique no ícone Retomar cache ().

  6. Clique em Fechar.

Linha de comando

Use o comando gcloud storage buckets anywhere-caches resume:

gcloud storage buckets anywhere-caches resume CACHE_ID

Substitua:

  • CACHE_ID com o identificador da instância de cache, formulado como BUCKET_NAME/CACHE_ZONE. Por exemplo, my-bucket/us-east1-b.

    Para retomar vários caches de uma só vez, especifique vários identificadores. Por exemplo, my-bucket/us-east1-b my-bucket/us-east1-c.

Se for bem-sucedido, o comando vai retornar um recurso AnywhereCache formatado.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  auto anywhere_cache = client.ResumeAnywhereCache(cache_name);
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Resumed anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.ResumeAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class AnywhereCacheResume {

  public static void anywhereCacheResume(String cacheName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      ResumeAnywhereCacheRequest request =
          ResumeAnywhereCacheRequest.newBuilder().setName(cacheName).build();

      AnywhereCache anywhereCache = storageControl.resumeAnywhereCache(request);

      System.out.printf("Resumed anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let cache = client
        .resume_anywhere_cache()
        .set_name(format!(
            "projects/_/buckets/{}/anywhereCaches/{}",
            bucket_id, cache_id
        ))
        .send()
        .await?;
    println!("Resumed anywhere cache: {:?}", cache);
    Ok(())
}

Terraform

Consulte a documentação do Terraform google_storage_anywhere_cache para detalhes sobre como usar o Rapid Cache com o Terraform.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com uma solicitação para retomar um cache:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/RAPID_CACHE_ID/resume"

    Substitua:

    • BUCKET_NAME com o nome do bucket associado ao cache que você quer retomar. Por exemplo, my-bucket.

    • RAPID_CACHE_ID com o identificador do cache. Por exemplo, us-east1-b.

Se for bem-sucedida, a operação vai retornar um recurso AnywhereCache formatado.

Desativar um cache

Console

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket associado ao cache que você quer desativar.

  3. Na página Detalhes do bucket, clique na guia Configuração.

  4. Na seção Rapid Cache, clique em Gerenciar caches.

  5. No painel Gerenciar caches, clique no ícone Desativar cache ().

  6. Na caixa de diálogo que aparece, clique em Confirmar.

  7. Clique em Fechar.

Linha de comando

Use o comando gcloud storage buckets anywhere-caches disable:

gcloud storage buckets anywhere-caches disable CACHE_ID

Substitua:

  • CACHE_ID com o identificador da instância de cache, formulado como BUCKET_NAME/CACHE_ZONE. Por exemplo, my-bucket/us-east1-b.

    Para desativar vários caches de uma só vez, especifique vários identificadores. Por exemplo, my-bucket/us-east1-b my-bucket/us-east1-c.

Se for bem-sucedido, o comando vai retornar um recurso AnywhereCache formatado.

Bibliotecas de cliente

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 

namespace storagecontrol = google::cloud::storagecontrol_v2;
[](storagecontrol::StorageControlClient client,
   std::string const& cache_name) {
  auto anywhere_cache = client.DisableAnywhereCache(cache_name);
  if (!anywhere_cache) throw std::move(anywhere_cache).status();
  std::cout << "Disabled anywhere cache: " << anywhere_cache->name() << "\n";
}

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente. 


import com.google.storage.control.v2.AnywhereCache;
import com.google.storage.control.v2.DisableAnywhereCacheRequest;
import com.google.storage.control.v2.StorageControlClient;
import java.io.IOException;

public final class AnywhereCacheDisable {

  public static void anywhereCacheDisable(String cacheName) throws IOException {
    try (StorageControlClient storageControl = StorageControlClient.create()) {

      DisableAnywhereCacheRequest request =
          DisableAnywhereCacheRequest.newBuilder().setName(cacheName).build();

      AnywhereCache anywhereCache = storageControl.disableAnywhereCache(request);

      System.out.printf("Disabled anywhere cache: %s%n", anywhereCache.getName());
    }
  }
}

Rust

use google_cloud_storage::client::StorageControl;

pub async fn sample(
    client: &StorageControl,
    bucket_id: &str,
    cache_id: &str,
) -> anyhow::Result<()> {
    let cache = client
        .disable_anywhere_cache()
        .set_name(format!(
            "projects/_/buckets/{}/anywhereCaches/{}",
            bucket_id, cache_id
        ))
        .send()
        .await?;
    println!("Disabled anywhere cache: {:?}", cache);
    Ok(())
}

Terraform

Consulte a documentação do Terraform google_storage_anywhere_cache para detalhes sobre como usar o Rapid Cache com o Terraform.

APIs REST

API JSON

  1. Ter a CLI gcloud instalada e inicializada, o que permite gerar um token de acesso para o cabeçalho Authorization.

  2. Use cURL para chamar a API JSON com uma solicitação para desativar um cache:

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/RAPID_CACHE_ID/disable"

    Substitua:

    • BUCKET_NAME com o nome do bucket associado ao cache que você quer desativar. Por exemplo, my-bucket.

    • RAPID_CACHE_ID com o identificador do cache. Por exemplo, us-east1-b.

Se for bem-sucedido, o comando vai retornar um recurso AnywhereCache formatado.

Monitorar o desempenho do cache

A parte do Cloud Storage no console do Google Cloud fornece gráficos de monitoramento que permitem acompanhar o desempenho dos caches usando métricas. Esses gráficos de monitoramento também podem ser visualizados usando o Cloud Monitoring.

Gráficos disponíveis

Gráfico Nível da hierarquia de recursos Descrição
Taxa de remoção de bytes Bucket A taxa de bytes removidos do cache, com amostragem a cada hora. Esses dados são atualizados mais de uma vez por hora para permitir o pós-processamento.
Taxa de remoção de bytes Projeto A taxa de bytes removidos de todos os caches de um bucket, com amostragem a cada hora. Esses dados são atualizados mais de uma vez por hora para permitir o pós-processamento.
Bytes no cache Bucket O número de bytes no cache, com amostragem a cada hora. Esses dados são atualizados mais de uma vez por hora para permitir o pós-processamento.
Bytes no cache Projeto O número de bytes em todos os caches de um bucket, com amostragem a cada hora. Esses dados são atualizados mais de uma vez por hora para permitir o pós-processamento.
Benefício da capacidade de processamento do cache Projeto A taxa da cota de largura de banda de transferência de dados para a região, birregional ou multirregional, o uso da cota e a capacidade de processamento extra disponibilizada pelo cache. A capacidade de processamento extra oferecida pelo cache não é contabilizada na cota. Por isso, os projetos podem exceder a capacidade de processamento permitida pela cota ao usar o cache.
Operações de taxa de acertos Bucket A porcentagem de operações de cache que veiculam os dados solicitados do cache em relação ao total de operações qualificadas para cache, com amostragem a cada 60 segundos. Quando uma leitura é retornada completamente do cache, a operação é considerada um acerto. Quando a leitura não é retornada (ou é retornada só parcialmente) do cache, a operação é considerada um erro.
Operações de taxa de acertos Projeto A porcentagem de operações de cache que veiculam os dados solicitados de todos os caches de um bucket em relação ao total de operações qualificadas para cache, com amostragem de 60 segundos. Quando uma leitura é retornada completamente do cache, a operação é considerada um acerto. Quando a leitura não é retornada (ou é retornada só parcialmente) do cache, a operação é considerada um erro.
Bytes de taxa de hits Bucket A porcentagem de bytes veiculados do cache em relação ao total de bytes qualificados para o cache, com amostragem a cada 60 segundos.
Bytes de taxa de hits Projeto A porcentagem de bytes veiculados de todos os caches de um bucket em relação ao total de bytes qualificados para cache, com amostragem a cada 60 segundos.
Bytes brutos da taxa de ingestão Bucket A taxa de bytes brutos ingeridos em cada cache, com amostras coletadas a cada 60 segundos. Todos os bytes ingeridos, incluindo os não faturáveis, são usados no cálculo do valor dessa métrica. Essa métrica é informada em tempo real.
Bytes brutos da taxa de ingestão Projeto A taxa de bytes brutos ingeridos em todos os caches de um bucket, com amostragem a cada 60 segundos. Todos os bytes ingeridos, incluindo os não faturáveis, são usados no cálculo do valor dessa métrica. Essa métrica é informada em tempo real.
Capacidade de processamento: ocorrência em cache Bucket O throughput veiculado do cache, com amostras coletadas a cada 60 segundos.
Capacidade de processamento: ocorrência em cache Projeto A capacidade de processamento veiculada de todos os caches para um bucket, com amostras coletadas a cada 60 segundos.
Capacidade de processamento: ausência no cache Bucket A capacidade de processamento que não é disponibilizada pelo cache, com amostras coletadas a cada 60 segundos.
Capacidade de processamento: ausência no cache Projeto A capacidade de processamento que não é veiculada por nenhum dos caches de um bucket, com amostras coletadas a cada 60 segundos.

Acessar gráficos

Os gráficos do Monitoring capturam dados de buckets individuais ou de todos os buckets em um projeto. O nível da hierarquia de recursos que um gráfico captura determina onde você pode acessar o gráfico.

Acessar gráficos no nível do bucket

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. Na lista de buckets, clique no nome do bucket para o qual você quer ver gráficos de monitoramento.

  3. Na página Detalhes do bucket, clique na guia Observabilidade.

  4. No menu de navegação, selecione Rapid Cache.

    Os gráficos do Monitoring são exibidos.

Acessar gráficos para envolvidos no projeto

  1. No console do Google Cloud , acesse a página Buckets do Cloud Storage.

    Acessar buckets

  2. No painel de navegação Cloud Storage, clique em Monitoring.

  3. Na barra de menus, clique em Rapid Cache.

    Os gráficos do Monitoring são exibidos.

Usar operações de longa duração

Quando executadas com êxito, as operações AnywhereCaches Create e Update iniciam uma operação de longa duração. É possível receber e listar operações de longa duração para visualizar os detalhes e o status da operação AnywhereCaches subjacente ou cancelar uma operação de longa duração para cancelar a operação AnywhereCaches subjacente enquanto ela está em andamento.

Para instruções sobre como usar operações de longa duração com o Rapid Cache, consulte Usar operações de longa duração.

O exemplo a seguir mostra uma operação de longa duração iniciada em uma operação de criação do AnywhereCaches:

done: false
kind: storage#operation
metadata:
  '@type': type.googleapis.com/google.storage.control.v2.CreateAnywhereCacheMetadata
  anywhereCacheId: us-central1-c
  zone: us-central1-c
  ttl: 172800s
  commonMetadata:
    createTime: '2023-12-14T20:52:00.032Z'
    progressPercent: -1
    requestedCancellation: false
    type: create-anywhere-cache
    updateTime: '2023-12-14T20:52:00.032Z'
name: projects/_/buckets/my-bucket/operations/AULf_KhQxxsWRSn56wv4jfmn3pOu_dKTz9FoYx6S0EzMw5ssR0cXIiorCvHRwqxZnQmWj9jnGpKb3Y6iCD3XM9KLc8EHBm7uig
selfLink: https://www.googleapis.com/storage/v1/b/my-bucket/operations/AULf_KhQxxsWRSn56wv4jfmn3pOu_dKTz9FoYx6S0EzMw5ssR0cXIiorCvHRwqxZnQmWj9jnGpKb3Y6iCD3XM9KLc8EHBm7uig

Novas tentativas

As APIs assíncronas do AnywhereCache são idempotentes por padrão. Isso significa que você pode repetir com segurança chamadas de API assíncronas do AnywhereCaches sem se preocupar em modificar recursos acidentalmente.

Por exemplo, digamos que você execute uma operação AnywhereCaches Create para criar um cache em us-central1-a, que é bem-sucedida. Se você realizar uma operação AnywhereCaches Create subsequente usando a mesma zona que foi bem-sucedida, a solicitação vai retornar a mesma operação de longa duração da solicitação anterior. Esse comportamento só ocorre se você incluir um request_id como parte da solicitação de criação de cache. Se um request_id não for incluído, você vai receber um erro ANYWHERE_CACHE_ALREADY_EXISTS ao tentar criar um cache que já existe. Para saber como incluir um request_id, consulte Identificação de solicitação.

A seguir

Receba recomendações sobre quais buckets e zonas criar um cache.