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

建立及管理批次作業工作

儲存空間批次作業可讓您執行批次工作，自動化處理 Cloud Storage 物件的大規模工作。您可以建立、查看、列出、取消及刪除這些工作，並使用 Cloud 稽核記錄追蹤管理活動。

事前準備

如要建立及管理儲存空間批次作業，請完成下列各節的步驟。

設定 Storage Intelligence

如要建立及管理儲存空間批次作業工作，請在要執行工作的 bucket 上設定 Storage Intelligence。

啟用 Storage Batch Operations API

啟用 Storage 批次作業 API。

gcloud services enable storagebatchoperations.googleapis.com

建立資訊清單

如要使用資訊清單選取物件，請建立資訊清單檔案。如要選取要在儲存空間批次作業工作中處理的物件，其中一種方法是使用資訊清單。

建立儲存空間批次作業工作

本節說明如何建立儲存空間批次作業工作。

如要取得建立儲存空間批次作業工作所需的權限，請要求管理員授予您專案的儲存空間管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要執行批次作業物件的 bucket 名稱。

系統會開啟「Bucket details」(值區詳細資料) 頁面，並選取「Objects」(物件) 分頁標籤。
按一下「建立批次作業」。
在「Select operation」(選取作業) 窗格中，選擇作業類型：
- 管理物件保留設定：選取「Temporary hold」(暫時保留) 或「Event-based hold」(事件型保留)。詳情請參閱「物件保留」。
- 更新物件中繼資料：如要新增物件中繼資料，請按照下列步驟操作：
  - 如要新增自訂中繼資料，請完成下列步驟：
    1. 在「Key」(金鑰) 欄位中輸入金鑰名稱。
    2. 在「Value」(值) 欄位中，輸入該鍵的值。
    3. 選用：按一下「+ 新增項目」，新增更多鍵/值組合。
  - 如要更新固定鍵中繼資料，請完成下列步驟：
    1. 如要展開「Update fixed-key metadata」(更新固定鍵中繼資料) 專區，請按一下展開箭頭。
    2. 在「Select one or more metadata to update」(選取一或多項要更新的中繼資料) 清單中，選取要編輯的中繼資料項目。
- 更新/輪替加密金鑰：如要使用或更新物件的加密金鑰，請按照下列步驟操作：
  1. 在「Select a Cloud KMS key」(選取 Cloud KMS 金鑰) 清單中，選取客戶自行管理的加密金鑰 (CMEK)。
  2. 選用：選取「切換專案」，從其他專案挑選金鑰，或選取「手動輸入金鑰」填寫詳細資料。
- 刪除物件：如要刪除物件，請執行下列操作：
  1. 檢查是否已啟用物件版本管理功能。
  2. 如果已啟用物件版本管理功能，請選擇下列其中一個刪除選項：
    - 選取「刪除物件的所有版本」，即可移除使用中和非現行的版本。
    - 選取「Permanently delete live versions」(永久刪除使用中的版本)，即可只移除使用中的版本。
    如果未啟用物件版本管理功能，所選物件會永久刪除。
  警告：意外刪除物件可能會導致資料遺失。啟用虛刪除功能，即可復原意外刪除的物件。
點選「下一步」。
在「Name operation & specify objects」(為作業命名並指定物件) 窗格中，執行下列操作：
1. 在「Name」(名稱) 欄位中輸入名稱。
2. 選用：在「Description」(說明) 欄位中輸入說明。
3. 在「Specify objects」(指定物件) 專區中，定義處理 bucket 物件的條件。選擇下列其中一個選項：
  - 「Select all objects」(選取所有物件)：包含 bucket 中的所有物件。
  - 透過前置字串篩選器選取物件：如要使用前置字串篩選器定義物件清單，請按照下列步驟操作：
    1. 在「Enter Prefixes of the objects to be included」(輸入待加入物件的前置字串) 欄位中，輸入前置字串。
    2. 選用：按一下「+ Add prefix」(+ 新增前置字元)，指定其他前置字元。
  - 使用資訊清單 CSV 檔案上傳物件清單：如要使用資訊清單檔案選取物件，請按照下列步驟操作：
    1. 將資訊清單 CSV 檔案上傳至 bucket。這個檔案必須包含「Bucket name」(Bucket 名稱)、「Object key」(物件金鑰) 和「Generation number」(世代編號) 標頭。
    2. 在「Select manifest file mode」(選取資訊清單檔案模式) 清單中，選擇下列其中一個選項：
      - 如果選取「Select a manifest file from Cloud Storage」(選取 Cloud Storage 中的資訊清單檔案)，請按一下「Select a manifest file from Cloud Storage」(選取 Cloud Storage 中的資訊清單檔案) 欄位中的「Browse」(瀏覽)。在隨即顯示的「Select object」(選取物件) 對話方塊中，前往資訊清單 CSV 檔案，然後按一下「Select」(選取)。
      - 如果選取「Select multiple manifest files using wildcard」(使用萬用字元選取多個資訊清單檔案)，請在「Enter manifest file location using wildcard」(使用萬用字元輸入資訊清單檔案位置) 欄位中輸入檔案路徑。例如：bucket-name/folder/manifest_*。
點選「建立」。

指令列

如要定義批次作業工作的物件清單，可以選擇下列其中一種來源設定：

以專案為來源：使用 Storage Insights 資料集設定，指定專案的物件。您可以指定進階篩選器參數，例如 --insights-dataset-config、--target-project、--bucket-filters 和 --object-filters，而不必指定個別 bucket 或前置字串。詳情請參閱「使用進階篩選器建立工作」。
以 bucket 為來源：指定特定 bucket 中的物件。您必須指定下列其中一個旗標：
- --bucket 或 --bucket-list，定義目標 bucket。
- 資訊清單 CSV 檔案 (--manifest-location) 或物件前置字串 (--included-object-prefixes)，用於定義目標物件。

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
使用 Google Cloud CLI 516.0.0 以上版本。
如要設定預設專案，請執行 gcloud config set project 指令：
```
gcloud config set project PROJECT_ID
```
其中 PROJECT_ID 是專案 ID。
選用：執行模擬測試工作。執行任何工作前，建議您先在模擬測試模式下執行工作，驗證物件選取條件並檢查是否有任何錯誤。模擬測試不會修改任何物件。

在開發環境中，執行 gcloud storage batch-operations jobs create 指令並加上 --dry-run 旗標：
```
gcloud storage batch-operations jobs create DRY_RUN_JOB_NAME \
{--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG \
--dry-run
```
其中：
- DRY_RUN_JOB_NAME 是儲存空間批次作業模擬測試工作的名稱。
其他參數與實際工作相同。詳情請參閱參數說明。

如要查看模擬測試結果，請參閱「取得儲存空間批次作業工作詳細資料」。
模擬測試成功後，請執行 gcloud storage batch-operations jobs create 指令。
```
gcloud storage batch-operations jobs create JOB_NAME \
{--bucket=BUCKET | --bucket-list=BUCKET_LIST} OBJECT_SELECTION_FLAG JOB_TYPE_FLAG
```
參數如下：
- JOB_NAME 是儲存空間批次作業工作的名稱。
  
  注意： 建立實際工作時，請指定不重複的工作名稱，或先刪除模擬測試工作。如果重複使用模擬測試的工作名稱，建立作業會失敗，並顯示 already exists 錯誤。
