儲存空間批次作業的 Cloud Logging

您可以在 Cloud Logging 中設定及查看儲存空間批次作業記錄。設定 Cloud Logging 時，批次作業工作會為每個轉換工作產生記錄項目，每個項目對應於物件的嘗試轉換。

儲存空間批次作業支援將記錄寫入 Cloud Logging 和 Cloud Storage Cloud 稽核記錄。這兩種選項都會擷取儲存空間批次作業動作，但建議使用 Cloud Logging。Cloud Logging 提供集中式平台，可分析記錄、即時監控及進階篩選，是管理及瞭解批次作業活動的強大解決方案。

事前準備

確認您有權存取 Cloud Logging。如要使用 Cloud Logging，建議您授予 Logs Viewer (roles/logging.viewer) Identity and Access Management 角色。Logs Viewer (roles/logging.viewer) Identity and Access Management 角色提供查看 Cloud Logging 資料所需的 Identity and Access Management 權限。如要進一步瞭解 Logging 存取權限，請參閱「使用 IAM 控管存取權」。

如要驗證及授予 IAM 權限，請完成下列步驟：

瞭解記錄詳細資料

啟用記錄功能後，儲存空間批次作業會擷取下列詳細資料：

  • 可記錄的動作：可記錄的動作值一律為 transform。

  • 可記錄的狀態：針對每項動作，您可以選擇記錄下列其中一種或兩種狀態：

    • SUCCEEDED：動作成功。
    • FAILED：動作失敗。

啟用記錄功能

如要啟用記錄功能，請指定要記錄的動作和狀態。

指令列

使用 gcloud storage batch-operations jobs create 建立儲存空間批次作業工作時，請使用 --log-actions 和 --log-action-states 旗標啟用記錄功能。

gcloud storage batch-operations jobs create JOB_NAME \
  --manifest-location=MANIFEST_LOCATION \
  --delete-object \
  --log-actions=transform \
  --log-action-states=LOG_ACTION_STATES

其中：

  • JOB_NAME 是您要為工作指定的名稱。例如：my-job。
  • MANIFEST_LOCATION 是資訊清單的位置。例如：gs://my-bucket/manifest.csv。
  • LOG_ACTION_STATES 是以半形逗號分隔的清單，包含要記錄的狀態。例如：succeeded,failed。

REST API

使用 LoggingConfig 建立儲存空間批次作業工作。

{
   "loggingConfig": {
      "logActions": ["TRANSFORM"],
      "logActionStates": ["LOG_ACTION_STATES"],
        }
}

其中：

LOG_ACTION_STATES 是以半形逗號分隔的狀態清單，例如："SUCCEEDED","FAILED"。

查看記錄

如要查看儲存空間批次作業記錄，請按照下列步驟操作：

控制台

  1. 前往 Cloud de Confiance 導覽選單，然後依序選取「Logging」>「Logs Explorer」 ：<br\></br\>

    前往「Logs Explorer」(記錄檔探索工具)

  2. 選取 Cloud de Confiance 專案。

  3. 從「升級」選單，從「舊版記錄檢視器」切換至「Logs Explorer」。

  4. 如要篩選記錄，只顯示儲存空間批次作業項目，請在查詢欄位中輸入 storage_batch_operations_job，然後按一下「Run query」(執行查詢)。

  5. 在「Query results」(查詢結果) 窗格中，按一下「Edit time」(編輯時間)，變更要傳回結果的時間範圍。

如要進一步瞭解如何使用 Logs Explorer，請參閱「使用 Logs Explorer」。

指令列

如要使用 gcloud CLI 搜尋儲存空間批次作業記錄，請使用 gcloud logging read 指令。

指定篩選條件，將結果限制為儲存空間批次作業記錄。

gcloud logging read "resource.type=storage_batch_operations_job"

REST API

使用 entries.list Cloud Logging API 方法。

如要篩選結果，只納入與儲存空間批次作業相關的項目，請使用 filter 欄位。以下是 JSON 要求物件範例：

{
"resourceNames":
  [
    "projects/my-project-name"
  ],
  "orderBy": "timestamp desc",
  "filter": "resource.type=\"storage_batch_operations_job\""
}

其中：

my-project-name 是您的專案名稱。

儲存空間批次作業記錄格式

