Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Rapid Cache 建立及管理快取

您可以透過 Rapid Cache 建立及管理快取執行個體，減少延遲時間，並為儲存在 Cloud Storage 中的物件最佳化資料存取。這項快取解決方案可加快資料擷取速度，進而提升應用程式效能。

本頁面說明如何使用 Rapid Cache 建立及管理快取執行個體。如要瞭解如何使用及管理從 Rapid Cache 非同步快取作業啟動的長時間執行作業，請參閱「使用長時間執行作業」。

使用 Rapid Cache 前，請先參閱「限制與限制」。

事前準備

開始建立及管理快取之前，請先完成下列章節。

取得必要角色

如要取得建立及管理 Rapid Cache 快取所需的權限，請要求管理員在您要建立快取的 bucket 中，授予您「Storage 管理員」(roles/storage.admin) IAM 角色。

這個預先定義的角色具備建立及管理 Rapid Cache 快取所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及管理 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 (只有在更新快取的寫入時擷取行為時才需要)

您也可以透過自訂角色取得這些權限。

如要瞭解如何授予 bucket 角色，請參閱「在 bucket 上設定及管理 IAM 政策」。

如要管理透過 Rapid Cache 方法啟動的長期執行的作業，您可能需要其他角色和權限。詳情請參閱「長時間執行的作業所需的角色」。

瞭解寫入時擷取設定

建立或更新快取時，您可以選擇啟用快取，在資料寫入 bucket 時立即擷取資料。這項功能稱為「寫入時擷取」。如果您打算使用 JSON API 啟用寫入時擷取功能，建議先瞭解寫入時擷取功能所用設定的行為。

建立快取

控制台

為現有 bucket 建立快取

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選要快取資料的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Configuration」(設定) 分頁標籤。
在「Rapid Cache」部分，按一下「設定快取」。

系統會顯示值區的「設定快取」頁面。
在「快取區域」部分中，按一下包含要建立快取區域的區域。
在「快取區域」部分，選取要建立快取的區域。針對您在可用區中建立的每個快取，您可以選擇完成下列步驟：
- 選用：您可以設定自訂存留時間 (TTL)，決定資料上次讀取後何時會從快取中清除。依預設，快取的存留時間為一天。
  
  如要設定自訂 TTL，請按照下列步驟操作：
  1. 在「存留時間」欄中，指定時間長度值 (例如：48) 和時間單位 (例如：hours)。
  2. 點選 [Save configuration] (儲存設定)。
- 選用：除了在首次讀取時擷取資料，您也可以啟用快取，在寫入時擷取資料。根據預設，快取只會在首次讀取時擷取資料。
  
  如要啟用快取，以便在寫入時擷取資料，請按照下列步驟操作：
  1. 在「擷取條件」欄中，按一下「編輯快取擷取條件」編輯。
    
    「設定擷取條件」頁面隨即顯示。
  2. 勾選「寫入時擷取資料」核取方塊。
    - 如要為新寫入 bucket 的所有物件啟用寫入時擷取功能，請按一下「整個 bucket」。
    - 如要只為名稱含有特定前置字元的新寫入物件啟用寫入時擷取功能，請按一下「選取的資料夾」，然後輸入物件名稱前置字元。物件名稱前置字串也稱為「資料夾路徑」。
    如要輸入多個物件名稱前置字元，請按一下「新增」新增。
    
    如要移除前置字元，請按一下「刪除項目」刪除。
  3. 按一下「完成」。
點選 [Save configuration] (儲存設定)。
在隨即顯示的對話方塊中，按一下「確認」。

「Bucket details」(Bucket 詳細資料) 頁面會開啟「Operations」(作業) 分頁，顯示建立快取作業的工作狀態。

為新 bucket 建立快取

如要在建立新 bucket 時一併建立快取，請按照「建立新 bucket」一文中的操作說明進行。

如要從「值區清單」頁面查看值區的快取狀態，請按照下列步驟操作：

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
按一下「查看資料欄」圖示 ()，選取「快取」，然後按一下「確定」。

指令列

