Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用 Rapid Cache 创建和管理缓存

借助 Rapid Cache，您可以创建基于 SSD 的可用区级缓存实例，从而缩短延迟时间并加快对 Cloud Storage 中存储的对象的访问速度，进而提升应用性能。

本文档介绍了如何使用 Rapid Cache 创建和管理缓存实例。在使用 Rapid Cache 之前，请先查看局限和限制。如需详细了解 Rapid Cache，请参阅 Rapid Cache。

如需了解如何管理 Rapid Cache 异步缓存操作启动的长时间运行的操作，请参阅使用长时间运行的操作。

准备工作

在开始创建和管理缓存之前，请完成以下部分。

获取所需角色

如需获得创建和管理 Rapid Cache 缓存所需的权限，请让您的管理员向您授予与缓存创建关联的存储桶的 Storage Admin (roles/storage.admin) IAM 角色。

此预定义角色包含创建和管理 Rapid Cache 缓存所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要具备以下权限才能创建和管理 Rapid Cache 缓存：

storage.anywhereCaches.create（用于创建缓存）
storage.anywhereCaches.disable（用于停用缓存）
storage.anywhereCaches.get（用于获取缓存）
storage.anywhereCaches.list（用于列出缓存）
storage.anywhereCaches.resume（用于恢复缓存）
storage.anywhereCaches.update（用于更新缓存）
storage.managedFolders.create（仅当为缓存启用写入时注入行为时才需要）
storage.managedFolders.update（仅在更新缓存的写入时注入行为时需要）

您还可以通过自定义角色获得这些权限。

如需了解如何授予存储桶的角色，请参阅设置和管理存储桶的 IAM 政策。

为了管理通过 Rapid Cache 方法启动的长时间运行的操作，您可能还需要其他角色和权限。如需了解详情，请参阅长时间运行的操作所需的角色。

了解写入时注入设置

创建或更新缓存时，您可以选择启用缓存，以便在数据写入存储桶时立即注入数据。此功能称为“写入时注入”。如果您计划使用 JSON API 启用写入时注入，我们建议您先了解用于写入时注入的已配置设置的行为。

创建缓存

控制台

为现有存储桶创建缓存

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击要缓存数据的存储桶的名称。
在存储桶详情页面上，点击配置标签页。
在 Rapid Cache 部分中，点击配置缓存。

系统会显示存储桶的配置缓存页面。
在缓存区域部分中，点击包含您要创建缓存的可用区的区域。
在缓存可用区部分中，选择要创建缓存的可用区。对于您在可用区中创建的每个缓存，可选择完成以下步骤：
- 可选：您可以设置自定义存留时间 (TTL)，以确定数据从上次读取起何时从缓存中逐出。默认情况下，缓存的 TTL 设置为一天。
  
  如需设置自定义 TTL，请执行以下操作：
  1. 在存留时间列中，指定时长值（例如：48）和时间单位（例如：hours）。
  2. 点击 Save configuration（保存配置）。
- 可选：除了在首次读取时注入数据之外，您还可以启用缓存在写入时注入数据。默认情况下，缓存仅配置为在首次读取时注入数据。
  
  如需使缓存能够在写入时注入数据，请执行以下操作：
  1. 在注入条件列中，点击修改缓存注入条件 edit。
    
    系统会显示设置提取条件页面。
  2. 选中写入时注入数据复选框。
    - 如需为新写入存储桶的所有对象启用写入时注入，请点击整个存储桶。
    - 如需仅为名称中具有特定前缀的新写入对象启用写入时注入，请点击所选文件夹，然后输入对象名称前缀。对象名称前缀也称为“文件夹路径”。
    您可以点击添加 add 输入多个对象名称前缀。
    
    如需移除前缀，请点击删除项 delete。
  3. 点击完成。
点击 Save configuration（保存配置）。
在显示的对话框中，点击确认。

存储桶详情页面中的操作标签页随即打开，其中显示了创建缓存操作的作业状态。

为新存储桶创建缓存

如需在创建新存储桶时创建缓存，请按照创建新存储桶中的说明操作。

如需在存储桶列表页面中查看存储桶缓存的状态，请执行以下操作：

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
点击查看列图标 ()，选择缓存，然后点击确定。

命令行

使用 gcloud storage buckets anywhere-caches create 命令：

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

您需要进行如下替换：

将 BUCKET_NAME 替换为要缓存数据的存储桶的名称。例如 my-bucket。
将 CACHE_ZONE 替换为缓存将运行的可用区。例如 us-east1-b。