所有儲存空間批次作業專用欄位都包含在 jsonPayload 物件中。雖然 jsonPayload 的確切內容會因工作類型而異，但所有 TransformActivityLog 項目都共用相同的結構。本節會先概略說明常見的記錄檔欄位，然後詳細說明作業專屬欄位。

  • 常見記錄檔欄位

    所有記錄都會顯示下列欄位：

    jsonPayload: {
"@type": "type.googleapis.com/google.cloud.storagebatchoperations.logging.TransformActivityLog",
"completeTime": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
"status": {
  "errorMessage": "String indicating error",
  "errorType": "ENUM_VALUE",
  "statusCode": "ENUM_VALUE"
},
"logName": "projects/PROJECT_ID/logs/storagebatchoperations.googleapis.com%2Ftransform_activity",
"receiveTimestamp": "YYYY-MM-DDTHH:MM:SS.SSSSSSSSSZ",
"resource": {
  "labels": {
    "location":"us-central1",
    "job_id": "BATCH_JOB_ID",
    "resource_container": "RESOURCE_CONTAINER",
    // ... other labels
  },
  "type": "storagebatchoperations.googleapis.com/Job"
},
// Operation-specific details will be nested here (for example,
// "DeleteObject", "PutObjectHold", "RewriteObject", "PutMetadata")
// Each operation-specific object will also contain the following
// object: "objectMetadataBefore": {
//   "gcsObject": {
//     "bucket": "BUCKET_NAME",
//     "generation": "GENERATION_NUMBER",
//     "objectKey": "OBJECT_PATH"
//   }
// }
}

    下表說明各個常見的記錄檔欄位：

    常見記錄欄位 類型 說明
    @type 字串 指定記錄項目酬載的類型，並指出記錄代表儲存空間批次作業的 TransformActivityLog。
    completeTime 時間戳記 作業完成的時間戳記 (符合 ISO 8601 標準)。
    status 物件 提供批次作業活動結果的相關資訊。
    status.errorMessage 字串 如果作業失敗，系統會顯示錯誤訊息。只有在 status.statusCode 值「不是」OK 時，系統才會顯示錯誤訊息。
    status.errorType 字串 錯誤類型。只有在 status.statusCode 值「不是」OK 時，才會顯示錯誤類型。
    status.statusCode 字串 作業的狀態碼。如果值為 OK，表示作業成功；任何其他值則代表失敗。
    logName 字串 記錄的完整資源名稱，指出專案和記錄串流。
    receiveTimestamp 時間戳記 記錄系統收到記錄項目的時間戳記。
    resource 物件 產生記錄項目的資源相關資訊。
    resource.labels 物件 提供資源其他識別資訊的鍵/值組合。
    resource.type 字串 產生記錄的資源類型。
    objectMetadataBefore 物件 包含嘗試批次作業前物件的中繼資料。
    objectMetadataBefore.gcsObject 物件 物件的詳細資料。
    objectMetadataBefore.gcsObject.bucket 字串 物件所在的值區名稱。
    objectMetadataBefore.gcsObject.generation 字串 作業前物件的版本編號。
    objectMetadataBefore.gcsObject.objectKey 字串 bucket 內物件的完整路徑。

  • 作業專屬jsonPayload內容

    不同批次作業的記錄項目差異，在於 jsonPayload 內巢狀結構的頂層物件。在特定記錄項目中，只有下列其中一個物件可用，對應於執行的特定批次作業：

    • 刪除物件 (DeleteObject)

      jsonPayload:
{
"DeleteObject": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  }
  }
}

    • 設定物件保留 (PutObjectHold)

      jsonPayload:
{
"PutObjectHold": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "temporaryHoldAfter": True,
  "eventBasedHoldAfter": True
}
}

    • 重寫物件 (RewriteObject)

      jsonPayload:
{
"RewriteObject": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "kmsKeyVersionAfter": "projects/my-gcp-project/locations/us-central1/keyRings/my-keyring-01/cryptoKeys/my-encryption-key/cryptoKeyVersions/1"
}
}

    • Put 中繼資料 (PutMetadata)

      jsonPayload:
{
"PutMetadata": {
  "objectMetadataBefore": {
    "gcsObject": {
      "bucket": "test-bucket",
      "generation": "1678912345678901",
      "objectKey": "test_object.txt"
    }
  },
  "content_disposition_after": "attachment; filename=\"report_final.pdf\"",
  "content_encoding_after": "gzip",
  "content_language_after": "en-US",
  "content_type_after": "application/pdf",
  "cache_control_after": "public, max-age=3600",
  "custom_time_after": "2025-06-27T10:00:00Z",
  "custom_metadata_after": {
    "project": "marketing",
    "version": "2.0",
    "approvedBy": "Admin"
  }
}
}

    下表說明作業專屬的記錄欄位：

    作業專屬記錄欄位 類型 說明
    PutObjectHold 物件 表示對物件執行保留作業。
    PutObjectHold.temporaryHoldAfter 布林值 如果值為 True，表示儲存空間批次作業工作完成後，物件已套用暫時性保留。有效值為 True 或 False。
    PutObjectHold.eventBasedHoldAfter 布林值 如果值為 True，表示儲存空間批次作業完成後，系統對物件套用了以事件為準的保留措施。有效值為 True 或 False。
    RewriteObject 物件 表示物件的重寫作業。
    RewriteObject.kmsKeyVersionAfter 字串 在重寫作業後使用的 Cloud Key Management Service 金鑰版本。如果物件的加密金鑰因重寫而變更，系統會填入 kmsKeyVersionAfter 欄位。這是選填欄位，也就是說，如果重寫後 Cloud KMS 金鑰版本維持不變，這個欄位可能就不會出現。
    PutMetadata 物件 表示物件的中繼資料更新作業。
    PutMetadata.content_disposition_after 字串 指定 PutMetadata 工作完成後的 Content-Disposition 標頭值。這是選填欄位，只有在設定或修改內容處置方式時才會填入。
    PutMetadata.content_encoding_after 字串 指定 PutMetadata 工作完成後的 Content-Encoding 標頭值。這是選填欄位，只有在設定或修改內容編碼時才會填入。
    PutMetadata.content_language_after 字串 指定 PutMetadata 工作完成後的 Content-Language 標頭值。這是選填欄位，只有在設定或修改內容語言時才會填入。
    PutMetadata.content_type_after 字串 指定 PutMetadata 工作完成後的 Content-Type 標頭值。這是選填欄位，只有在設定或修改內容類型時才會填入。
    PutMetadata.cache_control_after 字串 指定 PutMetadata 工作完成後的 Cache-Control 標頭值。這是選填欄位，只有在設定或修改快取控制項時才會填入。
    PutMetadata.custom_time_after 字串 指定 PutMetadata 工作完成後的 Custom-Time 標頭值。這是選填欄位，只有在設定或修改自訂時間時才會填入。
    PutMetadata.custom_metadata_after 對應 (鍵：字串，值：字串) 包含轉換後的 Custom- Metadata 鍵/值組合對應。這個欄位包含在物件上設定或修改的任何使用者定義中繼資料。可彈性儲存額外的中繼資料。