- --bucket：BUCKET 是 bucket 的名稱，其中包含您要處理的物件。
- --bucket-list：BUCKET_LIST 是以半形逗號分隔的清單，列出一或多個 bucket 名稱，其中包含要處理的物件。只要每個 bucket 都已加入 Storage Intelligence 方案，您最多可以指定任何專案中的 1,000 個 bucket。
- OBJECT_SELECTION_FLAG 是下列其中一個必須指定的旗標：
  - --included-object-prefixes：指定一或多個物件前置字串。例如：
    - 如要比對單一前置字元，請使用：--included-object-prefixes='prefix1'。
    - 如要比對多個前置字元，請使用以半形逗號分隔的前置字元清單：--included-object-prefixes='prefix1,prefix2'。
    - 如要納入所有物件，請使用空白前置字串：--included-object-prefixes=''。
  - --manifest-location：指定資訊清單位置。例如：gs://bucket_name/path/object_name.csv。
- JOB_TYPE_FLAG 是您需要指定的下列其中一個旗標，具體取決於工作類型。
  - --delete-object：刪除一或多個物件。
    - 如果 bucket 已啟用物件版本管理功能，現行物件會轉換為非現行狀態，非現行物件則會略過。
    - 如果 bucket 已停用物件版本管理功能，刪除作業會永久刪除物件，並略過非現行物件。
  - --enable-permanent-object-deletion：永久刪除物件。無論 bucket 的物件版本管理設定為何，只要搭配使用這個旗標和 --delete-object 旗標，即可永久刪除 bucket 中的使用中和非現行物件。
  - --rewrite-object：更新一或多個物件的客戶自行管理的加密金鑰。您也可以使用這個旗標，指定 storage-class 鍵來變更物件的儲存空間級別。支援的儲存空間級別包括 STANDARD、NEARLINE、COLDLINE 和 ARCHIVE。例如：--rewrite-object=storage-class=NEARLINE。
    
    注意： 如果變更已啟用 Autoclass 的 bucket 中物件的儲存空間級別，這項操作不會生效。作業會回報成功，但 Cloud Storage 會將物件的儲存空間級別重設為 Autoclass 定義的預設級別。
    注意： 變更物件的儲存空間級別時，系統會重寫物件資料。重寫屬於 A 級作業。視資料的建立時間、位置和儲存空間級別而定，這些作業可能會產生額外費用。詳情請參閱 Cloud Storage 定價。如果為 bucket 啟用物件版本管理功能，Cloud Storage 會將原始物件保留為非現行版本。除非您明確刪除，否則這個版本會一直保留在 bucket 中。
  - --set-object-acls-from-file：修補物件存取控管清單 (ACL)。提供 JSON 或 YAML 檔案，其中包含要為 allUsers 或 allAuthenticatedUsers 等實體新增或更新的授權。例如：--set-object-acls-from-file=acl-updates.yaml 或 --set-object-acls-from-file=acl-updates.json。
    
    更新用的 YAML 檔案結構如下：
```
grants:
  - entity: allAuthenticatedUsers
    role: READER
  remove_entities:
  - allUsers
```
    更新 JSON 檔案的結構如下：