如需一次创建多个缓存，您可以指定多个可用区。例如，us-east1-b us-east1-c us-east1-d。
将 TTL（可选）替换为缓存中数据的存留时间 (TTL)。该值可以介于 1 天到 7 天之间（含 1 天和 7 天）。该值可以秒、分钟、小时和天为单位。例如：
- 86400s 表示 86,400 秒
- 1440m 表示 1,440 分钟
- 24h 表示 24 小时
- 1d（1 天）
如果未指定，则默认为 86400s（1 天）。

如需将缓存配置为在数据写入存储桶时注入数据，请指定可选的 --enable-ingest-on-write 标志。此标志使缓存能够在所有对象写入存储桶时注入这些对象。

如果成功，该命令会返回与 AnywhereCache Create 操作关联的长时间运行的操作的 ID。您可以获取长时间运行的操作的详细信息，也可以取消长时间运行的操作，以在 AnywhereCaches Create 操作完成之前停止该操作。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需详细了解如何将 Rapid Cache 与 Terraform 搭配使用，请参阅 google_storage_anywhere_cache Terraform 文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。
创建一个包含以下信息的 JSON 文件：
```
{
   "zone": "ZONE",
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}
```
您需要进行如下替换：
- 将 ZONE 替换为缓存将运行的可用区。例如 us-east1-b。
- 将 TIME_TO_LIVE 替换为缓存中数据的存留时间 (TTL)。该值必须以秒为单位表示（例如：172800s 表示 172,800 秒，相当于 2 天）。
  
  最小值为 86400s（1 天），最大值为 604800s（7 天）。如果未指定，则默认为 86400s。
- 将 INGEST_SETTING 替换为 true 或 false，以指定缓存是否会在写入时注入数据。
  
  如果设置为 true，则会为写入存储桶的所有对象启用写入时注入。如果设置为 false，则可以为在某个前缀下写入的对象选择性地启用写入时注入，也可以为整个存储桶停用写入时注入。
  
  如需了解用于配置启用写入时注入的设置，请参阅启用写入时注入的要求。
  
  如需在存储桶级或前缀级启用写入时注入，或完全停用写入时注入，请使用以下一组说明。
  
  为存储桶启用写入时注入
  1. 如需为写入存储桶的所有对象启用写入时注入，请将 INGEST_SETTINGS 的值设置为 true。
  2. 按照第 3 步中的说明完成缓存请求。
  为具有特定前缀的对象选择性地启用写入时注入
  1. 将 INGEST_SETTINGS 的值设置为 false。
  2. 按照第 3 步中的说明完成缓存请求。
  3. 如果托管文件夹尚不存在，请创建托管文件夹，并使用前缀作为名称。
  4. 发送包含 rapidCacheConfig 配置的代管文件夹 PATCH 请求。按照了解如何使用写入时注入中的指南，在配置中设置字段值。
  如需详细了解如何使用 rapidCacheConfig 配置，请参阅更新托管文件夹的写入时注入。
  
  创建缓存而不启用写入时注入
  1. 将 INGEST_SETTINGS 的值设置为 false。
  2. 按照第 3 步中的说明完成缓存请求。

使用 cURL，通过创建缓存请求调用 JSON API：

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"

将

将 JSON_FILE_NAME 替换为您在第 2 步中创建的 JSON 文件的名称。
将 BUCKET_NAME 替换为要缓存数据的存储桶的名称。例如 my-bucket。

如果成功，此操作会返回一个 google.longrunning.Operation。您可以获取长时间运行的操作的详细信息，也可以取消长时间运行的操作，以在 AnywhereCaches Create 操作完成之前停止该操作。

查看缓存

控制台

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击与您要查看的缓存关联的存储桶的名称。
在存储桶详情页面上，点击配置标签页。
在 Rapid Cache 部分，点击缓存字段旁边的修改。
在随即显示的修改配置页面中，选择一个区域以查看该区域的可用区内的所有缓存。

然后，您可以在缓存可用区窗格中查看每个可用缓存的详细信息。

命令行

使用 gcloud storage buckets anywhere-caches describe 命令：

gcloud storage buckets anywhere-caches describe CACHE_ID

您需要进行如下替换：

将 CACHE_ID 替换为缓存实例的标识符，其格式为 BUCKET_NAME/CACHE_ZONE。例如 my-bucket/us-east1-b。

使用可选的 raw 标志输出原始 API 响应，而不是标准化 API 响应。

如果成功，此命令会返回一个 AnywhereCache 资源。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。


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