使用 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 天之間 (含頭尾)。值可以秒、分鐘、小時和天為單位表示。例如：
- 86400s 86,400 秒
- 1440m 1,440 分鐘
- 24h 24 小時
- 1d (1 天)
如未指定，則預設為 86400s (1 天)。

如要設定快取，在資料寫入 bucket 時立即擷取資料，請指定選用的 --enable-ingest-on-write 標記。這個旗標可讓快取在物件寫入 bucket 時擷取所有物件。

如果成功，指令會傳回與 AnywhereCache 建立作業相關聯的長時間執行的作業 ID。您可以取得長時間執行的作業詳細資料，或取消長時間執行的作業，在作業完成前停止 AnywhereCaches 建立作業。

用戶端程式庫

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_cacheTerraform 說明文件。

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)。值可以秒、分鐘、小時和天為單位表示。例如：
  - 86400s 86,400 秒
  - 1440m 1,440 分鐘
  - 24h 24 小時
  - 1d (1 天)
  如未指定，則預設為 86400s (1 天)。最大值為 7 天。
- INGEST_SETTING，搭配 true 或 false 使用，指定快取是否要在寫入時擷取資料。
  
  如果設為 true，系統會為寫入 bucket 的所有物件啟用寫入時擷取功能。如果設為 false，您可以為前置字元下寫入的物件選擇性啟用寫入時擷取功能，也可以為整個 bucket 停用這項功能。
  
  如要瞭解用於設定啟用寫入時擷取的設定，請參閱啟用寫入時擷取的規定。
  
  如要在 bucket 層級或前置字元層級啟用寫入時擷取功能，或完全停用這項功能，請使用下列任一組操作說明。
  
  為 bucket 啟用寫入時擷取功能
  1. 如要為寫入值區的所有物件啟用寫入時擷取功能，請將 INGEST_SETTINGS 的值設為 true。
  2. 按照步驟 3 完成快取要求。
  為前置字串下的物件選擇性啟用寫入時擷取功能
  1. 將 INGEST_SETTINGS 的值設為 false。
  2. 按照步驟 3 完成快取要求。
  3. 如果代管資料夾不存在，請建立代管資料夾，並使用前置字元做為名稱。
  4. 傳送代管資料夾 PATCH 要求，其中包含 rapidCacheConfig 設定。請按照「瞭解如何使用寫入時擷取功能」一文中的指引，在設定中設定欄位值。
  如需如何使用 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 建立作業。

查看快取

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選與要查看的快取相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Configuration」(設定) 分頁標籤。
在「Rapid Cache」部分中，按一下「快取」欄位旁邊的「編輯」。
在隨即顯示的「編輯設定」頁面中，選取區域即可查看該區域可用區內的所有快取。

接著，您可以在「快取區域」窗格中查看每個可用快取的詳細資料。

指令列

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

gcloud storage buckets anywhere-caches describe CACHE_ID

更改項目：

CACHE_ID，其中包含快取執行個體的 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_cacheTerraform 說明文件。

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 bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選與要查看的快取相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Configuration」(設定) 分頁標籤。
在「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_cacheTerraform 說明文件。

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 bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選與要更新的快取相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Configuration」(設定) 分頁標籤。
在「Rapid Cache」部分，按一下「管理快取」。
在「管理快取」窗格中，按一下「編輯或建立快取」。
在隨即顯示的「編輯設定」頁面中，更新快取的屬性：
- 如要更新快取的 TTL，請找出「存留時間」欄，然後指定時間長度並選取時間單位 (例如「分鐘」)。
- 如要設定快取的寫入時擷取行為，包括是否要快取所有寫入的物件，或只快取寫入前置字元下的特定物件，請按照下列步驟操作：
  1. 找到「擷取條件」欄，然後按一下「編輯快取擷取條件」。
  2. 在「設定擷取條件」窗格中：
  - 如要啟用或停用寫入時擷取功能，請勾選或取消勾選「Ingest data on write」(寫入時擷取資料) 核取方塊，然後點選「Done」(完成)。
  - 如要更新快取，以便在寫入時擷取 bucket 中的所有物件，請務必選取「在寫入時擷取資料」核取方塊，然後選取「整個 bucket」。然後按一下「完成」。
  - 如要更新快取，只擷取名稱包含指定前置字元的物件，請務必勾選「在寫入時擷取資料」核取方塊，然後選取「所選資料夾」。
    - 如要指定前置字元，請在資料夾路徑欄位中輸入一或多個前置字元，然後按一下「完成」。
    - 如要移除前置字元，請按一下前置字元旁的「刪除項目」。