```
{
"grants": [
  {
    "entity": "allAuthenticatedUsers",
    "role": "READER"
  }
],
"remove_entities": [
  "allUsers"
]
}
```
  - --put-object-event-based-hold：啟用事件型物件保留。
  - --no-put-object-event-based-hold：停用事件型物件保留。
  - --put-object-temporary-hold：啟用暫時物件保留。
  - --no-put-object-temporary-hold：停用暫時物件保留。
    
    以下範例說明如何建立工作，將 manifest.csv 中列出的所有物件 Content-Language 中繼資料更新為 en。
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--put-metadata=Content-Language=en
```
    以下範例說明如何建立指定多個 bucket 的工作，將 Content-Language 更新為 en-us：
```
gcloud storage batch-operations jobs create my-job \
--bucket-list=bucket1,bucket2 \
--included-object-prefixes='' \
--put-metadata=Content-Language=en-us
```
  - --put-metadata：更新物件中繼資料。指定要修改的物件中繼資料鍵/值組合。您可以指定一或多個鍵/值組合做為清單。您也可以使用 --put-metadata 旗標設定物件保留設定。如要這麼做，請使用 Retain-Until 和 Retention-Mode 欄位指定保留參數。例如，假設使用者要求系統將文字從英文翻譯成法文
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--put-metadata=Retain-Until=RETAIN_UNTIL_TIME,Retention-Mode=RETENTION_MODE
```
    其中：
    - RETAIN_UNTIL_TIME 是物件保留期限的日期和時間，採用 RFC 3339 格式。例如：2025-10-09T10:30:00Z。如要設定物件的保留設定，您必須啟用物件所在 bucket 的保留功能。
    - RETENTION_MODE 是保留模式，可以是 Unlocked 或 Locked。
      
      傳送要求更新 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位時，請注意下列事項：
      - 如要更新物件保留設定，您必須為 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位提供非空白值；如果只設定其中一個，會導致 INVALID_ARGUMENT 錯誤。
      - 您可以在 Unlocked 或 Locked 模式中，擴充物件的 RETAIN_UNTIL_TIME 值。
      - 如要執行下列操作，物件保留功能必須設為 Unlocked 模式：
        
        降低 RETAIN_UNTIL_TIME 值。
        
        移除保留設定。如要移除設定，請在 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位中提供空白值。
      - 如果同時省略 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位，保留設定會維持不變。
  - --clear-all-object-custom-contexts：刪除所有現有的物件情境。
    
    以下範例說明如何建立工作，清除 manifest.csv 中所列物件的所有物件內容：
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--clear-all-object-custom-contexts
```
    注意： 清除所有物件情境，會刪除物件上所有現有的情境。如要保留先前的物件內容，請啟用 Cloud Logging。記錄中包含更新前的背景資訊，可用於還原先前的值。
  - --clear-object-custom-contexts：移除含有特定鍵的脈絡資料。您也可以使用 --clear-object-custom-contexts 旗標和下列其中一個旗標，更新特定情境並移除索引鍵：
    - --update-object-custom-contexts：提供鍵/值組合的對應關係。
      
      以下範例說明如何建立工作，移除含有 temp-id 鍵的脈絡資料，並為 manifest.csv 中列出的所有物件，更新或插入含有 project-id 和 cost-center 鍵的脈絡資料：
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts=project-id=project-A,cost-center=engineering
      注意： 您無法在 --clear-object-custom-contexts 旗標和 --update-object-custom-contexts 旗標中指定相同的鍵。否則會發生 INVALID_ARGUMENT 錯誤。
    - --update-object-custom-contexts-file：提供 JSON 或 YAML 檔案的路徑，其中包含鍵/值組合。
      
      以下範例說明如何建立工作，處理 manifest.csv 中定義的物件。這項工作會執行下列作業：
      - 移除所有含有 temp-id 鍵的脈絡資料。
      - 使用 /tmp/context_updates.json 檔案中定義的 project-id 和 cost-center 鍵，更新現有情境。
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts-file=/tmp/context_updates.json
      其中 /tmp/context_updates.json 包含下列物件脈絡資料：
      { "project-id": {"value": "project-A"}, "cost-center": {"value": "engineering"} }

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id,
   std::string const& target_bucket_name, std::string const& object_prefix) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  namespace sbo = google::cloud::storagebatchoperations::v1;
  sbo::Job job;
  sbo::BucketList* bucket_list = job.mutable_bucket_list();
  sbo::BucketList::Bucket* bucket_config = bucket_list->add_buckets();
  bucket_config->set_bucket(target_bucket_name);
  sbo::PrefixList* prefix_list_config = bucket_config->mutable_prefix_list();
  prefix_list_config->add_included_object_prefixes(object_prefix);
  sbo::DeleteObject* delete_object_config = job.mutable_delete_object();
  delete_object_config->set_permanent_object_deletion_enabled(false);
  auto result = client.CreateJob(parent, job, job_id).get();
  if (!result) throw result.status();
  std::cout << "Created job: " << result->name() << "\n";
}

PHP

詳情請參閱 Cloud Storage PHP API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\CreateJobRequest;
use Google\Cloud\StorageBatchOperations\V1\Job;
use Google\Cloud\StorageBatchOperations\V1\BucketList;
use Google\Cloud\StorageBatchOperations\V1\BucketList\Bucket;
use Google\Cloud\StorageBatchOperations\V1\PrefixList;
use Google\Cloud\StorageBatchOperations\V1\DeleteObject;

/**
 * Create a new batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 * @param string $bucketName The name of your Cloud Storage bucket to operate on.
 *        (e.g. 'my-bucket')
 * @param string $objectPrefix The prefix of objects to include in the operation.
 *        (e.g. 'prefix1')
 */
function create_job(string $projectId, string $jobId, string $bucketName, string $objectPrefix): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');

    $prefixListConfig = new PrefixList(['included_object_prefixes' => [$objectPrefix]]);
    $bucket = new Bucket(['bucket' => $bucketName, 'prefix_list' => $prefixListConfig]);
    $bucketList = new BucketList(['buckets' => [$bucket]]);

    $deleteObject = new DeleteObject(['permanent_object_deletion_enabled' => false]);

    $job = new Job(['bucket_list' => $bucketList, 'delete_object' => $deleteObject]);

    $request = new CreateJobRequest([
        'parent' => $parent,
        'job_id' => $jobId,
        'job' => $job,
    ]);
    $response = $storageBatchOperationsClient->createJob($request);

    printf('Created job: %s', $response->getName());
}

JSON API

如要定義批次作業工作的物件清單，可以選擇下列其中一種來源設定：

以專案為來源：使用 projectSource 設定，指定整個專案的物件。您不必列出個別 bucket 或前置字串，而是指定進階篩選器參數，動態查詢儲存空間分析中繼資料。詳情請參閱「使用進階篩選器建立工作」中的「JSON API」分頁。
以 bucket 為來源：使用 bucketList 設定，指定特定 bucket 中的物件。您必須指定目標 bucket，以及資訊清單 CSV 檔案 (manifest_location) 或物件前置字串 (include_object_prefixes)。

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

建立 JSON 檔案，其中包含儲存空間批次作業的設定。以下是常見的設定：

{
        "Description": "JOB_DESCRIPTION",
        "BucketList":
        {
        "Buckets":
        [
         {
           "Bucket": "BUCKET_NAME",
           "Manifest": {
              "manifest_location": "MANIFEST_LOCATION"
               }
           "PrefixList": {
              "include_object_prefixes": "OBJECT_PREFIXES"
               }
         }
        ]
        },
        "DeleteObject":
        {
        "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
         }
        "RewriteObject": {
          "kms_key":"KMS_KEY_VALUE",
          "storage_class":"STORAGE_CLASS_VALUE"
          }
        "PutMetadata":{
          "METADATA_KEY": "METADATA_VALUE",
          ...,
          "objectRetention": {
              "retainUntilTime": "RETAIN_UNTIL_TIME",
              "mode": "RETENTION_MODE"
             }
           }
        "PutObjectHold": {
          "temporary_hold": TEMPORARY_HOLD_VALUE,
          "event_based_hold": EVENT_BASED_HOLD_VALUE
        },
        "updateObjectCustomContext": {
           "customContextUpdates": {
              "updates": {
                 "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
              },
              "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
           },
           "clearAll": CLEAR_ALL_VALUE
        },
        "SetObjectAcls": {
           "accessControlsUpdates": {
              "grants": [
                 { "entity": "allUsers", "role": "READER" }
              ],
              "removeEntities": ["allAuthenticatedUsers"]
           }
        },
        "dryRun": DRY_RUN_VALUE
        }

Where:

JOB_NAME 是儲存空間批次作業工作的名稱。
JOB_DESCRIPTION 是儲存空間批次作業工作的說明。
BUCKET_NAME 是值區名稱，其中包含一或多個要處理的物件。
如要指定要處理的物件，請在 JSON 檔案中使用下列任一屬性：
- MANIFEST_LOCATION 是資訊清單位置。例如：gs://bucket_name/path/object_name.csv。
- OBJECT_PREFIXES 是以半形逗號分隔的清單，包含一或多個物件前置字串。如要比對所有物件，請使用空白清單。
視要處理的工作而定，指定下列任一選項：
- 刪除物件：
```
"DeleteObject":
  {
  "permanent_object_deletion_enabled": OBJECT_DELETION_VALUE
  }
```
  其中 OBJECT_DELETION_VALUE 是 TRUE，用於刪除物件。
- 更新物件的客戶自行管理的加密金鑰：
```
"RewriteObject":
  {
  "kms_key": KMS_KEY_VALUE
  }
```
  其中 KMS_KEY_VALUE 是要更新的物件 KMS 金鑰值。
- 更新物件的儲存空間級別：
```
"RewriteObject":
  {
  "storage_class": STORAGE_CLASS_VALUE
  }
```
  其中 STORAGE_CLASS_VALUE 是要將物件轉換至的新儲存空間級別。支援的儲存空間級別包括 STANDARD、NEARLINE、COLDLINE 和 ARCHIVE。
- 更新物件中繼資料：
```
"PutMetadata": {
     "METADATA_KEY": "METADATA_VALUE",
     ...,
    "objectRetention": {
       "retainUntilTime": "RETAIN_UNTIL_TIME",
       "mode": "RETENTION_MODE"
     }
   }
