管理 object enrichments

設定物件擴充功能後，Cloud Storage 會以非同步方式評估符合條件的物件，並直接將擴充中繼資料附加至儲存的物件。

本頁面說明如何檢查基本內容中繼資料、擷取擴充資料酬載、捨棄物件中的擴充資料，以及在 Cloud Monitoring 中監控處理進度。

取得必要角色

如要取得查看、擷取及捨棄物件擴充所需的權限，請要求管理員授予您 bucket 或專案的下列 IAM 角色：

• 查看基本物件擴充中繼資料：Storage 物件檢視者 (roles/storage.objectViewer)
• 擷取 object enrichments 擴充資料：Storage 物件使用者 (roles/storage.objectUser)
• 在物件重寫期間捨棄 object enrichments：Storage 物件管理員 (roles/storage.objectAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備查看、擷取及捨棄 object enrichments 所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要查看、擷取及捨棄物件擴充功能，必須具備下列權限：

• 查看基本物件擴充內容中繼資料： storage.objects.get
• 擷取物件擴充資料： storage.objects.viewFullContext
• 在物件重寫期間捨棄 object enrichments：
  • storage.objects.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.update

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

查看 object enrichments

Cloud Storage 會將擴充中繼資料直接附加至物件，做為 contexts.custom 屬性下由 Google 管理的物件內容。每個模型都會使用前置字串為 google:annotation: 的保留鍵 (例如 google:annotation:label-detector-v1 或 google:annotation:face-detector-v1)。

Cloud Storage 將擴充資料分為兩個層級：

• 內容中繼資料：包含內容鍵、模型執行狀態 (value)、時間戳記和 protobuf 類型網址。標準物件 describe 和 get 作業會傳回這項中繼資料。
• 擴充資料 (預先發布版)：包含完整的結構化 JSON 擴充酬載 (最多 128 KiB)。這個酬載包含定界多邊形座標、分類信賴分數、臉部表情和安全評分等詳細資料。

查看基本情境中繼資料

如要查看哪些模型已處理物件，並查看基本情境中繼資料，請使用 Cloud de Confiance 控制台或 JSON API：

擷取擴充資料

如要擷取完整的結構化擴充資料 (例如定界框、邊界多邊形、標籤或偵測到的臉部)，請使用 JSON API 呼叫 viewFullContext 方法 (預覽版)。

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

2. 使用 cURL 將 viewFullContext 要求傳送至 JSON API，並指定要檢查的模型情境金鑰：

   curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Accept: application/json" \
     "https://storage.s3nsapis.fr/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME/viewFullContext?contextKey=CONTEXT_KEY"

   其中：

   • BUCKET_NAME 是包含物件的值區名稱。例如：my-bucket。
   • OBJECT_NAME 是物件的網址編碼名稱。例如：image.jpg。
   • CONTEXT_KEY 是模型內容鍵。例如：google:annotation:label-detector-v1。

   回應包含 extendedData 結構，以及完整的擴充酬載：

   {
     "kind": "storage#objectFullContext",
     "type": "CUSTOM",
     "key": "google:annotation:label-detector-v1",
     "value": "SUCCESS",
     "createTime": "2026-09-29T17:20:00.000Z",
     "updateTime": "2026-09-29T17:20:00.000Z",
     "extendedData": {
       "@type": "type.googleapis.com/google.protobuf.Struct",
       "modelName": "label-detector",
       "modelVersion": "v1",
       "labelAnnotationGroup": {
         "labelAnnotations": [
           {
             "description": "Night",
             "knowledgeGraphId": "/m/01d74z",
             "score": 0.92,
             "topicality": 0.19
           }
         ]
       }
     }
   }
   

如需各模型的詳細 JSON 結構定義和欄位，請參閱「支援的模型和結構定義」。

捨棄 object enrichments

如需遵守資料保留政策，或不再需要擴充中繼資料，可以從物件中捨棄。

Google 會管理開頭為 google: 前置字串的情境金鑰，因此您無法使用標準中繼資料更新方法修改或刪除這些金鑰。您可以在物件重寫、複製或組合作業期間，指定 dropContextGroups=custom 參數來捨棄物件，這會捨棄物件上的所有物件內容。

如要使用 JSON API 重寫物件，並捨棄物件內容 (包括 object enrichments)，請按照下列步驟操作：

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

2. 使用 cURL 呼叫 JSON API，並傳送 POST 重寫物件要求和 dropContextGroups=custom 查詢參數：

   curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Length: 0" \
     "https://storage.s3nsapis.fr/storage/v1/b/SOURCE_BUCKET/o/SOURCE_OBJECT/rewriteTo/b/DESTINATION_BUCKET/o/DESTINATION_OBJECT?dropContextGroups=custom"

   其中：

   • SOURCE_BUCKET 是包含來源物件的值區名稱。例如：my-source-bucket。
   • SOURCE_OBJECT 是來源物件的網址編碼名稱。例如：image.jpg。
   • DESTINATION_BUCKET 是目的地 bucket 的名稱 (可與來源 bucket 相同)。例如：my-source-bucket。
   • DESTINATION_OBJECT 是目的地物件的網址編碼名稱 (可與來源物件相符)。例如：image.jpg。

如要管理及捨棄數十億個物件的內容，請參閱「大量管理物件內容」。

監控 object enrichments 指標

您可以使用 Cloud Monitoring 追蹤擴充處理量、待處理物件和模型執行次數。Cloud Storage 會在gcs_bucket受監控資源的 storage.googleapis.com 命名空間下，匯出下列指標：

指標類型 (前置字元為 storage.googleapis.com/)	種類和類型	說明和標籤
auto_annotate/operations/pending_objects	GAUGE、INT64	值區中待處理的物件總數。每 300 秒取樣一次。
auto_annotate/operations/processed_object_count	DELTA、INT64	在指定時間範圍內，object enrichments 功能處理的物件總數。每 300 秒取樣一次。
auto_annotate/operations/model_count	DELTA、INT64	在時間範圍內，bucket 中執行的模型總數，依 model_name、model_version 和 status 分組 (例如 SUCCESS 或 FAILURE)。
auto_annotate/operations/request_count	DELTA、INT64	時間範圍內發出的 API 呼叫總數，依 method 和 response_code 分組。
auto_annotate/storage/annotated_objects	GAUGE、INT64	值區中已產生擴充功能的物件總數每日快照，依 type 和 data_locations 分組。
auto_annotate/storage/model_outputs	GAUGE、INT64	每日數據匯報，顯示儲存在 bucket 的模型輸出內容總數，依 model_name、model_version、status、type 和 data_locations 分組。

如要進一步瞭解如何查詢指標及設定快訊，請參閱「Cloud Storage 的 Cloud Monitoring 指標」和「使用 Metrics Explorer 建立圖表」。

後續步驟

• 設定 object enrichments。
• 在 BigQuery 中使用 SQL 分析物件擴充功能。
• 查看支援的模型和輸出結構定義。
• 閱讀物件擴充功能總覽。
• 查看 featureConfigs JSON API 資源和方法。
• 瞭解物件背景資訊。
• 使用儲存空間批次作業大量管理物件。