在「編輯設定」頁面中，按一下「儲存」。
在隨即顯示的對話方塊中，按一下「確認」。

指令列

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

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

更改項目：

CACHE_ID，其中包含快取執行個體的 ID，公式為 BUCKET_NAME/CACHE_ZONE。例如：my-bucket/us-east1-b。

如要一次更新多個快取，可以指定多個 ID。例如：my-bucket/us-east1-b my-bucket/us-east1-c。
TTL (選用) 快取中資料的存留時間 (TTL)。這個值可介於 1 天和 7 天之間 (含頭尾)。值可以秒、分鐘、小時和天為單位表示。例如：
- 86400s 86,400 秒
- 1440m 1,440 分鐘
- 24h 24 小時
- 1d (1 天)

如要設定快取，在資料寫入 bucket 時立即擷取資料，請指定 --enable-ingest-on-write 旗標。這個旗標可讓快取在物件寫入 bucket 時擷取所有物件。如要禁止快取在寫入時擷取資料，請指定 --no-enable-ingest-on-write 旗標。

如果執行成功，指令會傳回與 AnywhereCache 更新作業相關聯的原始長時間執行作業 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_cacheTerraform 說明文件。

REST API

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
建立 JSON 檔案，其中包含要更新的快取屬性變更。
```
{
   "ttl": "TIME_TO_LIVE",
   "ingestOnWrite": INGEST_SETTING
}
```
更改項目：
- TIME_TO_LIVE，其中包含快取中資料的存留時間。這個值可介於 1 天和 7 天之間 (含頭尾)。值可以秒、分鐘、小時和天為單位表示。例如：
  - 86400s 86,400 秒
  - 1440m 1,440 分鐘
  - 24h 24 小時
  - 1d (1 天)
- INGEST_SETTING，搭配 true 或 false，指定快取是否要在寫入時擷取資料。
  
  如果設為 true，系統會為寫入 bucket 的所有物件啟用寫入時擷取功能。如果設為 false，您可以選擇性地為前置字串下寫入的物件啟用寫入時擷取功能，或完全停用這項功能。
  
  如要瞭解用於設定在 Bucket 或前置字元層級啟用寫入時擷取功能的設定，請參閱「瞭解如何啟用寫入時擷取功能」。
  
  如要在 bucket 層級或前置字元層級啟用寫入時擷取功能，或完全停用這項功能，請使用下列任一組操作說明。
  
  為 bucket 啟用寫入時擷取功能
  1. 如要為寫入值區的所有物件啟用寫入時擷取功能，請將 INGEST_SETTINGS 的值設為 true。
  2. 按照步驟 3 完成快取要求。
  3. 如果先前已為前置字元啟用寫入時擷取功能，則會存在具有 rapidCacheConfig 設定的受管理資料夾。發出受管理資料夾 PATCH 要求，將 rapidCacheConfig 設定中的 policies 對應設為 null。
  如需如何使用 rapidCacheConfig 設定的詳細操作說明，請參閱「更新受管理資料夾的寫入時擷取設定」。
  
  為前置字串下的物件選擇性啟用寫入時擷取功能
  1. 將 INGEST_SETTINGS 的值設為 false。
  2. 按照步驟 3 完成快取要求。
  3. 如果代管資料夾不存在，請建立代管資料夾，並使用前置字元做為名稱。
  4. 傳送代管資料夾 PATCH 要求，其中包含 rapidCacheConfig 設定。請按照「寫入時擷取設定和行為」的指引，在設定中設定欄位值。
  rapidCacheConfig 設定的 policies 對應可能包含一或多個快取 ID (例如 us-east1-a 和 us-east1-b)。如要為特定快取啟用寫入時擷取功能，請將個別快取的 ingestOnWrite 設定設為 enabled。如要為特定快取停用寫入時擷取功能，請將個別快取的 ingestOnWrite 設定設為 unspecified。請詳閱寫入時擷取繼承，瞭解快取的寫入時擷取政策在快取的 ingestOnWrite 設定設為 unspecified 時，可能受到的影響。
  
  如需如何使用 rapidCacheConfig 設定的詳細操作說明，請參閱「更新受管理資料夾的寫入時擷取設定」。
  
  停用寫入時擷取功能
  1. 將 INGEST_SETTINGS 的值設為 false。這項設定會停用 bucket 層級的寫入時擷取功能。
  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，這是快取的 ID。例如：us-east1-b。

