儲存空間批次作業的 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

Create a storage batch operations job 搭配 LoggingConfig。

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

其中：

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

查看記錄

如要查看儲存空間批次作業記錄，請執行下列操作：

控制台

  1. 前往 Google Cloud 導覽選單 ，依序選取「記錄」>「記錄檔探索工具」 ：<br\></br\>

    前往記錄檔探索工具

  2. 選取 Google Cloud 專案。

  3. 從「升級」選單中，將「舊版記錄檢視器」切換為「記錄檔探索工具」。

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

  5. 在「查詢結果」窗格中，按一下「編輯時間」，即可變更要傳回結果的時間範圍。

如要進一步瞭解如何使用記錄檔探索工具，請參閱「使用記錄檔探索工具」。

指令列

如要使用 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 是您的專案名稱。

Storage 批次作業記錄格式

所有儲存空間批次作業專屬欄位都包含在 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"
}
}

    • 放置中繼資料 (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 Map (key: string, value: string) 轉換後包含 Custom- Metadata 鍵/值組合的對應。這個欄位包含在物件上設定或修改的任何使用者定義中繼資料。可彈性儲存額外中繼資料。