```
  其中：
  - METADATA_KEY/VALUE 是物件的中繼資料鍵/值組合。您可以指定一或多個組合。
  - RETAIN_UNTIL_TIME 是物件保留期限的日期和時間，採用 RFC 3339 格式。例如：2025-10-09T10:30:00Z。如要設定物件的保留設定，您必須啟用物件所在值區的保留功能。
  - RETENTION_MODE 是保留模式，可以是 Unlocked 或 Locked。
    
    傳送要求更新 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位時，請考量下列事項：
    - 如要更新物件保留設定，您必須為 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位提供非空白值；如果只設定其中一個，會導致 INVALID_ARGUMENT 錯誤。
    - 您可以在 Unlocked 或 Locked 模式中，擴充物件的 RETAIN_UNTIL_TIME 值。
    - 如要執行下列操作，物件保留功能必須設為 Unlocked 模式：
      
      降低 RETAIN_UNTIL_TIME 值。
      
      移除保留設定。如要移除設定，請在 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位中提供空白值。
    - 如果同時省略 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位，保留設定會維持不變。
  - 更新物件保留設定：
```
"PutObjectHold": {
    "temporary_hold": TEMPORARY_HOLD_VALUE,
    "event_based_hold": EVENT_BASED_HOLD_VALUE
  }
```
    其中：
    - TEMPORARY_HOLD_VALUE 可啟用或停用暫時物件保留功能。1 值會啟用保留，2 值則會停用保留。
    - EVENT_BASED_HOLD_VALUE 用於啟用或停用事件型物件保留。1 值會啟用保留，2 值則會停用保留。
  - 更新物件結構定義：
```
"updateObjectCustomContext": {
    "customContextUpdates": {
      "updates": {
        "CONTEXT_KEY": { "value": "CONTEXT_VALUE" }
      },
      "keysToClear": ["CONTEXT_KEY_TO_CLEAR"]
    },
    "clearAll": CLEAR_ALL_VALUE
  }
```
    其中：
    - CONTEXT_KEY 是要插入或更新的物件脈絡資料鍵。
    - CONTEXT_VALUE 是鍵的物件情境值。
    - CONTEXT_KEY_TO_CLEAR 是要移除的金鑰。
    - CLEAR_ALL_VALUE 設為 true，可刪除所有現有物件情境。
  - 更新物件存取控制清單 (ACL)：
```
"SetObjectAcls": {
    "accessControlsUpdates": {
       "grants": [
          { "entity": "ENTITY_NAME", "role": "ROLE_NAME" }
       ],
       "removeEntities": ["ENTITY_TO_REMOVE"]
    }
  }
```
    其中：
    - ENTITY_NAME 是要新增或更新存取權的實體，例如 allUsers、allAuthenticatedUsers 或特定使用者/群組。
    - ROLE_NAME 是要授予的角色。例如 READER、OWNER。
    - ENTITY_TO_REMOVE 是要移除憑證的實體。
- DRY_RUN_VALUE 是選用的布林值。設為 true，即可在模擬測試模式下執行工作。預設值為 false。
  
  重要事項： 建議您先以模擬測試模式執行工作，再執行實際工作。模擬測試會驗證物件選取條件並檢查錯誤，不會修改任何物件。
1. 使用 curl 呼叫 JSON API，並傳送 POST 儲存空間批次作業工作要求：
```
curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs?job_id=JOB_NAME"
```
  其中：
  - JSON_FILE_NAME 是 JSON 檔案的名稱。
  - PROJECT_ID 是專案 ID 或編號。例如：my-project。
  - JOB_NAME 是儲存空間批次作業工作的名稱。
    
    注意： 模擬測試後建立實際工作時，除非先明確刪除模擬測試工作，否則必須指定不重複的工作名稱。如果重複使用模擬測試的工作名稱，工作建立作業會失敗，並顯示 already exists 錯誤。

取得儲存空間批次作業工作詳細資料

本節說明如何取得儲存空間批次作業工作的詳細資料。

如要取得查看儲存空間批次作業工作所需的權限，請要求管理員授予您專案的儲存空間管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，按一下與作業相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面中，按一下「Operations」(作業) 分頁標籤。
在作業清單中，按一下要查看的工作「作業 ID」。
詳細資料頁面的「總覽」分頁會顯示工作指標，例如探索到的物件、處理的物件，以及發生的任何錯誤。
在「Error summary」(錯誤摘要) 表格中，查看執行失敗詳情，或按一下「View in Cloud Logging」(在 Cloud Logging 中查看) 查看記錄。
如要查看工作的配置設定，請按一下「Configuration」(設定) 分頁標籤。

指令列

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
在開發環境中執行 gcloud storage batch-operations jobs describe 指令。
```
gcloud storage batch-operations jobs describe JOB_NAME
```
其中：

JOB_NAME 是儲存空間批次作業工作的名稱。

對工作進行模擬測試時，輸出內容會包含下列欄位：
- totalObjectCount：顯示符合選取條件的物件數量。
- errorSummaries：列出模擬測試期間發現的任何錯誤，例如權限問題或無效設定。
- totalBytesFound：顯示受影響物件的總大小。只有在使用物件前置字元選取物件時，才會顯示這個欄位。
如果成功，模擬測試工作的回應會與下列範例類似：
```
  bucketList:
    buckets:
    - bucket: my-bucket
      manifest:
        manifestLocation: gs://my-bucket/manifest.csv
  completeTime: '2025-10-27T23:56:32Z'
  counters:
    totalObjectCount: '4'
  createTime: '2025-10-27T23:56:22.243528568Z'
  dryRun: true
  name: projects/my-project/locations/global/jobs/my-job
  putMetadata:
    contentLanguage: en
  state: SUCCEEDED
```
成功的工作回應會省略 dryRun 欄位，並在 counters 欄位中傳回下列指標：
- 找到的物件總數。
- 使用物件前置字串時找到的位元組總數。
- 成功轉換的物件。
- 失敗的物件轉換 (如適用)。
- 已建立物件情境 (如適用)。
- 刪除物件結構定義 (如適用)。
- 物件脈絡資料已更新 (如適用)。這個計數器會追蹤現有情境金鑰的更新。
實際工作執行的回應會與下列範例類似：
```
  bucketList:
    buckets:
    - bucket: my-bucket
      manifest:
        manifestLocation: gs://my-bucket/manifest.csv
  completeTime: '2025-10-31T20:19:42.357826655Z'
  counters:
    succeededObjectCount: '4'
    totalObjectCount: '4'
  createTime: '2025-10-31T20:19:22.016517077Z'
  name: projects/my-project/locations/global/jobs/my-job
  putMetadata:
    contentLanguage: en
  state: SUCCEEDED
  
