您可以設定 儲存空間分析資料集，收集及分析 Cloud Storage bucket 和物件的中繼資料和活動記錄。運用這些資料集產生的洞察資訊，找出可節省費用的機會、執行安全稽核，以及支援作業監控。本文說明如何設定儲存空間分析資料集。
事前準備
設定資料集前，請先完成下列步驟。
取得必要角色
如要取得設定資料集所需的權限，請要求管理員在來源專案中授予您下列 IAM 角色：
-
如要設定資料集：儲存空間分析 管理員 (
roles/storageinsights.admin) -
如要連結資料集，請按照下列步驟操作：
- 儲存空間分析分析人員 (
roles/storageinsights.analyst) - BigQuery 管理員 (
roles/bigquery.admin)
- 儲存空間分析分析人員 (
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
這些預先定義的角色具備設定資料集所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限
您必須具備下列權限，才能設定資料集：
-
設定資料集：
-
storageinsights.datasetConfigs.create -
storage.buckets.getObjectInsights
-
-
連結至 BigQuery 資料集：
storageinsights.datasetConfigs.linkDataset
啟用儲存空間分析 API
控制台
指令列
如要在目前的專案中啟用 Storage Insights API，請執行 gcloud services enable 指令：
gcloud services enable storageinsights.googleapis.com
如要進一步瞭解如何為 Google Cloud 專案啟用服務，請參閱「啟用及停用服務」。
設定 Storage Intelligence
確認您要使用資料集分析的專案、資料夾或組織已設定 Storage Intelligence。
建立資料集設定
如要建立資料集設定，請按照下列步驟操作。如要進一步瞭解可為資料集設定指定的欄位，請參閱「資料集設定屬性」。
控制台
- 前往 Google Cloud 控制台的 Cloud Storage「儲存空間分析」頁面。
按一下「設定資料集」。
在「Name your dataset」(命名資料集) 部分，輸入資料集名稱。視需要輸入資料集說明。名稱用於識別資料集設定，且不可變更。名稱最多可包含 128 個字元，包括字母、數字和底線，且開頭須為字母。
在「定義資料集範圍」部分，執行下列操作：
選取下列選項之一：
如要取得目前組織中所有專案的儲存空間中繼資料，請選取「Include the organization」(納入組織)。
如要取得所選資料夾中所有專案的儲存空間中繼資料，請選取「Include folders (Sub-organization/departments)」(加入資料夾 (子組織/部門))。如要瞭解如何取得資料夾 ID，請參閱「查看或列出資料夾和專案」。如要新增資料夾，請按照下列步驟操作：
- 在「Folder 1」欄位中輸入資料夾 ID。
- 如要新增多個資料夾 ID，請按一下「+ Add another folder」(+ 新增其他資料夾)。
如要取得所選專案的儲存空間中繼資料，請選取「Include projects by providing project numbers」(提供專案編號來加入專案)。如要瞭解如何找出專案編號，請參閱「找出專案名稱、編號和 ID」。如要新增專案，請按照下列步驟操作：
- 在「Project 1」欄位中輸入專案編號。
- 如要新增多個專案編號，請按一下「+ Add another project」(+ 新增其他專案)。
如要大量新增專案或資料夾，請選取「透過 CSV 檔案上傳專案/資料夾清單」。CSV 檔案必須包含要納入資料集的專案編號或資料夾 ID。一項資料集設定最多可指定 10,000 項專案或資料夾。
指定是否要自動將所選資源日後建立的 bucket 納入。
(選用) 如要依據區域和 bucket 前置字串指定 bucket 篩選器，請展開「Filters (optional)」(篩選器 (選用)) 區段。篩選器會累加套用至值區。
您可以納入或排除特定區域中的 bucket。例如，您可以排除
me-central1和me-central2區域中的 bucket。您也可以根據前置字串納入或排除值區。舉例來說，如要排除開頭為my-bucket的值區，請輸入my-bucket*前置字串。
按一下「繼續」。
在「Select retention period」(選取保留期限) 部分，選取資料集中資料的保留期限。
資料集預設會包含活動資料，並沿用資料集的保留期限。如要覆寫資料集保留期限，請選取「Specify a retention period for activity data」(指定活動資料的保留期限)，然後選取活動資料的保留天數。如要停用活動資料，請將保留期限設為
0天。在「選取儲存設定資料集的位置」部分，選取儲存連結資料集的位置。例如：
us-central1。連結的資料集必須位於 BigQuery 支援的位置，但來源 bucket 可以位於任何 Cloud Storage 位置。
在「Select service account type」(選取服務帳戶類型) 區段，選取資料集的服務代理類型。為資料集選擇特定設定或特定專案的服務代理。
按一下 [設定]。
指令列
如要建立資料集設定，請執行
gcloud storage insights dataset-configs create指令，並加上必要旗標：gcloud storage insights dataset-configs create DATASET_CONFIG_ID \ --location=LOCATION \ --organization=SOURCE_ORG_NUMBER \ --retention-period-days=DATASET_RETENTION_PERIOD_DAYS \ (SCOPE_FLAG)
更改項目：
將
DATASET_CONFIG_ID換成資料集設定的名稱。名稱用於識別資料集設定，且無法變更。名稱最多可包含 128 個字元，包括英文字母、數字和底線，且開頭須為英文字母。LOCATION，並使用 location 儲存連結的資料集。例如：us-central1。
連結的資料集必須位於 BigQuery 支援的位置，但來源 bucket 可以位於任何 Cloud Storage 位置。
SOURCE_ORG_NUMBER，並將來源專案所屬的機構 ID 填入其中。如要查詢組織 ID，請參閱「取得機構資源 ID」。DATASET_RETENTION_PERIOD_DAYS，並設定資料集的資料保留期限。SCOPE_FLAG，並搭配下列任一旗標，定義要收集的資料範圍：--enable-organization-scope：允許資料集從組織內的所有 bucket 收集洞察資料。--source-folders=[SOURCE_FOLDER_NUMBERS,...]：指定要納入資料集的資料夾編號清單。如要瞭解如何找出資料夾編號，請參閱「列出階層中的所有專案和資料夾」。--source-folders-file=FILE_PATH： 將 CSV 檔案上傳至 bucket，即可指定多個資料夾編號。--source-projects=[SOURCE_PROJECT_NUMBERS,...]：指定要納入資料集的專案編號清單。例如，464036093014。如要找出專案編號，請參閱「找出專案名稱、編號和 ID」。--source-projects-file=FILE_PATH：將 CSV 檔案上傳至 bucket，指定多個專案編號。
您可以視需要使用下列其他標記設定資料集：
使用
--include-buckets=BUCKET_NAMES_OR_REGEX依名稱或規則運算式納入特定 bucket。這個旗標無法與--exclude-buckets搭配使用。使用
--exclude-buckets=BUCKET_NAMES_OR_REGEX依名稱或規則運算式排除特定 bucket。您無法將此旗標與--include-buckets搭配使用。使用
--project=DESTINATION_PROJECT_ID指定專案，儲存資料集設定和產生的資料集。如不使用這個旗標，目的地專案就是您的有效專案。如要進一步瞭解專案 ID，請參閱「建立與管理專案」。使用
--auto-add-new-buckets自動納入日後新增至來源專案的任何 bucket。使用
--skip-verification略過驗證程序中的檢查和失敗情形，包括檢查必要的 IAM 權限。如果使用這個旗標，部分或所有值區可能會從資料集中排除。使用
--identity=IDENTITY_TYPE指定透過資料集設定建立的服務代理程式範圍。值為IDENTITY_TYPE_PER_CONFIG或IDENTITY_TYPE_PER_PROJECT。如未指定，預設值為IDENTITY_TYPE_PER_CONFIG。詳情請參閱「服務代理程式類型」。使用
--description=DESCRIPTION新增資料集設定的說明。使用
--activity-data-retention-period-days=ACTIVITY_RETENTION_PERIOD_DAYS指定資料集中活動資料的保留期限。根據預設，活動資料會包含在資料集中，並沿用資料集的保留期限。如要覆寫資料集保留期限，請指定活動資料的保留天數。如要排除活動資料，請將 ACTIVITY_RETENTION_PERIOD_DAYS 設為0。
以下範例會為 ID 為
123456789的機構，在us-central1區域中建立名為my-dataset的資料集設定，保留期限為30天，且範圍僅限於專案987654321和123123123：gcloud storage insights dataset-configs create my-dataset \ --location=us-central1 \ --organization=123456789 \ --retention-period-days=30 \ --source-projects=987654321,123123123
JSON API
安裝並初始化 gcloud CLI，以便為
Authorization標頭產生存取權杖。建立包含下列資訊的 JSON 檔案：
{ "sourceProjects": { "project_numbers": ["PROJECT_NUMBERS", ...] }, "retentionPeriodDays": "RETENTION_PERIOD_DAYS", "activityDataRetentionPeriodDays": "ACTIVITY_DATA_RETENTION_PERIOD_DAYS", "identity": { "type": "IDENTITY_TYPE" } }
更改項目：
PROJECT_NUMBERS：要納入資料集的專案編號。您可以指定一或多個專案。專案必須指定為字串清單。或者，您也可以新增要更新中繼資料的儲存空間和物件所屬的機構，或一或多個資料夾。如要納入資料夾或機構，請使用
sourceFolders或organizationScope欄位。詳情請參閱DatasetConfig參考資料。RETENTION_PERIOD_DAYS替換為資料集快照中要擷取的資料天數。例如：90。ACTIVITY_DATA_RETENTION_PERIOD_DAYS，並輸入要擷取到資料集快照中的活動資料天數。根據預設，活動資料會納入資料集，並沿用資料集的保留期限。如要覆寫資料集保留期限，請指定活動資料的保留天數。如要排除活動資料，請將 ACTIVITY_RETENTION_PERIOD_DAYS 設為0。IDENTITY_TYPE，並指定與資料集設定一併建立的服務帳戶類型。值為IDENTITY_TYPE_PER_CONFIG或IDENTITY_TYPE_PER_PROJECT。詳情請參閱「服務代理類型」。
如要建立資料集設定，請使用
cURL呼叫 JSON API，並發出CreateDatasetConfig 要求：curl -X POST --data-binary @JSON_FILE_NAME \ "https://storageinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasetConfigs?datasetConfigId=DATASET_CONFIG_ID" \ --header "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT)" \ --header "Accept: application/json" \ --header "Content-Type: application/json"
更改項目：
將
JSON_FILE_NAME替換為您在上一步建立的 JSON 檔案路徑。或者，您也可以在要求主體中傳遞DatasetConfig的執行個體。PROJECT_ID：資料集設定和資料集所屬專案的 ID。LOCATION：資料集和資料集設定的位置。例如：us-central1。將
DATASET_CONFIG_ID替換成資料集設定的名稱。名稱用於識別資料集設定，且不可變更。名稱最多可包含 128 個字元，包括字母、數字和底線，且開頭須為字母。SERVICE_ACCOUNT服務帳戶。例如：test-service-account@test-project.iam.gserviceaccount.com。
如要排解 error_attributes_view 中記錄的快照處理錯誤，請參閱「Storage Insights 資料集錯誤」。
將必要權限授予服務代理
建立資料集設定時，Google Cloud 會建立限定於特定設定或專案的服務代理。服務代理程式會採用 service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com 命名格式，並在您選取「包含 Google 提供的角色授權」核取方塊後，顯示在 Google Cloud 控制台的「IAM」頁面中。您也可以使用 JSON API 查看 DatasetConfig 資源，找出服務代理程式的名稱。
如要啟用儲存空間分析來產生及寫入資料集，請要求系統管理員在包含來源專案的組織中，將 Storage Insights 收集器服務角色 (roles/storage.insightsCollectorService) 授予服務代理。您必須將這個角色授予每個設定範圍服務代理，這些代理是為您要取得資料的每個資料集設定建立。如果您使用專案範圍的服務代理，則只需將這個角色授予服務代理一次，即可讀取及寫入專案中所有資料集設定的資料集。
如需授予專案角色的操作說明，請參閱「管理存取權」。
連結資料集
如要將資料集連結至 BigQuery，請完成下列步驟：
控制台
- 前往 Google Cloud 控制台的 Cloud Storage「儲存空間分析」頁面。
按一下產生要連結資料集的資料集設定名稱。
在「BigQuery 連結的資料集」部分，按一下「連結資料集」來連結資料集。
指令列
如要將資料集連結至 BigQuery，請執行
gcloud storage insights dataset-configs create-link指令：gcloud storage insights dataset-configs create-link DATASET_CONFIG_ID --location=LOCATION
更改項目：
DATASET_CONFIG_ID：產生要連結資料集的資料集設定名稱。LOCATION替換為資料集的位置。例如：us-central1。
您也可以指定完整資料集設定路徑。例如：
gcloud storage insights dataset-configs create-link projects/DESTINATION_PROJECT_ID/locations/LOCATION/datasetConfigs/DATASET_CONFIG_ID
更改項目：
JSON API
安裝並初始化 gcloud CLI，以便為
Authorization標頭產生存取權杖。使用
cURL搭配linkDatasetDatasetConfig 要求呼叫 JSON API：curl -X POST \ "https://storageinsights.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasetConfigsDATASET_CONFIG_ID:linkDataset?" \ --header "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=SERVICE_ACCOUNT)" \ --header "Accept: application/json" \ --header "Content-Type: application/json"更改項目：
使用 BigQuery 分析物件資料和中繼資料
如要分析物件內容或查看物件中繼資料，請使用 ref 欄 (會做為儲存空間分析資料集的一部分傳回)，執行 BigQuery ObjectRef 函式。請完成以下各節的步驟。
在 BigQuery 中建立 Cloud 資源連結
在 BigQuery 建立可存取 Cloud Storage 的 Cloud 資源連結。Cloud 資源連結可讓 BigQuery 使用自己的服務帳戶，存取 Cloud Storage 物件資料和中繼資料。詳情請參閱「建立 Cloud 資源連結」。
搭配儲存空間分析資料集使用 Cloud 資源連結
如要分析 ref 欄中參照的資料 (該資料會做為儲存空間分析資料集的一部分傳回)，請使用 OBJ.MAKE_REF 函式，將 URI 從 ref 欄與您建立的連線合併：
SELECT OBJ.GET_ACCESS_URL(OBJ.MAKE_REF(ref.uri, "CONNECTION_ID"), "r") FROM `PROJECT_ID.INSIGHTS_DATASET.object_attributes_view` WHERE LOCATION = "US";
更改項目：
CONNECTION_ID：您建立的 Cloud 資源連結 ID。PROJECT_ID：儲存空間分析 資料集所在專案的 ID。INSIGHTS_DATASET：儲存空間分析資料集的名稱。例如：storageinsights_dataset。
使用自訂模型分析儲存空間分析資料集
BigQuery 不支援直接在連結資料集中建立模型。如要使用自訂模型分析「儲存空間分析」資料，您必須在標準 BigQuery 資料集中建立及儲存模型。接著，您可以在查詢中參照該模型，同時指定連結的資料集進行分析：
在 BigQuery 資料集 (
MODEL_DATASET) 中建立模型，該資料集與連結的資料集 (INSIGHTS_DATASET) 位於同一個專案：CREATE OR REPLACE MODEL `MODEL_DATASET.gemini_model` REMOTE WITH CONNECTION `CONNECTION_ID` OPTIONS (ENDPOINT = 'gemini-2.0-flash');
更改項目：
MODEL_DATASET：要建立模型的資料集名稱。CONNECTION_ID：您建立的 Cloud 資源連結 ID。
執行參照模型的查詢，分析 Storage Insights 資料集中的資料。以下範例會為資料集中的圖片新增說明：
SELECT name, result AS ai_description FROM AI.GENERATE_TEXT( MODEL `MODEL_DATASET.gemini_model`, ( SELECT name, ( 'Describe this image', OBJ.GET_ACCESS_URL( OBJ.FETCH_METADATA( OBJ.MAKE_REF( ref.uri, 'CONNECTION_ID' ) ), 'r' ) ) AS prompt FROM `INSIGHTS_DATASET.object_attributes_view` WHERE contentType LIKE 'image/%' AND NOT name LIKE '%/' LIMIT 3 ) );
更改項目：
INSIGHTS_DATASET：儲存空間分析資料集的名稱。MODEL_DATASET：建立模型的資料集名稱。CONNECTION_ID：您建立的 Cloud 資源連結 ID。
使用預設模型分析儲存空間分析資料集
您可以使用預設模型，從非結構化資料生成洞察資訊，並協助偵測私密資訊。
從非結構化資料產生洞察資訊
下列查詢範例會生成 JPEG 圖片的說明：
SELECT AI.GENERATE( ( 'Return a JSON object with fields: "description" (max 20 words)', OBJ.GET_ACCESS_URL( OBJ.MAKE_REF(ref.uri, `CONNECTION_ID`), 'r' ) ) ) FROM `PROJECT_ID.INSIGHTS_DATASET.object_attributes_view` WHERE name LIKE 'returns/electronics/%' AND contentType = 'image/jpeg';
更改項目：
CONNECTION_ID：您建立的 Cloud 資源連結 ID。PROJECT_ID：儲存空間分析 資料集所在專案的 ID。INSIGHTS_DATASET：儲存空間分析資料集的名稱。
自動偵測機密資料
您可以使用多模態模型，偵測文件中的私密資料，例如個人識別資訊 (PII)。
下列查詢顯示如何掃描 PDF 文件，檢查是否有機密資訊：
SELECT AI.GENERATE( ( 'Does this document contain any credit card numbers or home addresses? Answer "SAFE" or "SENSITIVE".', OBJ.GET_ACCESS_URL( OBJ.MAKE_REF(ref.uri, `CONNECTION_ID`), 'r' ) ) ) FROM `PROJECT_ID.INSIGHTS_DATASET.object_attributes_view` WHERE contentType = 'application/pdf';
更改項目：
CONNECTION_ID：您建立的 Cloud 資源連結 ID。PROJECT_ID：儲存空間分析 資料集所在專案的 ID。INSIGHTS_DATASET：儲存空間分析資料集的名稱。
分析物件脈絡資料
如果資料集包含 object_contexts_catalog_view，您可以直接在 BigQuery 中查詢物件情境和擴充資料 (預先發布版)，例如標籤、臉部偵測和定界框。
圖片標籤：尋找含有特定標籤的物件
以下查詢會找出標註特定標籤且可信度分數大於 0.75 的圖片：
SELECT t.project, t.bucket, t.name, t.generation, label FROM `PROJECT_ID.INSIGHTS_DATASET.object_contexts_catalog_view` AS t, UNNEST(t.contexts) AS context, UNNEST(JSON_QUERY_ARRAY(context.extendedData.labelAnnotationGroup.labelAnnotations)) AS label WHERE context.key = "google:annotation:label-detector-v1" AND LOWER(STRING(label.description)) = 'LABEL_DESCRIPTION' AND FLOAT64(label.score) > 0.75;
更改項目：
PROJECT_ID：包含儲存空間分析資料集的專案 ID。INSIGHTS_DATASET：儲存空間分析資料集的名稱。LABEL_DESCRIPTION：要搜尋的標籤說明 (例如car或clothing)。
臉部偵測：找出微笑的相片
下列查詢會篩選出含有臉孔且喜悅機率大於 0.5 的圖片：
WITH face_stats AS ( SELECT t.project, t.bucket, t.name, t.generation, FLOAT64(face.joyProbability) AS joy_probability, FLOAT64(face.rollAngle) AS roll_angle, FLOAT64(face.panAngle) AS pan_angle, FLOAT64(face.tiltAngle) AS tilt_angle FROM `PROJECT_ID.INSIGHTS_DATASET.object_contexts_catalog_view` AS t, UNNEST(t.contexts) AS context, UNNEST(JSON_QUERY_ARRAY(context.extendedData.faceAnnotationGroup.faceAnnotations)) AS face WHERE context.key = 'google:annotation:face-detector-v1' ) SELECT * FROM face_stats WHERE joy_probability > 0.5 AND roll_angle BETWEEN -10 AND 10 AND pan_angle BETWEEN -10 AND 10 AND tilt_angle BETWEEN -10 AND 10 LIMIT 10;
更改項目：
PROJECT_ID：包含儲存空間分析資料集的專案 ID。INSIGHTS_DATASET：儲存空間分析資料集的名稱。
物件偵測：找出偵測到物件的定界框座標
下列查詢會擷取可信度分數大於 0.50 的物件偵測定界框座標：
SELECT t.project, t.bucket, t.name AS object_name, t.generation, STRING(object.name) AS detected_object_name, FLOAT64(object.score) AS confidence_score, ( SELECT AS STRUCT MIN(FLOAT64(v.x)) AS x_min, MIN(FLOAT64(v.y)) AS y_min, MAX(FLOAT64(v.x)) AS x_max, MAX(FLOAT64(v.y)) AS y_max FROM UNNEST(JSON_QUERY_ARRAY(object.boundingPoly.normalizedVertices)) AS v ).* FROM `PROJECT_ID.INSIGHTS_DATASET.object_contexts_catalog_view` AS t, UNNEST(t.contexts) AS context, UNNEST(JSON_QUERY_ARRAY(context.extendedData.objectAnnotationGroup.objectAnnotations)) AS object WHERE context.key = 'google:annotation:object-detector-v1' AND LOWER(STRING(object.name)) = 'DETECTED_OBJECT_NAME' AND FLOAT64(object.score) > 0.50 LIMIT 20;
更改項目：
PROJECT_ID：包含儲存空間分析資料集的專案 ID。INSIGHTS_DATASET：儲存空間分析資料集的名稱。DETECTED_OBJECT_NAME：要搜尋的偵測到物件類別名稱 (例如drink或car)。