如需详细了解如何将 Rapid Cache 与 Terraform 搭配使用，请参阅 google_storage_anywhere_cache Terraform 文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。
使用 cURL，通过获取缓存请求调用 JSON API：
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches/RAPID_CACHE_ID"
```
您需要进行如下替换：
- 将 BUCKET_NAME 替换为与要检索的缓存关联的存储桶的名称。例如 my-bucket。
- 将 RAPID_CACHE_ID 替换为缓存所在的可用区。例如 us-east1-b。

如果成功，此操作会返回一个 AnywhereCache 资源。

列出缓存

控制台

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击与您要查看的缓存关联的存储桶的名称。
在存储桶详情页面上，点击配置标签页。
在 Rapid Cache 部分，点击缓存字段旁边的修改。
在随即显示的修改配置页面中，选择一个区域以查看该区域的可用区内的所有缓存。

该区域内可用区的所有可用缓存都显示在缓存可用区窗格中。

命令行

使用 gcloud storage buckets anywhere-caches list 命令：

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

您需要进行如下替换：

将 BUCKET_NAME 替换为与您要列出的缓存关联的存储桶的名称。例如 my-bucket。

如果成功，此命令会返回 AnywhereCache 资源列表。

您可以选择使用 --raw 标志来返回原始 API 响应，而不是标准化响应。如需详细了解如何控制列出行为（例如分页显示结果），请参阅 gcloud storage ls 文档。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。


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

如需详细了解如何将 Rapid Cache 与 Terraform 搭配使用，请参阅 google_storage_anywhere_cache Terraform 文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。
使用 cURL，通过列出缓存请求调用 JSON API：
```
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/anywhereCaches"
```
您需要进行如下替换：
- 将 BUCKET_NAME 替换为与要检索的缓存关联的存储桶的名称。例如 my-bucket。
列出多个缓存时，您可以将结果分页。

如果成功，此操作会返回 AnywhereCache 资源列表。如需详细了解此响应的结构，请参阅 AnywhereCaches List 文档中的响应。

更新缓存

控制台

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击与您要更新的缓存关联的存储桶的名称。
在存储桶详情页面上，点击配置标签页。
在Rapid Cache部分中，点击 管理缓存。
在管理缓存窗格中，点击 修改或创建缓存。
在显示的修改配置页面中，更新缓存的属性：
- 如需更新缓存的 TTL，请找到存留时间列，然后指定时长并选择时间单位（例如分钟）。
- 如需配置缓存的写入时注入行为，包括是缓存写入的所有对象，还是仅缓存写入到某个前缀下的特定对象，请执行以下操作：
  1. 找到提取条件列，然后点击 修改缓存提取条件。
  2. 在设置提取条件窗格中：
  - 如需启用或停用写入时注入，请选中或清除写入时注入数据复选框，然后点击完成。
  - 如需更新缓存以在写入时注入存储桶中的所有对象，请确保选中在写入时注入数据复选框，然后选择整个存储桶。接着，点击完成。
  - 如需更新缓存，使其仅注入名称中包含指定前缀的对象，请确保选中在写入时注入数据复选框，然后选择所选文件夹。
    - 如需指定前缀，请在文件夹路径字段中输入一个或多个前缀，然后点击完成。
    - 如需移除前缀，请点击前缀旁边的删除项 。
在修改配置页面中，点击保存。
在显示的对话框中，点击确认。

命令行

使用 gcloud storage buckets anywhere-caches update 命令：

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

您需要进行如下替换：

将 CACHE_ID 替换为缓存实例的标识符，其格式为 BUCKET_NAME/CACHE_ZONE。例如 my-bucket/us-east1-b。

如需一次更新多个缓存，您可以指定多个标识符。例如 my-bucket/us-east1-b my-bucket/us-east1-c。
将 TTL（可选）替换为缓存中数据的存留时间 (TTL)。该值可以介于 1 天到 7 天之间（含 1 天和 7 天）。该值可以秒、分钟、小时和天为单位。例如：
- 86400s 表示 86,400 秒
- 1440m 表示 1,440 分钟
- 24h 表示 24 小时
- 1d（1 天）

如需将缓存配置为在数据写入存储桶时立即注入数据，请指定 --enable-ingest-on-write 标志。此标志使缓存能够在所有对象写入存储桶时注入这些对象。如需禁止缓存在写入时提取数据，请指定 --no-enable-ingest-on-write 标志。

如果成功，该命令会返回与 AnywhereCache Update 操作关联的原始长时间运行的操作的 ID。您可以获取长时间运行的操作的详细信息。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。


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

如需详细了解如何将 Rapid Cache 与 Terraform 搭配使用，请参阅 google_storage_anywhere_cache Terraform 文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。
创建一个 JSON 文件，其中包含您要更新的缓存属性更改。
```
{
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}
```
您需要进行如下替换：
- 将 TIME_TO_LIVE 替换为缓存中数据的 TTL。该值可以介于 1 天到 7 天之间（含 1 天和 7 天）。该值可以秒、分钟、小时和天为单位。例如：
  - 86400s 表示 86,400 秒
  - 1440m 表示 1,440 分钟
  - 24h 表示 24 小时
  - 1d（1 天）
- 将 INGEST_SETTING 替换为 true 或 false，以指定缓存是否在写入时提取数据。
  
  如果设置为 true，则会为写入存储桶的所有对象启用写入时注入。如果设置为 false，则可以针对在特定前缀下写入的对象选择性地启用写入时注入，也可以完全停用该功能。
  
  如需了解用于在存储桶或前缀级别配置启用写入时注入的设置，请参阅了解如何启用写入时注入。
  
  如需在存储桶级或前缀级启用写入时注入，或完全停用写入时注入，请使用以下一组说明。
  
  为存储桶启用写入时注入
  1. 如需为写入存储桶的所有对象启用写入时注入，请将 INGEST_SETTINGS 的值设置为 true。
  2. 按照第 3 步中的说明完成缓存请求。
  3. 如果之前为某个前缀启用了写入时注入，则存在具有 rapidCacheConfig 配置的代管式文件夹。发出代管式文件夹 PATCH 请求，将 rapidCacheConfig 配置中的 policies 映射设置为 null。
  如需详细了解如何使用 rapidCacheConfig 配置，请参阅更新托管文件夹的写入时注入。
  
  为具有特定前缀的对象选择性地启用写入时注入
  1. 将 INGEST_SETTINGS 的值设置为 false。
  2. 按照第 3 步中的说明完成缓存请求。
  3. 如果托管文件夹尚不存在，请创建托管文件夹，并使用前缀作为名称。
  4. 发送包含 rapidCacheConfig 配置的代管文件夹 PATCH 请求。使用写入时注入设置和行为中的指南在配置中设置字段值。
  rapidCacheConfig 配置的 policies 映射可以包含一个或多个缓存 ID（例如 us-east1-a 和 us-east1-b）。如需为特定缓存启用写入时注入，请将各个缓存的 ingestOnWrite 设置设为 enabled。如需为某些缓存停用写入时注入，请将各个缓存的 ingestOnWrite 设置设为 unspecified。请仔细阅读写入时注入继承，了解当缓存的 ingestOnWrite 设置设为 unspecified 时，缓存的写入时注入政策会受到怎样的影响。
  
  如需详细了解如何使用 rapidCacheConfig 配置，请参阅更新托管文件夹的写入时注入。
  
  停用写入时注入
  1. 将 INGEST_SETTINGS 的值设置为 false。此设置会在存储桶级别停用写入时注入。
  2. 按照第 3 步中的说明完成缓存请求。
  3. 如需在前缀级别停用写入时注入，请找到配置了前缀级别写入时注入的托管式文件夹。发出代管式文件夹 PATCH 请求，将 rapidCacheConfig 配置中的 policies 映射设置为 null。或者，在 PATCH 请求中从托管文件夹资源中删除 rapidCacheConfig 配置。
  如需详细了解如何使用 rapidCacheConfig 配置，请参阅更新托管文件夹的写入时注入。
以下示例将缓存的 TTL 更新为 2 天，并为写入存储桶的所有对象启用写入时注入：
```
{
   "ttl": "172800s",
   "ingestOnWrite": true
}
```
如需应用新属性，请使用 cURL，通过更新缓存请求调用 JSON API：
```
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"
```
您需要进行如下替换：
- 将 JSON_FILE_NAME 替换为您在第 2 步中创建的 JSON 文件的名称。
- 将 BUCKET_NAME 替换为与要更新的缓存关联的存储桶的名称。例如 my-bucket。
- 将 RAPID_CACHE_ID 替换为缓存的标识符。例如 us-east1-b。

如果成功，此操作会返回一个 google.longrunning.Operation。您可以获取长时间运行的操作的详细信息。

恢复缓存

控制台

如需恢复已暂停或停用的缓存，请完成以下步骤：

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击与您要恢复的缓存关联的存储桶的名称。
在存储桶详情页面上，点击配置标签页。
在Rapid Cache部分中，点击 管理缓存。
在管理缓存窗格中，点击恢复缓存图标 ()。
点击关闭。

命令行

使用 gcloud storage buckets anywhere-caches resume 命令：

gcloud storage buckets anywhere-caches resume CACHE_ID

您需要进行如下替换：

将 CACHE_ID 替换为缓存实例的标识符，其格式为 BUCKET_NAME/CACHE_ZONE。例如 my-bucket/us-east1-b。

如需一次恢复多个缓存，您可以指定多个标识符。例如 my-bucket/us-east1-b my-bucket/us-east1-c。

如果成功，该命令会返回一个格式化的 AnywhereCache 资源。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。


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

如需详细了解如何将 Rapid Cache 与 Terraform 搭配使用，请参阅 google_storage_anywhere_cache Terraform 文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。
使用 cURL，通过恢复缓存请求调用 JSON API：
```
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"
```
您需要进行如下替换：
- 将 BUCKET_NAME 替换为与要恢复的缓存关联的存储桶的名称。例如 my-bucket。
- 将 RAPID_CACHE_ID 替换为缓存的标识符。例如 us-east1-b。

如果成功，该操作会返回一个格式化的 AnywhereCache 资源。

停用缓存

控制台

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击与您要停用的缓存关联的存储桶的名称。
在存储桶详情页面上，点击配置标签页。
在Rapid Cache部分中，点击 管理缓存。
在管理缓存窗格中，点击停用缓存图标 ()。
在显示的对话框中，点击确认。
点击关闭。

命令行

使用 gcloud storage buckets anywhere-caches disable 命令：

gcloud storage buckets anywhere-caches disable CACHE_ID

您需要进行如下替换：

将 CACHE_ID 替换为缓存实例的标识符，其格式为 BUCKET_NAME/CACHE_ZONE。例如 my-bucket/us-east1-b。

如需一次停用多个缓存，您可以指定多个标识符。例如 my-bucket/us-east1-b my-bucket/us-east1-c。

如果成功，该命令会返回一个格式化的 AnywhereCache 资源。

客户端库

C++

如需了解详情，请参阅 Cloud Storage C++ API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

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

如需了解详情，请参阅 Cloud Storage Java API 参考文档。

如需向 Cloud Storage 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。


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

如需详细了解如何将 Rapid Cache 与 Terraform 搭配使用，请参阅 google_storage_anywhere_cache Terraform 文档。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。
使用 cURL，通过停用缓存请求调用 JSON API：
```
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"
```
您需要进行如下替换：
- 将 BUCKET_NAME 替换为与要停用的缓存关联的存储桶的名称。例如 my-bucket。
- 将 RAPID_CACHE_ID 替换为缓存的标识符。例如 us-east1-b。

如果成功，该命令会返回一个格式化的 AnywhereCache 资源。

监控缓存性能

Google Cloud 控制台的 Cloud Storage 部分提供了监控图表，可让您使用指标跟踪缓存的性能。您还可以使用 Cloud Monitoring 查看这些监控图表。

可用图表

图表	资源层次结构级层	说明
字节逐出速率	存储桶	从缓存中逐出字节的速率，每小时采样一次。这些数据的刷新间隔时间小于 1 小时，以便系统有时间对数据进行后处理。
字节逐出速率	项目	从存储桶的所有缓存中逐出字节的速率，每小时采样一次。这些数据的刷新间隔时间小于 1 小时，以便系统有时间对数据进行后处理。
缓存中的字节数	存储桶	缓存中的字节数，每小时采样一次。这些数据的刷新间隔时间小于 1 小时，以便系统有时间对数据进行后处理。
缓存中的字节数	项目	存储桶所有缓存中的字节数，每小时采样一次。这些数据的刷新间隔时间小于 1 小时，以便系统有时间对数据进行后处理。
缓存吞吐量优势	项目	该区域、双区域或多区域的数据传输带宽配额、配额用量以及缓存提供的额外吞吐量。缓存提供的额外吞吐量不会计入配额，因此，使用缓存可以让项目超出配额允许的吞吐量。
操作命中率	存储桶	从缓存传送请求数据的缓存操作次数占缓存合格操作总次数的百分比，每 60 秒采样一次。如果读取操作完全从缓存中返回，则计为命中。如果读取操作未从缓存返回或仅从缓存返回了部分数据，则计为未命中。
操作命中率	项目	从存储桶的所有缓存传送请求数据的缓存操作次数占缓存合格操作总次数的百分比，每 60 秒采样一次。如果读取操作完全从缓存中返回，则计为命中。如果读取操作未从缓存返回或仅从缓存返回了部分数据，则计为未命中。
字节命中率	存储桶	从缓存中传送的字节数占缓存合格字节总数的百分比，每 60 秒采样一次。
字节命中率	项目	从存储桶的所有缓存中传送的字节数占缓存合格字节总数的百分比，每 60 秒采样一次。
原始字节注入速率	存储桶	原始字节注入各缓存的速率，每 60 秒采样一次。系统使用所有已注入的字节（包括不计费的字节）来计算此指标的值。此指标实时报告。
原始字节注入速率	项目	原始字节注入存储桶所有缓存的速率，每 60 秒采样一次。系统使用所有已注入的字节（包括不计费的字节）来计算此指标的值。此指标实时报告。
吞吐量 - 缓存命中	存储桶	从缓存中传送的吞吐量，每 60 秒采样一次。
吞吐量 - 缓存命中	项目	从存储桶所有缓存中传送的吞吐量，每 60 秒采样一次。
吞吐量 - 缓存未命中	存储桶	未从缓存中传送的吞吐量，每 60 秒采样一次。
吞吐量 - 缓存未命中	项目	未从存储桶的任何缓存中传送的吞吐量，每 60 秒采样一次。

访问图表

监控图表可以捕获项目中各个存储桶或所有存储桶的数据。图表捕获的资源层次结构级层决定了您可以从哪里访问图表。

访问存储桶级图表

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在存储桶列表中，点击您要查看监控图表的存储桶的名称。
在存储桶详情页面中，点击可观测性标签页。
在导航菜单中，选择 Rapid Cache。

此时会显示监控图表。

访问项目级图表

在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。

进入“存储桶”
在 Cloud Storage 导航窗格中，点击监控。
在菜单栏中，点击 Rapid Cache。

此时会显示监控图表。

使用长时间运行的操作

AnywhereCaches Create 和 Update 操作成功运行后，会启动长时间运行的操作。您可以获取和列出长时间运行的操作，以查看底层 AnywhereCache 操作的详细信息和状态，也可以取消长时间运行的操作，以取消正在进行的底层 AnywhereCache 操作。

如需了解如何在 Rapid Cache 中使用长时间运行的操作，请参阅使用长时间运行的操作。

以下示例展示了从 AnywhereCaches Create 操作启动的长时间运行的操作：

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

重试

默认情况下，异步 AnywhereCache API 具有幂等性。这意味着，您可以放心地重试异步 AnywhereCaches API 调用，而不用担心会意外修改资源。

例如，假设您执行了一个 AnywhereCaches Create 操作以在 us-central1-a 中创建缓存，并且该操作成功。然后，您使用同一可用区再次执行 AnywhereCaches Create 操作，该请求会返回与上一个请求相同的长时间运行的操作。请注意，只有在创建缓存请求中添加 request_id 时，才会出现这种行为。如果未添加 request_id，则在尝试创建已存在的缓存时，您会收到 ANYWHERE_CACHE_ALREADY_EXISTS 错误。如需了解如何添加 request_id，请参阅请求标识。

后续步骤

获取有关为哪些存储桶和可用区创建缓存的建议。

使用 Rapid Cache 创建和管理缓存 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

获取所需角色

所需权限

了解写入时注入设置

创建缓存

控制台

命令行

客户端库

C++

Java

Rust

Terraform

REST API

JSON API

为存储桶启用写入时注入

为具有特定前缀的对象选择性地启用写入时注入

创建缓存而不启用写入时注入

查看缓存

控制台

命令行

客户端库

C++

Java

Rust

Terraform

REST API

JSON API

列出缓存

控制台

命令行

客户端库

C++

Java

Rust

Terraform

REST API

JSON API

更新缓存

控制台

命令行

客户端库

C++

Java

Rust

Terraform

REST API

JSON API

为存储桶启用写入时注入

为具有特定前缀的对象选择性地启用写入时注入

停用写入时注入

恢复缓存

控制台

命令行

客户端库

C++

Java

Rust

Terraform

REST API

JSON API

停用缓存

控制台

命令行

客户端库

C++

Java

Rust

Terraform

REST API

JSON API

监控缓存性能

可用图表

访问图表

访问存储桶级图表

访问项目级图表

使用长时间运行的操作

重试

后续步骤

使用 Rapid Cache 创建和管理缓存