```
注意： 如果在模擬測試後修改 bucket 中的物件，實際工作的 totalObjectCount 值可能會與模擬測試結果不同。

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto job = client.GetJob(name);
  if (!job) throw job.status();
  std::cout << "Got job: " << job->name() << "\n";
}

PHP

詳情請參閱 Cloud Storage PHP API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\GetJobRequest;

/**
 * Gets a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function get_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new GetJobRequest([
        'name' => $formattedName,
    ]);

    $response = $storageBatchOperationsClient->getJob($request);

    printf('Got job: %s', $response->getName());
}

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

使用 cURL 呼叫 JSON API，並傳送 GET 儲存空間批次作業工作要求：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"

其中：

PROJECT_ID 是專案 ID 或編號。例如：my-project。
JOB_NAME 是儲存空間批次作業工作的名稱。

對工作進行模擬測試時，輸出內容會包含下列欄位：

totalObjectCount：顯示符合選取條件的物件數量。
errorSummaries：列出模擬測試期間發現的任何錯誤，例如權限問題或無效設定。
totalBytesFound：顯示受影響物件的總大小。只有在使用物件前置字元選取物件時，才會顯示這個欄位。

如果成功，模擬測試的回應會與下列範例相似：

{
  "name": "projects/my-project/locations/global/jobs/my-job",
  "description": "dry-run-job",
  "deleteObject": {
    "permanent_object_deletion_enabled": true
     },
  "createTime": "2025-10-28T00:26:53.900882459Z",
  "completeTime": "2025-10-28T00:27:04.101663275Z",
  "counters": {
      "totalObjectCount": "5",
      "totalBytesFound": "203"
    },
  "state": "SUCCEEDED",
  "bucketList": {
    "buckets": [
      {
        "bucket": "my-bucket",
        "prefixList": {
          "includedObjectPrefixes": [
            ""
          ]
        }
      }
    ]
  },
  "dryRun": true
}

成功的工作回應會省略 dryRun 欄位，並在 counters 欄位中傳回下列指標：

找到的物件總數。
使用物件前置字串時找到的位元組總數。
成功轉換的物件。
失敗的物件轉換 (如適用)。
已建立物件情境 (如適用)。
刪除物件結構定義 (如適用)。

物件脈絡資料已更新 (如適用)。這個計數器會追蹤現有情境金鑰的更新。

實際工作執行的回應會與下列範例類似：

{
"name": "my-job",
"description": "my-delete-objects-job",
"deleteObject": {
  "permanent_object_deletion_enabled": true
},
"createTime": "2025-10-28T00:26:53.900882459Z",
"completeTime": "2025-10-28T00:27:04.101663275Z",
"counters": {
  "succeededObjectCount: "5"
  "totalObjectCount": "5",
  "totalBytesFound": "203"
},
"state": "SUCCEEDED",
"bucketList": {
  "buckets": [
    {
      "bucket": "my-bucket",
      "prefixList": {
        "includedObjectPrefixes": [
          ""
        ]
      }
    }
  ]
}
}

列出 bucket 作業

如果工作包含多個 bucket，您可以查看個別 bucket 的作業進度和狀態。如要列出特定工作對 bucket 執行的作業，請執行 gcloud storage batch-operations bucket-operations list 指令：

gcloud storage batch-operations bucket-operations list --job=JOB_NAME

您也可以使用 --buckets 旗標，篩選出特定 bucket：

gcloud storage batch-operations bucket-operations list --job=JOB_NAME --buckets=BUCKET_NAME_LIST

以下範例說明如何列出工作 my-job 的 bucket1 和 bucket2 作業：

gcloud storage batch-operations bucket-operations list --job=my-job --buckets=bucket1,bucket2

其中：

JOB_NAME 是您建立的儲存空間批次作業工作專屬名稱。例如：my-job。
BUCKET_NAME_LIST 是以半形逗號分隔的值區名稱清單，名稱之間不含空格。例如：bucket1,bucket2。

說明 bucket 作業

如要查看特定 bucket 作業的詳細資料，請使用下列任一方法：

使用 gcloud storage batch-operations bucket-operations describe 指令，並加上作業資源名稱旗標：
```
gcloud alpha storage batch-operations bucket-operations describe BUCKET_OPERATION_RESOURCE_NAME
```
其中：
- BUCKET_OPERATION_RESOURCE_NAME 是 bucket 作業的完整資源路徑。例如：projects/my-project/locations/global/jobs/my-job/bucketOperations/bo-1。
使用 gcloud storage batch-operations bucket-operations describe 指令，並加上作業 bucket 作業 ID 和工作 ID 旗標：
```
gcloud alpha storage batch-operations bucket-operations describe BUCKET_OPERATION_ID --job=JOB_NAME
```
其中：
- BUCKET_OPERATION_ID 是 bucket 作業的 ID。
- JOB_NAME 是您建立的儲存空間批次作業工作專屬名稱。例如：my-job。

列出儲存空間批次作業工作

本節說明如何列出專案中的儲存空間批次作業工作。

如要取得列出儲存空間批次作業工作所需的權限，請要求管理員授予您專案的 Storage 管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，按一下與作業相關聯的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面中，按一下「Operations」(作業) 分頁標籤。「Operations」(作業) 頁面會顯示執行中的作業清單。

指令列

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
在開發環境中執行 gcloud storage batch-operations jobs list 指令。
```
gcloud storage batch-operations jobs list
```

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  for (auto const& job : client.ListJobs(parent)) {
    if (!job) throw job.status();
    std::cout << job->name() << "\n";
  }
}

PHP

詳情請參閱 Cloud Storage PHP API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\ListJobsRequest;

/**
 * List Jobs in a given project.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 */
function list_jobs(string $projectId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');

    $request = new ListJobsRequest([
        'parent' => $parent,
    ]);

    $jobs = $storageBatchOperationsClient->listJobs($request);

    foreach ($jobs as $job) {
        printf('Job name: %s' . PHP_EOL, $job->getName());
    }
}

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

使用 cURL 呼叫 JSON API，並傳送 LIST 儲存空間批次作業要求：

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs"

其中：

PROJECT_ID 是專案 ID 或編號。例如：my-project。

取消儲存空間批次作業工作

本節說明如何取消專案中的儲存空間批次作業。

如要取得取消儲存空間批次作業工作所需的權限，請要求管理員授予您專案的儲存空間管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，按一下與要取消的儲存空間批次作業相關聯的 bucket 名稱。
按一下「作業」分頁標籤。這個分頁會顯示批次作業工作清單。只能取消執行中的工作。
在作業清單中，選取一或多個要取消的工作，然後按一下「Cancel」(取消)。

指令列

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
在開發環境中執行 gcloud storage batch-operations jobs cancel 指令。
```
gcloud storage batch-operations jobs cancel JOB_NAME
```
其中：

JOB_NAME 是儲存空間批次作業工作的名稱。

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto response = client.CancelJob(name);
  if (!response) throw response.status();
  std::cout << "Cancelled job: " << name << "\n";
}

PHP

詳情請參閱 Cloud Storage PHP API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\CancelJobRequest;

/**
 * Cancel a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function cancel_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new CancelJobRequest([
        'name' => $formattedName,
    ]);

    $storageBatchOperationsClient->cancelJob($request);

    printf('Cancelled job: %s', $formattedName);
}

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 呼叫 JSON API，並傳送 CANCEL 儲存空間批次作業工作要求：
```
curl -X CANCEL \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"
```
其中：
- PROJECT_ID 是專案 ID 或編號。例如：my-project。
- JOB_NAME 是儲存空間批次作業工作的名稱。

刪除儲存空間批次作業工作

本節說明如何刪除儲存空間批次作業工作。

如要取得刪除儲存空間批次作業工作所需的權限，請要求管理員授予專案的儲存空間管理員 (roles/storage.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選與要刪除的儲存空間批次作業相關聯的 bucket 名稱。
按一下「作業」分頁標籤。這個分頁會顯示批次作業工作清單。您只能刪除未執行的工作，例如成功、失敗或取消的工作。
在作業清單中，選取一或多個要刪除的工作，然後按一下「Delete」(刪除)。

指令列

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
在開發環境中執行 gcloud storage batch-operations jobs delete 指令。
```
gcloud storage batch-operations jobs delete JOB_NAME
```
其中：

JOB_NAME 是儲存空間批次作業工作的名稱。

用戶端程式庫

C++

詳情請參閱 Cloud Storage C++ API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

[](google::cloud::storagebatchoperations_v1::StorageBatchOperationsClient
       client,
   std::string const& project_id, std::string const& job_id) {
  auto const parent =
      std::string{"projects/"} + project_id + "/locations/global";
  auto const name = parent + "/jobs/" + job_id;
  auto status = client.DeleteJob(name);
  if (!status.ok()) throw status;
  std::cout << "Deleted job: " << name << "\n";
}

PHP

詳情請參閱 Cloud Storage PHP API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

use Google\Cloud\StorageBatchOperations\V1\Client\StorageBatchOperationsClient;
use Google\Cloud\StorageBatchOperations\V1\DeleteJobRequest;

/**
 * Delete a batch job.
 *
 * @param string $projectId Your Google Cloud project ID.
 *        (e.g. 'my-project-id')
 * @param string $jobId A unique identifier for this job.
 *        (e.g. '94d60cc1-2d95-41c5-b6e3-ff66cd3532d5')
 */
function delete_job(string $projectId, string $jobId): void
{
    // Create a client.
    $storageBatchOperationsClient = new StorageBatchOperationsClient();

    $parent = $storageBatchOperationsClient->locationName($projectId, 'global');
    $formattedName = $parent . '/jobs/' . $jobId;

    $request = new DeleteJobRequest([
        'name' => $formattedName,
    ]);

    $storageBatchOperationsClient->deleteJob($request);

    printf('Deleted job: %s', $formattedName);
}

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 呼叫 JSON API，並傳送 DELETE 儲存空間批次作業工作要求：
```
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_NAME"
```
其中：
- PROJECT_ID 是專案 ID 或編號。例如：my-project。
- JOB_NAME 是儲存空間批次作業工作的名稱。

使用 Storage Insights 資料集建立儲存空間批次作業

如要對資料集內列出的物件執行批次作業，請選取下列其中一個選項：

使用進階篩選器：直接在 Google Cloud CLI 指令中，於專案層級動態篩選物件。

儲存空間分析資料集是根據儲存空間中繼資料的定期時間點快照建立而成。每個快照都有快照時間，顯示中繼資料的擷取時間。使用進階篩選器執行批次工作時，這個快照時間會決定要處理哪些物件和版本。根據預設，儲存空間批次作業會自動選取最新的快照時間。為避免對過時資料執行作業，如果所選快照超過兩天，工作建立作業就會失敗。如要瞭解如何解決這項失敗問題，請參閱「排解 Storage 批次作業問題」。
使用資訊清單檔案：執行 BigQuery 查詢來產生 CSV 資訊清單檔案，然後提供給工作。

以下各節將說明這些方法。

使用進階篩選器

您可以使用一般運算語言 (CEL) 篩選器，直接根據儲存空間分析資料集中的欄位選取物件，不必建立資訊清單檔案。您可以在專案中跨多個 bucket 執行工作。使用資料集篩選器選取物件時，儲存空間批次作業會指定所選資料集快照中，目前有效的物件。因此，工作只會包含在快照時 softDeleteTime 和 timeDeleted 的值均為 NULL 的物件。

指令列

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
執行 gcloud storage batch-operations jobs create 指令：
```
gcloud storage batch-operations jobs create JOB_NAME \
{--insights-dataset-config=INSIGHTS_DATASET_CONFIG_RESOURCE_NAME --target-project=TARGET_PROJECT [--bucket-filters=BUCKET_FILTER_CEL] [--object-filters=OBJECT_FILTER_CEL] [--target-locations=TARGET_LOCATIONS] [--target-snapshot-time=TARGET_SNAPSHOT_TIME] | --dry-run-job-id=DRY_RUN_JOB_ID} \
--JOB_TYPE_FLAG
```
其中：
- JOB_NAME 是儲存空間批次作業工作的名稱。
- INSIGHTS_DATASET_CONFIG_RESOURCE_NAME：資料集設定的資源名稱。例如：projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id}。您必須先指定這項參數，才能使用 --bucket-filters 和 --object-filters 旗標。
- TARGET_PROJECT：與目標資源相關聯的專案 ID 或專案編號。
- BUCKET_FILTER_CEL 和 OBJECT_FILTER_CEL (選用)：用於選取物件的 CEL 篩選運算式。以下是相關範例：
  - --bucket-filters="name in ['bucket-1', 'bucket-2']"
  - --object-filters="size >= 5000 && name.endsWith('.pdf')" 如要瞭解支援的欄位、運算子和函式，請參閱 CEL 篩選器參考資料。
- TARGET_LOCATIONS (選用)：用於縮小工作範圍的 Cloud Storage 位置清單。例如：us,us-central1,us-east4。您可以使用這項參數，排除服務中斷的地點。如果只指定 TARGET_LOCATIONS 並省略 TARGET_SNAPSHOT_TIME，工作會自動選擇在所有指定位置的物件和 bucket 屬性檢視表中，成功填入的最新快照時間戳記。
- TARGET_SNAPSHOT_TIME (選用)：要使用的資料集快照 UTC 時間戳記，格式為 RFC 3339。例如，2026-05-03T16:00:00Z。這個快照必須存在於值區和物件屬性檢視中。如果指定這個參數，也必須指定 TARGET_LOCATIONS 參數。
- DRY_RUN_JOB_ID：先前執行的模擬測試工作 ID。如果指定這項參數，就無法指定任何其他物件選取參數，包括 --insights-dataset-config、--target-project、--bucket-filters、--object-filters、--target-locations 和 --target-snapshot-time。有效工作會直接從模擬測試工作輪詢所有選取條件。
- JOB_TYPE_FLAG：與要執行的批次作業相對應的旗標，例如 --put-metadata 或 --delete-object。

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
建立 JSON 設定檔，指定資料集篩選器和大量作業設定。例如：
```
{
    "description": "JOB_DESCRIPTION",
    "projectSource": {
        "project": "projects/TARGET_PROJECT",
        "insightsDatasetConfig": "INSIGHTS_DATASET_CONFIG_RESOURCE_NAME",
        "bucketFilters": {
            "expression": "BUCKET_FILTER_CEL"
        },
        "objectFilters": {
            "expression": "OBJECT_FILTER_CEL"
        },
        "snapshotTime": "SNAPSHOT_TIME",
        "targetLocations": {
            "locations": ["LOCATION_1", "LOCATION_2"]
        }
    },
    "deleteObject": {
        "permanentObjectDeletionEnabled": OBJECT_DELETION_VALUE
    }
 }
