您可以設定 儲存空間分析資料集，收集及分析 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 個字元，包括英文字母、數字和底線，且開頭須為英文字母。
在「Define dataset scope」(定義資料集範圍) 部分，執行下列操作：
選取下列選項之一：
如要取得目前組織中所有專案的儲存空間中繼資料，請選取「Include the organization」(納入組織)。
如要取得所選資料夾中所有專案的儲存空間中繼資料，請選取「Include folders (Sub-organization/departments)」(加入資料夾 (子組織/部門))。如要瞭解如何取得資料夾 ID，請參閱「查看或列出資料夾和專案」。如要新增資料夾，請按照下列步驟操作：
- 在「Folder 1」欄位中輸入資料夾 ID。
- 如要新增多個資料夾 ID，請點選「+ 新增其他資料夾」。
如要取得所選專案的儲存空間中繼資料，請選取「Include projects by providing project numbers」(提供專案編號來加入專案)。如要瞭解如何找出專案編號，請參閱「找出專案名稱、編號和 ID」。如要新增專案，請按照下列步驟操作：
- 在「Project 1」欄位中，輸入專案編號。
- 如要新增多個專案編號，請按一下「+ 新增其他專案」。
如要大量新增專案或資料夾，請選取「透過 CSV 檔案上傳專案/資料夾清單」。CSV 檔案必須包含要納入資料集的專案編號或資料夾 ID。一個資料集設定最多可指定 10,000 個專案或資料夾。
指定是否要自動將所選資源日後建立的 bucket 納入。
如要依據區域和 bucket 前置字串指定 bucket 篩選條件，請展開「Filters (optional)」(篩選條件 (選用)) 區段。篩選器會累加套用至值區。
您可以納入或排除特定區域中的 bucket。舉例來說，您可以排除
me-central1和me-central2區域中的 buckets。您也可以根據前置字串納入或排除值區。舉例來說，如要排除開頭為my-bucket的值區，請輸入my-bucket*前置字串。
按一下「繼續」。
在「選取保留期限」部分，選取資料集中資料的保留期限。
資料集預設會包含活動資料，並沿用資料集的保留期限。如要覆寫資料集保留期限，請選取「Specify a retention period for activity data」(指定活動資料的保留期限)，然後選取活動資料的保留天數。如要停用活動資料，請將保留期限設為
0天。在「Select location to store configured dataset」(選取儲存設定資料集的位置) 部分，選取要儲存連結資料集的位置。例如：
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，並提供要儲存連結資料集的位置。例如：us-central1。
連結的資料集必須位於 BigQuery 支援的位置，但來源 bucket 可以位於任何 Cloud Storage 位置。
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。
以下範例會在
us-central1區域中，為 ID 為123456789的組織建立名為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 of the project 是指資料集設定和資料集所屬的專案 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呼叫 JSON API，並發出linkDatasetDatasetConfig 要求：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"更改項目：
JSON_FILE_NAME：您建立的 JSON 檔案路徑。PROJECT_ID，其中 ID 是資料集設定所屬的專案。LOCATION替換為資料集和資料集設定所在的位置。例如：us-central1。DATASET_CONFIG_ID替換為產生要連結資料集的資料集設定名稱。SERVICE_ACCOUNT。例如：test-service-account@test-project.iam.gserviceaccount.com。
使用 BigQuery 分析物件資料和中繼資料
如要分析物件內容或查看物件中繼資料，請使用 ref 欄 (會以「儲存空間分析」資料集的形式傳回)，執行 BigQuery ObjectRef函式。請完成以下各節的步驟。
在 BigQuery 中建立 Cloud 資源連結
在 BigQuery 中，建立可存取 Cloud Storage 的 Cloud 資源連結。Cloud 資源連結可讓 BigQuery 使用自己的服務帳戶，存取 Cloud Storage 物件資料和中繼資料。詳情請參閱「建立 Cloud 資源連結」。
搭配儲存空間分析資料集使用 Cloud 資源連結
如要分析 ref 欄中參照的資料，這些資料會以儲存空間分析資料集的形式傳回，請使用 OBJ.MAKE_REF 函式合併 ref 欄中的 URI 和您建立的連線：
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 資料集中建立及儲存模型。接著，您可以在查詢中參照該模型，同時指定連結的資料集進行分析：
在與連結資料集 (
INSIGHTS_DATASET) 相同的專案中，於 BigQuery 資料集 (MODEL_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：儲存空間分析資料集的名稱。