物件內容

本文說明如何透過物件脈絡資料，將脈絡資訊與物件建立關聯，以便管理及探索資料。

如要瞭解如何附加及管理物件脈絡資料，請參閱「使用物件脈絡資料」。

總覽

物件脈絡資料可讓您將鍵/值組合與 Cloud Storage 物件建立關聯，以便分類、追蹤及搜尋資料。您可以在建立或更新物件時附加脈絡資料，或讓 Google 服務自動附加。

在 objects 資源中，所有物件情境都會顯示在 contexts.custom 欄位下方。contexts.custom 內有兩種情境：

  • 不含擴充資料的自訂環境：這類環境包含鍵、字串值和時間戳記。您可以使用這些情境，在儲存空間 bucket 中整理、篩選及追蹤物件。

  • 含擴充資料的自訂環境 (預先發布版)：環境包含鍵、字串值、時間戳記，以及選用的結構化 JSON 酬載。Google 服務會在自動分析 (例如機器學習標籤) 期間附加這些情境。

情境元件

每個情境項目都包含下列元件：

  • Key：物件內容的專屬 ID (最多 256 個位元組)。以 google: 開頭的鍵 (例如 google:annotation:face-detector-v1) 預留給 Google 生成的情境。您無法使用 google: 前置字元建立或更新內容。如要移除前置字元為 google: 的結構定義，您必須在重寫作業期間使用 dropContextGroups 參數捨棄這些結構定義。

  • 值：與鍵相關聯的字串值 (最多 256 個位元組)，用於控管工作流程及篩選物件清單。

  • 時間戳記：僅供輸出的時間戳記 (createTime 和 updateTime)，指出情境的建立時間和上次修改時間。

  • 擴充資料 (預先發布版)：選用的結構化 JSON 酬載 (最多 128 KiB)，包含詳細資訊，例如機器學習標籤或自動註解。

標準 get 和 list 要求會傳回內容鍵、值和時間戳記。如果情境含有擴充資料，標準要求會包含 extendedDataTypeUrl 欄位 (type.googleapis.com/google.protobuf.Struct)。如要擷取完整的擴充資料酬載，請使用 viewFullContext 方法 (預先發布版)。

舉例來說，具有自訂情境 (包含和不包含擴充資料) 的物件，其 JSON 表示法如下：

{
  "contexts": {
    "custom": {
      "customer_id": {
        "value": "cust-78901",
        "createTime": "2026-01-01T00:00:00.000Z",
        "updateTime": "2026-01-01T00:00:00.000Z"
      },
      "payment_status": {
        "value": "unpaid",
        "createTime": "2026-01-01T00:00:00.000Z",
        "updateTime": "2026-01-01T00:00:00.000Z"
      },
      "google:annotation:face-detector-v1": {
        "value": "SUCCESS",
        "createTime": "2026-09-29T17:20:00.000Z",
        "updateTime": "2026-09-29T17:20:00.000Z",
        "extendedDataTypeUrl": "type.googleapis.com/google.protobuf.Struct"
      }
    }
  }
}

在這個例子中：

  • customer_id 和 payment_status 是不含擴充資料的自訂情境。
  • google:annotation:face-detector-v1 是 Google 生成的自訂脈絡，包含擴充資料。

您可以擷取所有脈絡資料，並根據鍵和值篩選物件清單。

物件脈絡資料的用途

物件脈絡資料可讓您分類、追蹤及充實資料。以下各節說明使用物件內容管理不同類型資訊的情境。

將物件分組及分類

分類及整理各值區和專案中的物件。使用情境，依屬性 (例如資料集來源、擁有權或成本中心) 標記資料。

  • 範例 1：將情境 data_classification: PII 指派給含有個人識別資訊 (PII) 的物件，以便法規遵循政策處理這些物件。

  • 範例 2：在擷取期間，指派 batch_id: 2025_Q4_Model_Run 情境來分組新的訓練圖片，以便有效率地測試及擷取模型。

追蹤工作流程

如要最佳化自訂工作流程並避免重複作業，請直接將工作流程狀態資訊嵌入物件，追蹤物件在處理管道中的流程。

  • 範例 1：使用 processing_status: awaiting_review 表示等待外部發布核准的物件。

  • 範例 2：使用 processed_by: analytics_pipeline 防止自訂資料處理服務重新掃描已完成某個階段的檔案。

為物件增添應用程式專屬的背景資訊

附加應用程式或業務流程的特定資訊，為每個物件提供額外背景資訊和資料歷程。

  • 範例 1：如果是衛星圖，請記錄擷取詳細資料 (例如 capture_angle: 45deg_NW)，或使用 lineage: ingested_from_s3 追蹤檔案的歷史記錄。

  • 範例 2：嵌入檔案內容的詳細資料，例如 document_type: service_manual 和 vehicle_model: f250。

物件脈絡的優點

物件背景資訊可擴充 Cloud Storage 物件的功能。直接將自訂鍵/值組合與儲存的物件建立關聯，可帶來下列好處：

  • 資料探索：篩選物件清單，將工作負載的輸入內容限制為感興趣的物件。

  • 互通性：支援與其他雲端服務供應商的物件標記互通，並簡化遷移作業，因為物件內容接受未預先定義的字串值。

  • 資料持續性：在物件的整個生命週期中保留比對內容資料。複製、重寫、撰寫、移動或還原物件時，系統會自動轉移背景資訊。如要避免將內容轉移至目的地物件，您也可以在複製、重寫和撰寫作業期間，使用 dropContextGroups 查詢參數 (例如 dropContextGroups=custom) 選擇性捨棄內容。

  • 環境修改控制項：使用 Identity and Access Management (IAM) 權限定義可新增、變更或移除環境的使用者，以維護稽核追蹤記錄。

  • 批次作業：使用儲存空間批次作業，一次管理數十億個物件的物件內容。

  • 使用 BigQuery 進行大量分析：使用物件內容目錄檢視畫面 (object_contexts_catalog_view)，查詢及分析儲存空間分析資料集中的儲存空間值區中的物件內容和擴充資料 (例如標籤、臉部偵測結果和定界框)。

定價

如需定價詳情，請參閱「Cloud Storage 定價」。

後續步驟