```
其中：
- JOB_DESCRIPTION 是工作的說明。
  - TARGET_PROJECT 是與目標物件相關聯的專案 ID 或專案編號。
- INSIGHTS_DATASET_CONFIG_RESOURCE_NAME 是資料集設定的完整資源名稱 (例如 projects/{project-id}/locations/{location-id}/datasetConfigs/{dataset_config_id})。
- BUCKET_FILTER_CEL 是 bucket 的 CEL 篩選運算式。例如，name in ['bucket-1', 'bucket-2']。如要進一步瞭解支援的關鍵字、欄位和運算子，請參閱「CEL 篩選器參考資料」。
- OBJECT_FILTER_CEL 是物件的 CEL 篩選運算式。例如：size >= 5000 && name.endsWith('.pdf')。
- snapshotTime (選用)：RFC 3339 格式的特定世界標準時間戳記 (例如 "2026-05-03T16:00:00Z")，指定要使用的資料集快照。這個快照必須同時存在於所有指定地區的 bucket 和物件資料集檢視畫面中。如果指定這個欄位，也必須指定 targetLocations 欄位。
- targetLocations (選用)：JSON 物件，指定 Cloud Storage 位置清單 (例如 ["us", "us-central1", "us-east4"])，用於篩選工作範圍。如果依附元件在特定位置發生中斷，您可以將工作範圍縮小至特定位置。如果只指定 targetLocations 並省略 snapshotTime，工作會自動選擇最近的快照時間戳記，該時間戳記已成功填入所有指定位置的物件和 bucket 屬性檢視表。
- OBJECT_DELETION_VALUE 是切換永久刪除的布林值。例如：true 或 false。

使用 cURL 傳送 POST 要求，執行工作：

curl -X POST \
     -H "Authorization: Bearer OAUTH2_TOKEN" \
     -H "Content-Type: application/json" \
     -d @JSON_FILE_NAME \
     "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs?job_id=JOB_NAME"

其中：

JSON_FILE_NAME 是 JSON 檔案的名稱。
PROJECT_ID 是專案 ID 或編號。例如：my-project。
JOB_NAME 是儲存空間批次作業工作的名稱。

使用資訊清單檔案

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

使用儲存空間分析資料集建立資訊清單

您可以從 BigQuery 擷取資料，為儲存空間批次作業建立資訊清單。如要這麼做，您需要查詢連結的資料集，將結果資料匯出為 CSV 檔案，並儲存至 Cloud Storage bucket。儲存空間批次作業工作即可使用這個 CSV 檔案做為資訊清單。

在 BigQuery 中對 Storage Insights 資料集檢視表執行下列 SQL 查詢，即可擷取大於 1 KiB 且名稱為 Temp_Training 的物件：

  EXPORT DATA OPTIONS(
   uri=`URI`,
   format=`CSV`,
   overwrite=OVERWRITE_VALUE,
   field_delimiter=',') AS
  SELECT bucket, name, generation
  FROM DATASET_VIEW_NAME
  WHERE bucket = BUCKET_NAME
  AND name LIKE (`Temp_Training%`)
  AND size > 1024 * 1024
  AND snapshotTime = SNAPSHOT_TIME

其中：

URI 是資訊清單所在 bucket 的 URI。例如，gs://bucket_name/path_to_csv_file/*.csv。使用 *.csv 萬用字元時，BigQuery 會將結果匯出至多個 CSV 檔案。
OVERWRITE_VALUE 是布林值。如果設為 true，匯出作業會覆寫指定位置的現有檔案。
DATASET_VIEW_NAME 是儲存空間分析資料集檢視畫面的完整名稱，格式為 PROJECT_ID.DATASET_ID.VIEW_NAME。如要查看資料集名稱，請檢視連結的資料集。

其中：
- PROJECT_ID 是專案 ID 或編號。例如：my-project。
- DATASET_ID 是資料集名稱。例如：objects-deletion-dataset。
- VIEW_NAME 是資料集檢視表的名稱。例如：bucket_attributes_view。
BUCKET_NAME 是 bucket 的名稱。例如：my-bucket。
SNAPSHOT_TIME 是儲存空間分析資料集檢視畫面的快照時間。例如：2024-09-10T00:00:00Z。

使用資訊清單檔案建立儲存空間批次作業工作

如要建立儲存空間批次作業工作，處理資訊清單中的物件，請完成下列步驟：

控制台

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要執行批次作業物件的 bucket 名稱。

系統會開啟「Bucket details」(值區詳細資料) 頁面，並選取「Objects」(物件) 分頁標籤。
按一下「建立批次作業」。
在「Select operation」(選取作業) 窗格中，選擇作業類型：
- 管理物件保留設定：選取「Temporary hold」(暫時保留) 或「Event-based hold」(事件型保留)。詳情請參閱「物件保留」。
- 更新物件中繼資料：如要新增物件中繼資料，請按照下列步驟操作：
  - 如要新增自訂中繼資料，請完成下列步驟：
    1. 在「Key」(金鑰) 欄位中輸入金鑰名稱。
    2. 在「Value」(值) 欄位中，輸入該鍵的值。
    3. 選用：按一下「+ 新增項目」，新增更多鍵/值組合。
  - 如要更新固定鍵中繼資料，請完成下列步驟：
    1. 如要展開「Update fixed-key metadata」(更新固定鍵中繼資料) 專區，請按一下展開箭頭。
    2. 在「Select one or more metadata to update」(選取一或多項要更新的中繼資料) 清單中，選取要編輯的中繼資料項目。
- 更新/輪替加密金鑰：如要使用或更新物件的加密金鑰，請按照下列步驟操作：
  1. 在「Select a Cloud KMS key」(選取 Cloud KMS 金鑰) 清單中，選取客戶自行管理的加密金鑰 (CMEK)。
  2. 選用：選取「切換專案」，從其他專案挑選金鑰，或選取「手動輸入金鑰」填寫詳細資料。
- 刪除物件：如要刪除物件，請執行下列操作：
  1. 檢查是否已啟用物件版本管理功能。
  2. 如果已啟用物件版本管理功能，請選擇下列其中一個刪除選項：
    - 選取「刪除物件的所有版本」，即可移除使用中和非現行的版本。
    - 選取「Permanently delete live versions」(永久刪除使用中的版本)，即可只移除使用中的版本。
    如果未啟用物件版本管理功能，所選物件會永久刪除。
  警告：意外刪除物件可能會導致資料遺失。啟用虛刪除功能，即可復原意外刪除的物件。
點選「下一步」。
在「Name operation & specify objects」(為作業命名並指定物件) 窗格中，執行下列操作：
1. 在「Name」(名稱) 欄位中輸入名稱。
2. 選用：在「Description」(說明) 欄位中輸入說明。
3. 在「Specify objects」(指定物件) 專區中，選取「Upload lists of objects using manifest CSV files」(使用資訊清單 CSV 檔案上傳物件清單)，然後執行下列操作：
  1. 將資訊清單 CSV 檔案上傳至 bucket。這個檔案必須包含「Bucket name」(Bucket 名稱)、「Object key」(物件金鑰) 和「Generation number」(世代編號) 標頭。
  2. 在「Select manifest file mode」(選取資訊清單檔案模式) 清單中，選擇下列其中一個選項：
    - 如果選取「Select a manifest file from Cloud Storage」(選取 Cloud Storage 中的資訊清單檔案)，請按一下「Select a manifest file from Cloud Storage」(選取 Cloud Storage 中的資訊清單檔案) 欄位中的「Browse」(瀏覽)。在隨即顯示的「Select object」(選取物件) 對話方塊中，前往資訊清單 CSV 檔案，然後按一下「Select」(選取)。
    - 如果選取「Select multiple manifest files using wildcard」(使用萬用字元選取多個資訊清單檔案)，請在「Enter manifest file location using wildcard」(使用萬用字元輸入資訊清單檔案位置) 欄位中輸入檔案路徑。例如：bucket-name/folder/manifest_*。
點選「建立」。

指令列

在 Google Cloud 控制台啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。
在開發環境中執行 gcloud storage batch-operations jobs create 指令：
```
gcloud storage batch-operations jobs create \
JOB_NAME \
{--bucket=SOURCE_BUCKET | --bucket-list=SOURCE_BUCKET_LIST} \
--manifest-location=URI \
JOB_TYPE_FLAG
```
其中：
- JOB_NAME 是儲存空間批次作業工作的名稱。
- SOURCE_BUCKET 是含有要處理物件的 bucket 名稱。例如：my-bucket。
- SOURCE_BUCKET_LIST 是以半形逗號分隔的清單，包含一或多個 bucket 名稱，這些 bucket 含有您要處理的物件。例如：bucket1,bucket2。
- URI 是資訊清單所在 bucket 的 URI。例如，gs://bucket_name/path_to_csv_file/*.csv。使用 *.csv 萬用字元時，BigQuery 會將結果匯出至多個 CSV 檔案。
- JOB_TYPE_FLAG 是下列其中一個旗標，視工作類型而定。
  - --delete-object：刪除一或多個物件。
  - --put-metadata：更新物件中繼資料。物件中繼資料會以鍵/值組合的形式儲存。指定要修改的中繼資料鍵/值組合。您可以指定一或多個鍵/值組合做為清單。您也可以使用 --put-metadata 旗標提供物件保留設定。
  - --rewrite-object：更新一或多個物件的客戶自行管理的加密金鑰。您也可以使用這個旗標，指定 storage-class 鍵來變更物件的儲存空間級別。支援的儲存空間級別包括 STANDARD、NEARLINE、COLDLINE 和 ARCHIVE。例如：--rewrite-object=storage-class=NEARLINE。
  - --set-object-acls-from-file：修補物件存取控管清單 (ACL)。提供 JSON 或 YAML 檔案的路徑，其中包含要為 allUsers 或 allAuthenticatedUsers 等實體新增或更新的授權。例如：--set-object-acls-from-file=acl-updates.yaml。
  - --put-object-event-based-hold：啟用事件型物件保留。
  - --no-put-object-event-based-hold：停用事件型物件保留。
  - --put-object-temporary-hold：啟用暫時物件保留。
  - --no-put-object-temporary-hold：停用暫時物件保留。
  - --clear-all-object-custom-contexts：刪除所有現有的物件情境。
    
    以下範例說明如何建立工作，清除 manifest.csv 中所列物件的所有物件內容：
```
gcloud storage batch-operations jobs create my-job \
--bucket=my-bucket \
--manifest-location=gs://my-bucket/manifest.csv \
--clear-all-object-custom-contexts
```
    注意： 清除所有物件情境，會刪除物件上所有現有的情境。如要保留先前的物件內容，請啟用 Cloud Logging。記錄中包含更新前的背景資訊，可用於還原先前的值。
  - --clear-object-custom-contexts：移除含有特定鍵的脈絡資料。您也可以使用 --clear-object-custom-contexts 旗標和下列其中一個旗標，更新特定情境並移除索引鍵：
    - --update-object-custom-contexts：提供鍵/值組合的對應關係。
      
      以下範例說明如何建立工作，移除含有 temp-id 鍵的脈絡資料，並為 manifest.csv 中列出的所有物件，更新或插入含有 project-id 和 cost-center 鍵的脈絡資料：
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts=project-id=project-A,cost-center=engineering
      注意： 您無法在 --clear-object-custom-contexts 旗標和 --update-object-custom-contexts 旗標中指定相同的鍵。否則會發生 INVALID_ARGUMENT 錯誤。
    - --update-object-custom-contexts-file：提供 JSON 或 YAML 檔案的路徑，其中包含鍵/值組合。
      
      以下範例說明如何建立工作，處理 manifest.csv 中定義的物件。這項工作會執行下列作業：
      - 移除所有含有 temp-id 鍵的脈絡資料。
      - 使用 /tmp/context_updates.json 檔案中定義的 project-id 和 cost-center 鍵，更新現有情境。
      gcloud storage batch-operations jobs create my-job \ --bucket=my-bucket \ --manifest-location=gs://my-bucket/manifest.csv \ --clear-object-custom-contexts=temp-id \ --update-object-custom-contexts-file=/tmp/context_updates.json
      其中 /tmp/context_updates.json 包含下列物件脈絡資料：
      { "project-id": {"value": "project-A"}, "cost-center": {"value": "engineering"} }

與 VPC Service Controls 整合

VPC Service Controls 可為儲存空間批次作業資源提供額外一層安全防護。將專案納入 service perimeter，可防止來自 perimeter 外的要求存取資源和服務。如要進一步瞭解儲存空間批次作業的 VPC Service Controls service perimeter 詳細資料，請參閱「支援的產品和限制」。

使用 Cloud 稽核記錄查看儲存空間批次作業

儲存空間批次作業工作會將 Cloud Storage 物件的轉換記錄，儲存在 Cloud Storage 的 Cloud 稽核記錄。如要追蹤這些轉換，請搭配使用 Cloud 稽核記錄和 Cloud Storage。如要瞭解如何啟用稽核記錄，請參閱「啟用稽核記錄」。在稽核記錄項目中，如果 callUserAgent 中繼資料欄位的值為 StorageBatchOperations，表示轉換作業是由儲存空間批次作業執行。

後續步驟

瞭解儲存空間分析資料集

建立及管理批次作業工作 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定 Storage Intelligence

啟用 Storage Batch Operations API

建立資訊清單

建立儲存空間批次作業工作

控制台

指令列

用戶端程式庫

C++

PHP

JSON API

取得儲存空間批次作業工作詳細資料

控制台

指令列

用戶端程式庫

C++

PHP

JSON API

列出 bucket 作業

說明 bucket 作業

列出儲存空間批次作業工作

控制台

指令列

用戶端程式庫

C++

PHP

JSON API

取消儲存空間批次作業工作

控制台

指令列

用戶端程式庫

C++

PHP

JSON API

刪除儲存空間批次作業工作

控制台

指令列

用戶端程式庫

C++

PHP

JSON API

使用 Storage Insights 資料集建立儲存空間批次作業

使用進階篩選器

指令列

JSON API

使用資訊清單檔案

使用儲存空間分析資料集建立資訊清單

使用資訊清單檔案建立儲存空間批次作業工作

控制台

指令列

與 VPC Service Controls 整合

使用 Cloud 稽核記錄查看儲存空間批次作業

後續步驟

建立及管理批次作業工作