建立及管理批次作業工作

本頁說明如何建立、查看、列出、取消及刪除儲存空間批次作業工作。本文也會說明如何搭配使用 Cloud 稽核記錄與儲存空間批次作業工作。

事前準備

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

設定 Storage Intelligence

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

設定 Google Cloud CLI

您必須使用 Google Cloud CLI 516.0.0 以上版本。

設定預設專案

設定要建立儲存空間批次作業工作的專案。

gcloud config set project PROJECT_ID

其中 PROJECT_ID 是專案 ID。

啟用 API

啟用 Storage 批次作業 API。

gcloud services enable storagebatchoperations.googleapis.com

建立資訊清單

如要使用資訊清單進行物件選取，請建立資訊清單。

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

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

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

這個預先定義的角色具備建立儲存空間批次作業工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立儲存空間批次作業工作，必須具備下列權限：

建立儲存空間批次作業工作： storagebatchoperations.jobs.create
執行刪除物件的儲存空間批次作業工作： storage.objects.delete
執行更新物件中繼資料、更新物件客戶自行管理的加密金鑰、更新物件內容或更新物件保留儲存空間批次作業工作： storage.objects.update

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

指令列

在 Google Cloud 控制台中啟用 Cloud Shell。

啟用 Cloud Shell

Google Cloud 主控台底部會開啟一個 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。
(選用) 執行模擬測試工作。執行任何工作前，建議您先以模擬測試模式執行工作，驗證物件選取條件並檢查是否有任何錯誤。模擬執行不會修改任何物件。

在開發環境中，執行加上 --dry-run 旗標的 gcloud storage batch-operations jobs create 指令：
```
gcloud storage batch-operations jobs create DRY_RUN_JOB_NAME\
--bucket=BUCKET_NAME OBJECT_SELECTION_FLAG JOB_TYPE_FLAG\
--dry-run
```
模擬執行時使用的參數與實際工作相同。詳情請參閱參數說明。

如要查看試營運結果，請參閱「取得儲存空間批次作業工作詳細資料」。
模擬測試成功後，請執行 gcloud storage batch-operations jobs create 指令。
```
gcloud storage batch-operations jobs create JOB_NAME\
--bucket=BUCKET_NAME OBJECT_SELECTION_FLAG JOB_TYPE_FLAG
```
其中參數如下：
- DRY_RUN_JOB_NAME 是儲存空間批次作業試執行工作的名稱。
- JOB_NAME 是儲存空間批次作業工作的名稱。
  
  注意： 在試執行後建立實際工作時，您必須指定不重複的工作名稱，除非您先明確刪除試執行工作。重複使用試算表工作名稱會導致工作建立失敗，並出現 already exists 錯誤。
- BUCKET_NAME 是包含一或多個要處理物件的值區名稱。
- 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：永久刪除物件。搭配使用這個旗標和 --delete-object 旗標，即可永久刪除 bucket 中的使用中和非現行物件，無論 bucket 的物件版本管理設定為何。
  - --rewrite-object：更新一或多個物件的客戶自行管理的加密金鑰。
  - --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
```
  - --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。如要為物件設定保留設定，您必須在包含該物件的值區中啟用保留功能。
    - RETENTION_MODE 是保留模式，可為 Unlocked 或 Locked。
      
      傳送要求更新 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位時，請注意下列事項：
      - 如要更新物件保留設定，您必須為 RETENTION_MODE 和 RETAIN_UNTIL_TIME 欄位提供非空值；只設定其中一個欄位會導致 INVALID_ARGUMENT 錯誤。
      - 您可以擴充 RETAIN_UNTIL_TIME 值，適用於 Unlocked 或 Locked 模式的物件。
      - 如要執行下列操作，物件保留功能必須處於 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 的內容，並更新或插入鍵為 project-id 和 cost-center 的內容，適用於 manifest.csv 中列出的所有物件：
      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());
}

REST API

JSON API

安裝並初始化 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"
      }
    "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
    },
    "dryRun": DRY_RUN_VALUE
    }
     
```
其中：
- 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 金鑰值。
  - 更新物件中繼資料：
```
"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 錯誤。
      
      您可以擴充 RETAIN_UNTIL_TIME 值，適用於 Unlocked 或 Locked 模式的物件。
      
      如要執行下列操作，物件保留功能必須處於 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，即可刪除所有現有物件內容。
  - DRY_RUN_VALUE 是選用的布林值。設為 true，即可在模擬測試模式下執行工作。預設值為 false。
  提示： 建議您先以模擬測試模式執行作業，再執行實際作業。模擬執行會驗證物件選取條件並檢查錯誤，但不會修改任何物件。
- 使用 cURL 來透過 POST 儲存空間批次作業工作要求呼叫 JSON API：
```
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 錯誤。

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

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

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

這個預先定義的角色具備查看儲存空間批次作業工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要查看儲存空間批次作業工作，必須具備下列權限：

查看 Storage 批次作業工作： storagebatchoperations.jobs.get, storagebatchoperations.operations.get

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

指令列