如果作業成功，會傳回 google.longrunning.Operation。您可以取得長時間執行的作業詳細資料。

恢復快取

控制台

如要恢復已暫停或停用的快取，請完成下列操作說明：

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選與要繼續的快取相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Configuration」(設定) 分頁標籤。
在「Rapid Cache」部分，按一下「管理快取」。
在「管理快取」窗格中，按一下「繼續快取」圖示 ()。
按一下 [關閉]。

指令列

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

gcloud storage buckets anywhere-caches resume CACHE_ID

更改項目：

CACHE_ID，其中包含快取執行個體的 ID，公式為 BUCKET_NAME/CACHE_ZONE。例如：my-bucket/us-east1-b。

如要一次恢復多個快取，可以指定多個 ID。例如：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_cacheTerraform 說明文件。

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，這是快取的 ID。例如：us-east1-b。

如果成功，作業會傳回格式化的 AnywhereCache 資源。

停用快取

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選與要停用快取相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Configuration」(設定) 分頁標籤。
在「Rapid Cache」部分，按一下「管理快取」。
在「管理快取」窗格中，按一下「停用快取」圖示 ()。
在隨即顯示的對話方塊中，按一下「確認」。
按一下 [關閉]。

指令列

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

gcloud storage buckets anywhere-caches disable CACHE_ID

更改項目：

CACHE_ID，其中包含快取執行個體的 ID，公式為 BUCKET_NAME/CACHE_ZONE。例如：my-bucket/us-east1-b。

如要一次停用多個快取，可以指定多個 ID。例如：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_cacheTerraform 說明文件。

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，這是快取的 ID。例如：us-east1-b。

如果成功，指令會傳回格式化的 AnywhereCache 資源。

監控快取效能

Google Cloud 控制台的 Cloud Storage 部分提供監控圖表，可讓您使用指標追蹤快取的效能。您也可以使用 Cloud Monitoring 查看這些監控圖表。

可用的圖表

圖表	資源階層層級	說明
位元組剔除率	值區	每小時取樣一次，從快取中剔除的位元組速率。這項資料每小時更新多次，以便預留時間對資料進行後續處理。
位元組剔除率	專案	bucket 中所有快取剔除位元組的速率，每小時取樣一次。這項資料每小時更新多次，以便預留時間對資料進行後續處理。
快取中的位元組數	值區	快取中的位元組數，每小時取樣一次。這項資料每小時更新多次，以便預留時間對資料進行後續處理。
快取中的位元組數	專案	bucket 中所有快取的位元組數，每小時取樣一次。這項資料每小時更新多次，以便預留時間對資料進行後續處理。
快取處理量效益	專案	區域、雙區域或多區域的資料傳輸頻寬配額比率、配額用量，以及快取提供的額外處理量。快取提供的額外處理量不會計入配額，因此使用快取之後，專案的處理量可以超出配額上限。
命中率作業	值區	這項指標以 60 秒為間隔，顯示符合條件的所有快取作業中，有多少比例的快取作業是透過快取提供所要求的資料。如果讀取內容完全從快取傳回，該項作業會計為「命中」。如果讀取內容只有一部分或並非從快取傳回，該項作業則會計為「失敗」。
命中率作業	專案	這項指標以 60 秒為間隔，顯示符合條件的所有快取作業中，有多少比例的快取作業是透過某個 bucket 的所有快取提供所要求的各項資料。如果讀取內容完全從快取傳回，該項作業會計為「命中」。如果讀取內容只有一部分或並非從快取傳回，該項作業則會計為「失敗」。
命中率 (位元組數)	值區	快取提供的位元組數，在符合條件的快取總位元組數中的占比。每 60 秒取樣一次。
命中率 (位元組數)	專案	某個 bucket 所有快取提供的位元組數，在符合條件的快取總位元組數中的占比，每 60 秒取樣一次。
原始位元組擷取率	值區	各快取擷取原始位元組的速率，每 60 秒取樣一次。所有擷取的位元組 (包括非計費位元組) 都會用於計算這項指標的值。這項指標會即時回報。
原始位元組擷取率	專案	bucket 擷取至所有快取的原始位元組速率，每 60 秒取樣一次。所有擷取的位元組 (包括非計費位元組) 都會用於計算這項指標的值。這項指標會即時回報。
處理量 - 快取命中	值區	快取提供的處理量，每 60 秒取樣一次。
處理量 - 快取命中	專案	某個 bucket 所有快取提供的處理量，每 60 秒取樣一次。
處理量 - 快取失敗	值區	每 60 秒取樣一次，顯示未從快取提供的處理量。
處理量 - 快取失敗	專案	bucket 中任何快取未提供的處理量，每 60 秒取樣一次。