在 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_ID
```
其中：

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

模擬執行工作時，輸出內容會包含下列欄位：
- 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());
}

REST API

JSON API

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

使用 cURL 透過 GET 儲存空間批次作業工作要求呼叫 JSON API：

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

其中：

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

模擬執行工作時，輸出內容會包含下列欄位：

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

列出 Storage 批次作業工作

本節說明如何列出專案中的 Storage 批次作業工作。

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

這個預先定義的角色具備列出儲存空間批次作業工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要列出儲存空間批次作業工作，必須具備下列權限：

列出 Storage 批次作業工作： storagebatchoperations.jobs.list, storagebatchoperations.operations.list

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

指令列

在 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());
    }
}

REST API

JSON API

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

使用 cURL 透過 LIST 儲存空間批次作業工作要求呼叫 JSON API：

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。

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

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

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

這個預先定義的角色具備取消儲存空間批次作業工作的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要取消儲存空間批次作業工作，必須具備下列權限：

取消儲存空間批次作業工作： storagebatchoperations.jobs.cancel, storagebatchoperations.operations.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_ID
```
其中：

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

用戶端程式庫

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);
}

REST API

JSON API

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

使用 cURL 透過 CANCEL 儲存空間批次作業工作要求呼叫 JSON API：
```
curl -X CANCEL \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_ID"
```
其中：
- PROJECT_ID 是專案的 ID 或編號。例如：my-project。
- JOB_ID 是儲存空間批次作業工作的名稱。

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

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

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

這個預先定義的角色具備刪除儲存空間批次作業工作的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要刪除儲存空間批次作業工作，您必須具備下列權限：

刪除儲存空間批次作業工作： storagebatchoperations.jobs.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_ID
```
其中：

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

用戶端程式庫

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);
}

REST API

JSON API

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

使用 cURL 透過 DELETE 儲存空間批次作業工作要求呼叫 JSON API：
```
curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://storagebatchoperations.googleapis.com/v1/projects/PROJECT_ID/locations/global/jobs/JOB_ID"
```
其中：
- PROJECT_ID 是專案的 ID 或編號。例如：my-project。
- JOB_ID 是儲存空間批次作業工作的名稱。

使用儲存空間分析資料集建立儲存空間批次作業工作

如要使用 Storage Insights 資料集建立儲存空間批次作業工作，請完成下列章節中的步驟。

這個預先定義的角色具備建立儲存空間批次作業工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立儲存空間批次作業工作，必須具備下列權限：

建立儲存空間批次作業工作： storagebatchoperations.jobs.create
執行刪除物件的儲存空間批次作業工作： storage.objects.delete
執行更新物件中繼資料、更新物件客戶自行管理的加密金鑰、更新物件內容或更新物件保留儲存空間批次作業工作： storage.objects.update

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

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

您可以從 BigQuery 擷取資料，為儲存空間批次作業工作建立資訊清單。如要執行這項操作，您需要查詢連結的資料集，將產生的資料匯出為 CSV 檔案，然後儲存至 Cloud Storage 值區。儲存空間批次作業工作隨後可將這個 CSV 檔案做為資訊清單。

在 BigQuery 中對儲存空間分析資料集檢視畫面執行下列 SQL 查詢，即可擷取名稱為 Temp_Training 的物件，且這些物件的大小超過 1 KiB：

  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 是包含資訊清單的值區 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 是值區名稱。例如：my-bucket。
SNAPSHOT_TIME 是儲存空間分析資料集檢視畫面的快照時間。例如：2024-09-10T00:00:00Z。

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

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

指令列

在 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_ID \
--bucket=SOURCE_BUCKET_NAME \
--manifest-location=URI \
--JOB_TYPE_FLAG
```
其中：
- JOB_ID 是儲存空間批次作業工作的名稱。
- SOURCE_BUCKET_NAME 是包含一或多個要處理物件的值區。例如：my-bucket。
- URI 是包含資訊清單的值區 URI。例如，gs://bucket_name/path_to_csv_file/*.csv。使用 *.csv 萬用字元時，BigQuery 會將結果匯出至多個 CSV 檔案。
- JOB_TYPE_FLAG 是下列其中一個旗標，視工作類型而定。
  - --delete-object：刪除一或多個物件。
  - --put-metadata：更新物件中繼資料。物件中繼資料會以鍵/值組合的形式儲存。指定要修改的中繼資料鍵/值組合。您可以將一或多個鍵/值組合指定為清單。您也可以使用 --put-metadata 標記提供物件保留設定。
  - --rewrite-object：更新一或多個物件的客戶自行管理的加密金鑰。
  - --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 的內容，並更新或插入鍵為 project-id 和 cost-center 的內容，適用於 manifest.csv 中列出的所有物件：
      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，為儲存空間批次作業資源提供額外的安全防護。使用 VPC Service Controls 時，您可以將專案加入 service perimeter，防止來自 perimeter 外部的要求存取資源和服務。如要進一步瞭解儲存空間批次作業的 VPC Service Controls 服務邊界詳細資料，請參閱「支援的產品和限制」。

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

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

後續步驟

瞭解儲存空間分析資料集

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

事前準備

設定 Storage Intelligence

設定 Google Cloud CLI

設定預設專案

啟用 API

建立資訊清單

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

所需權限

指令列

用戶端程式庫

C++

PHP

REST API

JSON API

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

所需權限

指令列

用戶端程式庫

C++

PHP

REST API

JSON API

列出 Storage 批次作業工作

所需權限

指令列

用戶端程式庫

C++

PHP

REST API

JSON API

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

所需權限

指令列

用戶端程式庫

C++

PHP

REST API

JSON API

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

所需權限

指令列

用戶端程式庫

C++

PHP

REST API

JSON API

使用儲存空間分析資料集建立儲存空間批次作業工作

所需權限

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

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

指令列

與 VPC Service Controls 整合

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

後續步驟

建立及管理批次作業工作