存取圖表

監控圖表會擷取個別 bucket 或專案中所有 bucket 的資料。圖表擷取的資源階層層級，決定了您可以在何處存取圖表。

存取值區層級圖表

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選要查看監控圖表所屬的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面中，按一下「Observability」(可觀測性) 分頁標籤。
在導覽選單中選取「Rapid Cache」。

系統會顯示監控圖表。

存取專案層級圖表

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在「Cloud Storage」導覽窗格中，按一下「Monitoring」。
在選單列中，按一下 Rapid Cache。

系統會顯示監控圖表。

使用長時間執行的作業

成功執行後，「AnywhereCaches Create」和「Update」作業會啟動長時間執行的作業。您可以取得及列出長時間執行的作業，以便查看基礎 AnywhereCaches 作業的詳細資料和狀態，也可以取消長時間執行的作業，以便在基礎 AnywhereCaches 作業進行期間取消該作業。

如需瞭解如何使用長時間執行的作業進行 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

重試次數

非同步 AnywhereCaches API 預設為等冪。也就是說，您可以安全地重試非同步 AnywhereCaches API 呼叫，不必擔心無意間修改資源。

舉例來說，假設您執行 AnywhereCaches Create 作業，在 us-central1-a 中建立快取，且作業成功。如果您使用相同的可用區執行後續的 AnywhereCaches Create 作業並成功，要求會傳回與先前要求相同的長時間執行的作業。請注意，只有在建立快取要求中加入 request_id 時，才會發生這種情況。如果未加入 request_id，嘗試建立已存在的快取時，會收到 ANYWHERE_CACHE_ALREADY_EXISTS 錯誤。如要瞭解如何加入 request_id，請參閱「要求識別資訊」。

後續步驟

取得建議，瞭解要為哪些 bucket 和區域建立快取。

使用 Rapid Cache 建立及管理快取 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

取得必要角色

所需權限

瞭解寫入時擷取設定

建立快取

控制台

指令列

用戶端程式庫

C++

Java

Rust

Terraform

REST API

JSON API

為 bucket 啟用寫入時擷取功能

為前置字串下的物件選擇性啟用寫入時擷取功能

建立快取，但不啟用寫入時擷取功能

查看快取

控制台

指令列

用戶端程式庫

C++

Java

Rust

Terraform

REST API

JSON API

列出快取

控制台

指令列

用戶端程式庫

C++

Java

Rust

Terraform

REST API

JSON API

更新快取

控制台

指令列

用戶端程式庫

C++

Java

Rust

Terraform

REST API

JSON API

為 bucket 啟用寫入時擷取功能

為前置字串下的物件選擇性啟用寫入時擷取功能

停用寫入時擷取功能

恢復快取

控制台

指令列

用戶端程式庫

C++

Java

Rust

Terraform

REST API

JSON API

停用快取

控制台

指令列

用戶端程式庫

C++

Java

Rust

Terraform

REST API

JSON API

監控快取效能

可用的圖表

存取圖表

存取值區層級圖表

存取專案層級圖表

使用長時間執行的作業

重試次數

後續步驟

使用 Rapid Cache 建立及管理快取