使用庫存報表

Cloud Storage inventory reports 可讓您排定 CSV 或 Apache Parquet 匯出作業，匯出物件中繼資料，而不必執行耗用大量資源的清單作業。您可以設定報表時間安排、查看產生的報表，以及管理報表設定，以便稽核物件、分析儲存費用或驗證資料遷移作業。

事前準備

開始建立及管理庫存報表和庫存報表設定之前，請按照後續子節的操作說明操作。

取得必要角色

如要取得建立及管理庫存報表所需的權限，請要求管理員在專案或來源和目的地 bucket 上，授予您下列 IAM 角色，以便管理庫存報表。

  • 如要建立及管理庫存報表設定，請按照下列步驟操作：

    • 來源和目的地 bucket 的 roles/storage.admin

    • 專案的 roles/storageinsights.admin 權限

  • 如要讀取及下載庫存報表，請按照下列步驟操作：

    • 目的地 bucket 的 roles/storage.objectViewer

    • 專案的 roles/storageinsights.viewer 權限

這些預先定義的角色具備建立及管理庫存報表和設定所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及管理庫存報表設定，請按照下列步驟操作：

  • 來源 bucket 的 storage.buckets.get
  • 來源 bucket 的 storage.objects.list
  • 來源 bucket 的 storage.buckets.getObjectInsights
  • 目的地 bucket 的 storage.buckets.get
  • 目的地 bucket 的 storage.objects.create
  • 專案的 storageinsights.reportConfigs.delete 權限
  • 專案的 storageinsights.reportConfigs.get 權限
  • 專案的 storageinsights.reportConfigs.create 權限
  • 專案的 storageinsights.reportConfigs.list 權限
  • 專案的 storageinsights.reportConfigs.update 權限

如要讀取及下載庫存報表，請按照下列步驟操作：

  • 目的地 bucket 的 storage.objects.get
  • 專案的 storageinsights.reportDetails.get 權限
  • 專案的 storageinsights.reportDetails.list 權限

您或許還可透過其他預先定義的角色取得這些權限。如要查看角色與權限的關聯，請參閱「Cloud Storage 的 IAM 角色」。

如要瞭解如何使用角色控管 bucket 存取權，請參閱「使用 IAM」。如要瞭解如何使用角色控管專案存取權，請參閱「管理存取權」。

啟用儲存空間分析 API

控制台

啟用儲存空間分析 API (如果尚未啟用)。

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

指令列

啟用 Storage Insights API (如果尚未啟用)：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則，您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

gcloud services enable storageinsights.googleapis.com

REST API

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

  2. 如要啟用儲存空間分析 API，請使用 cURL 呼叫 services.enable 方法：

    curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  https://serviceusage.googleapis.com/v1/projects/PROJECT_ID/services/storageinsights.googleapis.com:enable

    更改項目：

    PROJECT_ID：要啟用 API 的專案 ID。

建立庫存報表設定

控制台

如要建立商品目錄報表設定，請完成下列步驟：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選要用做來源 bucket 的 bucket 名稱。

  3. 在「Bucket details」(值區詳細資料) 頁面中，按一下「Inventory reports」(庫存報表) 分頁標籤。

  4. 按一下「Create report configuration」(建立報表設定)。

  5. 在「Identify your report configuration」(確認報表設定) 部分，建立庫存報表設定的顯示名稱。顯示名稱最多可包含 256 個字元。

  6. 在「Choose metadata fields」(選擇中繼資料欄位) 區段中，選取要納入清查報表的中繼資料欄位。

  7. 按一下「繼續」。

  8. 在「Choose a file format」(選擇檔案格式) 部分，選取要產生商品目錄報表的檔案格式。

  9. 在「Choose a destination bucket」(選擇目的地 bucket) 區段中，選取要用做目的地 bucket 的 bucket。

    在「Enter destination path (optional)」(輸入目的地路徑 (選填)) 部分，您可以視需要指定要產生庫存報表的目的地路徑。

  10. 在「Scheduling options」(排程選項) 部分，指定產生報表的頻率、開始日期和結束日期。

  11. 點選「建立」。

    系統隨即會顯示「Report configuration details」(報表設定詳細資料) 頁面。頁面上會顯示產生的庫存報表中繼資料。

指令列

  1. 如要建立庫存報表設定，請執行 gcloud storage insights inventory-reports create 指令：

    gcloud storage insights inventory-reports create SOURCE_BUCKET_URL \
  --csv-separator=SEPARATOR \
  --csv-delimiter=DELIMITER \
  --[no]-csv-header \
  --parquet \
  --display-name=DISPLAY_NAME \
  --destination=DESTINATION_PATH \
  --metadata-fields=METADATA_FIELD \
  --schedule-starts=START_DATE \
  --schedule-repeats=FREQUENCY \
  --schedule-repeats-until=END_DATE

    更改項目：

    • SOURCE_BUCKET_URL 替換為來源 bucket 的網址。例如：gs://my_example_source_bucket。

    • SEPARATOR 替換為用於分隔 CSV 檔案中記錄的字元。必須是 \n 或 \r\n。預設值為 \n。選用。如果使用 --csv-separator 旗標，則無法使用 --parquet。

    • DELIMITER：CSV 格式庫存報表中分隔欄位的分隔符號。值可以包含一個字元，且不得與 SEPARATOR 相同。預設值為 ,。選用。 如果使用 --csv-delimiter，就無法使用 --parquet。

    • --[no]-csv-header，並加上標記，指出商品目錄報表 CSV 檔案是否包含標頭。使用 --csv-header 納入標頭，使用 --no-csv-header 排除標頭。如果使用任一標記，就無法使用 --parquet。

    • DISPLAY_NAME：可編輯的庫存報表設定名稱。選填。

    • --parquet，並加入標記，以 Apache Parquet 格式 (而非 CSV) 產生庫存報表。如果使用，則無法使用 --csv-delimiter、--csv-separator 和 --[no-]csv-header。

    • 將 DESTINATION_PATH 替換為要產生庫存報表的值區或值區中的資料夾。例如 gs://my_example_destination_bucket 或 gs://my_example_destination_bucket/path/to/inventory/report。

      指定 bucket 內資料夾的路徑時，您可以在路徑中使用關鍵字，系統會在產生報表時將關鍵字替換為相應的值。這樣一來，您就能以 Hive 分區格式產生報表，在 BigQuery 中載入或查詢資料，不需額外處理。

    • METADATA_FIELD，並以逗號分隔的清單，列出要納入清查報表的中繼資料欄位。

    • START_DATE 替換成要開始產生庫存報表的世界標準時間日期。例如：2022-01-15。

    • FREQUENCY 替換為您希望產生庫存報表的頻率。值為 daily 或 weekly。

    • END_DATE：世界標準時間日期，表示您希望停止產生商品目錄報表的時間。必須是 START_DATE 之後的值。舉例來說，如果您指定 2022-02-15，系統自 2022 年 2 月 16 日起就不會再產生商品目錄報表。

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


import com.google.cloud.storageinsights.v1.CSVOptions;
import com.google.cloud.storageinsights.v1.CloudStorageDestinationOptions;
import com.google.cloud.storageinsights.v1.CloudStorageFilters;
import com.google.cloud.storageinsights.v1.CreateReportConfigRequest;
import com.google.cloud.storageinsights.v1.FrequencyOptions;
import com.google.cloud.storageinsights.v1.LocationName;
import com.google.cloud.storageinsights.v1.ObjectMetadataReportOptions;
import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import com.google.common.collect.ImmutableList;
import com.google.type.Date;
import java.io.IOException;

public class CreateInventoryReportConfig {

  public static void createInventoryReportConfig(
      String projectId, String bucketLocation, String sourceBucket, String destinationBucket)
      throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfig reportConfig =
          ReportConfig.newBuilder()
              .setDisplayName("Example inventory report configuration")
              .setFrequencyOptions(
                  FrequencyOptions.newBuilder()
                      .setFrequency(FrequencyOptions.Frequency.WEEKLY)
                      .setStartDate(Date.newBuilder().setDay(15).setMonth(8).setYear(3022).build())
                      .setEndDate(Date.newBuilder().setDay(15).setMonth(9).setYear(3022).build())
                      .build())
              .setCsvOptions(
                  CSVOptions.newBuilder()
                      .setDelimiter(",")
                      .setRecordSeparator("\n")
                      .setHeaderRequired(true)
                      .build())
              .setObjectMetadataReportOptions(
                  ObjectMetadataReportOptions.newBuilder()
                      .addAllMetadataFields(ImmutableList.of("project", "name", "bucket"))
                      .setStorageFilters(
                          CloudStorageFilters.newBuilder().setBucket(sourceBucket).build())
                      .setStorageDestinationOptions(
                          CloudStorageDestinationOptions.newBuilder()
                              .setBucket(destinationBucket)
                              .build())
                      .build())
              .build();
      CreateReportConfigRequest request =
          CreateReportConfigRequest.newBuilder()
              .setParent(LocationName.of(projectId, bucketLocation).toString())
              .setReportConfig(reportConfig)
              .build();
      ReportConfig response = storageInsightsClient.createReportConfig(request);
      System.out.println("Created inventory report config with name " + response.getName());
    }
  }
}

REST API

JSON API

如要建立商品目錄報表設定，請完成下列步驟：

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

  2. 建立包含下列資訊的 JSON 檔案，除非另有說明，否則所有欄位皆為必填：

    {
  "display_name": "DISPLAY_NAME",
  "frequency_options": {
    "frequency": "FREQUENCY",
    "start_date": "START_DATE",
    "end_date": "END_DATE",
  },
  "csv_options": {
    "record_separator": "RECORD_SEPARATOR",
    "delimiter": "DELIMITER",
    "header_required": HEADER_REQUIRED
  },
  "object_metadata_report_options": {
     "metadata_fields": [
      "METADATA_FIELD",
      ...
    ],
    "storage_filters": {
      "bucket": "SOURCE_BUCKET_NAME"
    },
    "storage_destination_options": {
      "bucket": "DESTINATION_BUCKET_NAME",
      "destination_path": "DESTINATION_PATH"
    }
  }
}

    更改項目：

    • DISPLAY_NAME：庫存報表設定的可編輯顯示名稱。最多可包含 256 個字元。

    • FREQUENCY 替換為產生商品目錄報表的頻率。值為 DAILY 或 WEEKLY。

    • START_DATE 替換成要開始產生庫存報表的世界標準時間日期。不得為當天或過去的日期。值必須是包含 day、month 和 year 鍵的物件。例如：{"day": 15, "month": 8, "year": 2022}。

    • END_DATE：世界標準時間日期，表示您希望停止產生商品目錄報表的時間。值必須是包含 day、month 和 year 鍵的物件。舉例來說，如果您指定 {"day": 15, "month": 9, "year": 2022}，系統就不會再產生 2022 年 9 月 16 日之後的商品目錄報表。

    • RECORD_SEPARATOR 替換為用於分隔 CSV 檔案中記錄的字元。必須是 \n 或 \r\n。預設值為 \n。這是選填欄位。

    • DELIMITER：用於分隔 CSV 格式商品目錄報表中欄位的分隔符號。值可以包含一個字元，且不得與 RECORD_SEPARATOR 相同。預設值為 ,。這是選填欄位。

    • HEADER_REQUIRED：布林值，表示 CSV 檔案是否包含標頭。這是選填欄位。

    • SOURCE_BUCKET_NAME 替換成來源 bucket 的名稱，該 bucket 包含您要產生清查報表的物件。例如：my_example_bucket。

    • METADATA_FIELD：以半形逗號分隔的清單，列出要納入清查報表的中繼資料欄位。

    • DESTINATION_BUCKET_NAME：目的地 bucket 的名稱，用於產生及儲存庫存報表。例如：my_example_destination_bucket。

    • DESTINATION_PATH：產生清查報表的目的地 bucket 路徑。這是選填欄位。

      指定 bucket 內資料夾的路徑時，您可以在路徑中使用關鍵字，系統會在產生報表時將關鍵字替換為相應的值。這樣一來，您就能以 Hive 分區格式產生報表，在 BigQuery 中載入或查詢資料，不需額外處理。

    舉例來說，下列程式碼範例會建立名為「Example inventory report configuration」的商品目錄報表設定，並每週產生報表：

    {
  "display_name": "Example inventory report configuration",
  "frequency_options": {
    "frequency": "WEEKLY",
    "start_date": {
      "day": 15,
      "month": 8,
      "year": 2022
    },
    "end_date": {
      "day": 15,
      "month": 9,
      "year": 2022
    },
  },
  "csv_options": {
    "record_separator": "\n",
    "delimiter": ",",
    "header_required": true
  },
  "object_metadata_report_options": {
     "metadata_fields": [
      "project",
      "name",
      "bucket"
    ],
    "storage_filters": {
      "bucket": "example_source_bucket"
    },
    "storage_destination_options": {
      "bucket": "example_destination_bucket"
    }
  }
}

  3. 如要套用清查報表設定，請使用 cURL 呼叫 JSON API，並傳送 Create ReportConfig 要求：

    curl -X POST --data-binary @JSON_FILE_NAME \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • JSON_FILE_NAME：您在上一個步驟中建立的 JSON 檔案路徑。

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

將必要角色授予服務代理

首次設定清查報表時，系統會自動建立專案層級的服務代理。服務代理程式的命名格式為 service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com，當您勾選「Include Google-provided role grants」(包含 Google 提供的角色授權) 核取方塊時，服務代理程式會顯示在 Google Cloud 控制台的 IAM 頁面。

如要啟用儲存空間分析來產生及寫入庫存報表，請要求系統管理員將下列 IAM 角色授予服務代理：

  • 來源 bucket 的 roles/storage.insightsCollectorService，包括 storage.buckets.getObjectInsights 和 storage.buckets.get 權限
  • 目的地 bucket 的 roles/storage.objectCreator，包含 storage.objects.create 權限

如需授予角色的操作說明，請參閱「使用 IAM」。您可以使用 Google Cloud 控制台或 Google Cloud CLI 授予 roles/storage.insightsCollectorService 角色。例如： 

gcloud storage buckets add-iam-policy-binding SOURCE_BUCKET_URL \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com \
    --role=roles/storage.insightsCollectorService

服務代理取得必要權限後，最多需要 24 小時，才能將第一份庫存報表寫入目的地 bucket。

編輯庫存報表設定

建立庫存報表設定後，您可以修改設定的特定屬性。

控制台

如要編輯庫存報表設定，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，按一下來源 bucket 的名稱，其中包含您要編輯的庫存報表設定。

  3. 在來源 bucket 的「Bucket details」(bucket 詳細資料) 頁面中，按一下「Inventory reports」(清查報表) 分頁標籤。

  4. 按一下要編輯的庫存報表設定名稱。

  5. 在隨即顯示的「Report configuration details」(報表設定詳細資料) 頁面中，使用 「Edit」(編輯) 按鈕編輯屬性。

指令列

如要編輯庫存報表設定，請按照下列步驟操作：

  1. 如要找出要編輯的清查報表設定名稱，請使用 gcloud storage insights inventory-reports list 指令，列出來源 bucket 中的所有清查設定：

    gcloud storage insights inventory-reports list \
  --source=SOURCE_BUCKET \
  --filter=EXPRESSION \
  --page-size=SIZE \
  --sort-by=FIELD \
  --format="yaml(name)"

    更改項目：

    • SOURCE_BUCKET：含有資產盤點清單報表設定的來源 bucket 網址。

    • EXPRESSION：對要列出的每個資源項目套用布林值篩選條件。如果運算式評估結果為 True，系統就會列出項目。如要進一步瞭解篩選運算式並查看範例，請執行 $ gcloud topic filters。

    • SIZE，其中包含每頁的資源數量上限。預設值為 50。

    • FIELD：列出要做為排序依據的資源欄位索引鍵名稱，並以逗號分隔的清單呈現。預設為遞增排序。如要指定特定欄位採用遞減排序，請在該欄位前面加上 ~。

    1. 使用 gcloud storage insights inventory-reports update 指令，編輯要更新的庫存報表設定欄位。以下範例會更新庫存報表設定，以 Apache Parquet 格式每日產生庫存報表：

      gcloud storage insights inventory-reports update CONFIG_NAME \
--parquet \
--schedule-repeats="daily"

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.ReportConfigName;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import com.google.cloud.storageinsights.v1.UpdateReportConfigRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;

public class EditInventoryReportConfig {


  public static void editInventoryReportConfig(
          String projectId, String location, String inventoryReportConfigUuid) throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfigName name = ReportConfigName.of(projectId, location, inventoryReportConfigUuid);
      ReportConfig reportConfig = storageInsightsClient.getReportConfig(name);

      // Set any other fields you want to update here
      ReportConfig updatedReportConfig =
              reportConfig.toBuilder().setDisplayName("Updated Display Name").build();

      storageInsightsClient.updateReportConfig(
              UpdateReportConfigRequest.newBuilder()
                      // Add any fields that you want to update to the update mask, in snake case
                      .setUpdateMask(FieldMask.newBuilder().addPaths("display_name")
                              .build())
                      .setReportConfig(updatedReportConfig).build());

      System.out.println("Edited inventory report config with name " + name);
    }
  }
}

REST API

JSON API

如要編輯庫存報表設定，請完成下列步驟：

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

  2. 使用 cURL 呼叫 JSON API，並傳送 Get ReportConfig 要求，取得要編輯的商品目錄報表設定名稱：

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    如要擷取特定來源 bucket 中的所有庫存報表設定，請在要求中附加 filter 查詢參數：

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?filter=objectMetadataReportOptions.storageFilters.bucket=BUCKET_NAME" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。
    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。
    • BUCKET_NAME：來源 bucket 的名稱，其中包含要編輯的庫存報表設定。

  3. 建立 JSON 檔案，其中包含要編輯的屬性變更。以下範例會更新庫存報表設定，以 Apache Parquet 格式每日產生庫存報表：

    {
  "ReportConfig": {
    "frequency_options": {
      "frequency": "DAILY"
    },
    "parquet_options": {
    }
  }

  4. 如要套用清查報表設定，請使用 cURL 呼叫 JSON API，並傳送 Patch ReportConfig 要求：

    curl --request PATCH \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data-binary "@JSON_FILE_NAME.json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    • REPORT_CONFIG_UUID 替換為自動生成的庫存報表設定 UUID。

列出庫存報表設定

控制台

如要列出來源 bucket 中的庫存報表設定，請完成下列步驟：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選來源 bucket 的名稱，其中包含您要查看的庫存報表設定。

  3. 在「Bucket details」(值區詳細資料) 頁面中，按一下「Inventory reports」(庫存報表) 分頁標籤。

    來源 bucket 中的庫存報表設定會隨即顯示。

指令列

您可以使用 gcloud storage insights inventory-reports list 指令，列出來源 bucket 中的所有清查設定：

gcloud storage insights inventory-reports list \
  --source=SOURCE_BUCKET \
  --filter=EXPRESSION \
  --page-size=SIZE \
  --sort-by=FIELD \
  --format="yaml(name)"

更改項目：

  • SOURCE_BUCKET：含有資產盤點清單報表設定的來源 bucket 網址。

  • EXPRESSION：對要列出的每個資源項目套用布林值篩選條件。如果運算式評估結果為 True，系統就會列出項目。如要進一步瞭解篩選運算式並查看範例，請執行 $ gcloud topic filters。

  • SIZE，其中包含每頁的資源數量上限。預設值為 50。

  • FIELD：列出要做為排序依據的資源欄位索引鍵名稱，並以逗號分隔的清單呈現。預設為遞增排序。如要指定特定欄位採用遞減排序，請在該欄位前面加上 ~。

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


import com.google.cloud.storageinsights.v1.LocationName;
import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import java.io.IOException;

public class ListInventoryReportConfigs {


  public static void listInventoryReportConfigs(String projectId, String location)
      throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      System.out.println(
          "Printing inventory report configs in project "
              + projectId
              + " and location "
              + location);
      for (ReportConfig config :
          storageInsightsClient
              .listReportConfigs(LocationName.of(projectId, location))
              .iterateAll()) {
        System.out.println(config.getName());
      }
    }
  }
}

REST API

JSON API

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

  2. 您可以使用列出庫存報表設定的要求，列出專案中特定位置的所有庫存報表設定：

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    如要列出特定來源 bucket 中的所有商品目錄報表設定，請在要求中附加 filter 查詢參數：

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs?filter=objectMetadataReportOptions.storageFilters.bucket=BUCKET_NAME" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    • BUCKET_NAME 替換為來源 bucket 的名稱，其中包含要列出的庫存報表設定。

下載商品目錄報表

控制台

下載個別報表

系統會產生清查報表，並以物件形式儲存在目的地 bucket 中，因此您可以像下載一般物件一樣下載報表。

如要下載商品目錄報表，請完成下列步驟：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選含有要下載清查報表的目的地 bucket 名稱。

  3. 在「Bucket details」(值區詳細資料) 頁面中，確認已選取「Objects」(物件) 分頁標籤。

  4. 按一下要下載的商品目錄報表相關聯的 「Download」(下載)。

如果不知道目的地 bucket，也可以透過產生報表的設定，下載庫存報表：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選來源 bucket 的名稱，其中包含產生要下載報表的庫存報表設定。

  3. 在「Bucket details」(Bucket 詳細資料) 頁面中，按一下清查報表設定的設定名稱。

  4. 在隨即顯示的「Report configuration details」(報表設定詳細資料) 頁面中，前往「Inventory report history」(庫存報表記錄) 專區，然後點選要下載的庫存報表目的地物件路徑。

    系統會顯示包含庫存報表的目的地 bucket「Bucket details」(bucket 詳細資料) 頁面。

  5. 按一下要下載的商品目錄報表相關聯的 「Download」(下載)。

下載報表 shard

如要下載已分割成一或多個 shard 的庫存報表，請完成下列步驟：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選您建立庫存報表設定時指定的目的地 bucket 名稱。

  3. 在「Bucket details」(值區詳細資料) 頁面中，檢查是否有資訊清單檔案。如果出現資訊清單檔案，表示庫存報表的所有 shard 都已產生。

    資訊清單檔案名稱範例如下：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。

  4. 在目的地 bucket 中，按一下與資訊清單檔案相關聯的「 Download」(下載)。記下要從 report_shards_file_names 欄位下載的 shard 檔案名稱。

  5. 在目的地 bucket 中，按一下與要下載的 shard 檔案相關聯的 「Download」(下載)。

指令列

下載個別報表

如要下載商品目錄報表，請完成下列步驟：

  1. 如要列出由盤點報表設定產生的所有盤點報表，並擷取其 REPORT_DETAIL_ID，請使用 gcloud storage insights inventory-reports details list 指令：

    gcloud storage insights inventory-reports details list CONFIG_NAME \
  --filter=EXPRESSION \
  --page-size=SIZE \
  --sort-by=FIELD

    更改項目：

    • CONFIG_NAME：庫存報表設定的專屬名稱，格式為 projects/PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID。

    • EXPRESSION：對要列出的每個資源項目套用布林值篩選條件。如果運算式評估結果為 True，系統就會列出項目。如要進一步瞭解篩選運算式並查看範例，請執行 $ gcloud topic filters。

    • SIZE，其中包含每頁的資源數量上限。預設值為 50。

    • FIELD：列出要做為排序依據的資源欄位索引鍵名稱，並以逗號分隔的清單呈現。預設為遞增排序。如要指定特定欄位採用遞減排序，請在該欄位前面加上 ~。

    如果成功，指令會傳回類似以下的輸出內容：

    REPORT_DETAIL_ID            SNAPSHOT_TIME
Report_2023-04-10T00-00     2023-04-10T00:53:03Z
Report_2023-04-12T00-00     2023-04-12T00:52:54Z
Report_2023-04-05T00-00     2023-04-05T00:53:01Z

  2. 如要下載商品目錄報表，您必須先擷取 ReportDetail 物件的 reportPathPrefix 屬性。如要取得報表的 reportPathPrefix，請使用 gcloud storage insights inventory-reports details describe 指令：

    gcloud storage insights inventory-reports details describe REPORT_DETAIL_NAME

    將 REPORT_DETAIL_NAME 替換為清查報表名稱，格式為 projects/PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID/reportDetails/REPORT_DETAIL_ID。

下載報表 shard

如要下載已分割成一或多個 shard 的庫存報表，請完成下列步驟：

  1. 使用 gcloud storage cp 指令下載清查報表資訊清單檔案：

    gcloud storage cp gs://BUCKET_NAME/MANIFEST_FILE_NAME DOWNLOAD_PATH

    更改項目：

    • BUCKET_NAME 替換為目的地 bucket 的名稱。

    • MANIFEST_FILE_NAME：目的地 bucket 中的資訊清單檔案名稱，命名慣例如下：

      REPORT_CONFIG_UUID_TARGET_DATETIME_manifest.json

      其中：

      • REPORT_CONFIG_UUID 是自動生成的 UUID，代表產生您要下載的報表 shard 的盤點報表設定。

      • TARGET_DATETIME 是產生商品目錄報表的日期時間。

      例如 fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。

    • DOWNLOAD_PATH 替換成要儲存目錄報表的檔案系統路徑。例如：./example_report.csv。

  2. 如要下載 shard 檔案，請使用 gcloud storage cp 指令：

    gcloud storage cp gs://BUCKET_NAME/SHARD_FILE_NAME DOWNLOAD_PATH

    更改項目：

    • BUCKET_NAME 替換為目的地 bucket 的名稱。

    • 將 SHARD_FILE_NAME 替換為要下載的 shard 檔案名稱 (經過網址編碼)。例如：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:54_0.csv。

    • DOWNLOAD_PATH 替換成要儲存目錄報表的檔案系統路徑。例如：./example_report.csv。

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


import com.google.cloud.storageinsights.v1.ReportConfig;
import com.google.cloud.storageinsights.v1.ReportConfigName;
import com.google.cloud.storageinsights.v1.ReportDetail;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import java.io.IOException;

public class GetInventoryReportNames {


  public static void getInventoryReportNames(
      String projectId, String location, String reportConfigUuid) throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfig config =
          storageInsightsClient.getReportConfig(
              ReportConfigName.of(projectId, location, reportConfigUuid));
      String extension = config.hasCsvOptions() ? "csv" : "parquet";
      System.out.println(
          "You can use the Google Cloud Storage Client "
              + "to download the following objects from Google Cloud Storage:");
      for (ReportDetail reportDetail :
          storageInsightsClient.listReportDetails(config.getName()).iterateAll()) {
        for (long index = reportDetail.getShardsCount() - 1; index >= 0; index--) {
          System.out.println(reportDetail.getReportPathPrefix() + index + "." + extension);
        }
      }
    }
  }
}

REST API

JSON API

下載個別報表

如要下載商品目錄報表，請完成下列步驟：

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

  2. 使用 cURL 呼叫 JSON API，並要求列出清查報表詳細資料，即可列出清查報表設定產生的所有清查報表：

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID/reportDetails/" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    • REPORT_CONFIG_UUID 替換為自動生成的 UUID，該 UUID 屬於產生您要下載報表的盤點報表設定。

  3. 如要取得個別報表的詳細資料，請使用 cURL 呼叫 JSON API，並傳送 Get ReportDetails 要求：

    curl --request GET \
"https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID/reportDetails/REPORT_DETAIL_ID" \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    • REPORT_CONFIG_UUID 替換為自動生成的 UUID，該 UUID 屬於產生您要下載報表的盤點報表設定。

    • 將 REPORT_DETAIL_ID 替換為要下載的庫存報表名稱。

下載報表 shard

如要下載已分割成一或多個 shard 的庫存報表，請完成下列步驟：

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

  2. 如要下載清查報表的資訊清單檔案，請使用 cURL 透過 GET 物件要求呼叫 JSON API：

    curl -X GET \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/MANIFEST_FILE_NAME?alt=media"

    更改項目：

    • BUCKET_NAME：目的地 bucket 的名稱。

    • MANIFEST_FILE_NAME：目的地 bucket 中的資訊清單檔案名稱，命名慣例如下：

      REPORT_CONFIG_UUID_TARGET_DATETIME_manifest.json

      其中：

      • REPORT_CONFIG_UUID 是自動生成的 UUID，代表產生您要下載的報表 shard 的庫存報表設定。

      • TARGET_DATETIME 是產生商品目錄報表的日期。

    例如 fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。

    資訊清單檔案的 report_shards_file_names 欄位包含可下載的庫存報表 shard 名稱。

  3. 如要下載盤點報表 shard 檔案，請使用 curl 呼叫 Cloud Storage JSON API，並傳送 Get 物件要求：

    curl -X GET \
  --header "Authorization: Bearer $(gcloud auth print-access-token)" \
  -o "DOWNLOAD_PATH" \
  "https://storage.googleapis.com/storage/v1/b/BUCKET_NAME/o/SHARD_FILE_NAME?alt=media"

    更改項目：

    • DOWNLOAD_PATH：本機檔案系統中要儲存物件的路徑。例如：Desktop/dog.png。

    • BUCKET_NAME 替換為包含清查報表的目標 bucket 名稱。例如：my-bucket。

    • SHARD_FILE_NAME：要下載的 shard 檔案名稱，須經過網址編碼。例如：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:54_0.csv。

刪除庫存報表設定

控制台

如要刪除庫存報表設定，請完成下列步驟：

  1. 前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。

    前往「Buckets」(值區) 頁面

  2. 在 bucket 清單中，點選含有要刪除的清查報表設定的來源 bucket 名稱。

  3. 在來源 bucket 的「Bucket details」(bucket 詳細資料) 頁面中，按一下「Inventory reports」(清查報表) 分頁標籤。

  4. 按一下要刪除的庫存報表設定名稱。

  5. 在隨即顯示的「Report configuration details」(報表設定詳細資料) 頁面中，按一下 「Delete」(刪除)。

指令列

如要刪除盤點報表設定，請使用 gcloud storage insights inventory-reports delete 指令：

gcloud storage insights inventory-reports delete CONFIG_NAME
  --force

將 CONFIG_NAME 替換為庫存報表設定的專屬名稱，格式為 projects/PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID。

--force 旗標會刪除指定庫存報表設定產生的所有庫存報表中繼資料。但不會刪除清查報表物件本身。

用戶端程式庫

Java

詳情請參閱 Cloud Storage Java API 參考文件。

如要向 Cloud Storage 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


import com.google.cloud.storageinsights.v1.ReportConfigName;
import com.google.cloud.storageinsights.v1.StorageInsightsClient;
import java.io.IOException;

public class DeleteInventoryReportConfig {


  public static void deleteInventoryReportConfig(
      String projectId, String location, String inventoryReportConfigUuid) throws IOException {
    try (StorageInsightsClient storageInsightsClient = StorageInsightsClient.create()) {
      ReportConfigName name = ReportConfigName.of(projectId, location, inventoryReportConfigUuid);
      storageInsightsClient.deleteReportConfig(name);

      System.out.println("Deleted inventory report config with name " + name);
    }
  }
}

REST API

JSON API

如要刪除庫存報表設定，請完成下列步驟：

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

  2. 如要刪除庫存報表設定，請使用 cURL 呼叫 JSON API，並傳送 Delete ReportConfig 要求：

    curl --request DELETE \
'https://storageinsights.googleapis.com/v1/projects/YOUR_PROJECT/locations/LOCATION/reportConfigs/REPORT_CONFIG_UUID?force=true' \
  --header 'Authorization: Bearer $(gcloud auth print-access-token)' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \

    更改項目：

    • YOUR_PROJECT：來源和目的地 bucket 所在的專案名稱。

    • LOCATION 替換為來源和目的地 bucket 的位置。例如：us-west1。

    • 將 REPORT_CONFIG_UUID 替換為要刪除的庫存報表設定自動產生的 UUID。

force 查詢參數會刪除由指定庫存報表設定產生的所有庫存報表中繼資料。但不會刪除清查報表物件本身。

進階：產生 Hive 分區格式的商品目錄報表

建立清查報表設定時，您可以指定目的地路徑，也就是目的地 bucket 中產生清查報表的位置。這樣一來，您就能以 Hive 分區格式產生商品目錄報表。

您可以使用預留位置關鍵字指定目的地路徑。產生商品目錄報表時，目的地路徑中的關鍵字會替換為相應的值。例如，目的地路徑 config={{report-config-id}}/date={{date}} 可解析為 config=1A34-F2E456-12B456-1C3D/date=2022-05-20。

目的地路徑關鍵字

您可以指定關鍵字 report-config-id、date 或 datetime，並以 {{ 和 }} 括住，其中：

  • report-config-id 是庫存報表設定的 UUID。

  • date 是產生商品目錄報表的日期。採用 ISO 8601 格式。

  • datetime 是產生庫存報表的日期和時間。採用 ISO 8601 格式。

您可以使用下列任一工具指定關鍵字：

  • 使用 Google Cloud 控制台時，請在「Enter destination path (optional)」(輸入目的地路徑 (選填)) 部分指定關鍵字。建立庫存報表設定時，系統會顯示這個部分。

  • 使用 Google Cloud CLI 時，請透過 --destination 旗標指定預留位置關鍵字。

  • 使用 JSON API 時，請在 ReportConfig 物件的 storage_destination_options.destination_path 欄位中指定預留位置關鍵字。

存取控管和安全性

以下是與庫存報表和設定的安全性和使用方式相關的建議和考量事項：

  • 建議具備 roles/storage.admin 角色的使用者也擁有 storageinsights.reportConfigs.* 權限，以便控管 bucket 中所有資源的使用情形，例如讀取物件和中繼資料。

  • 建議您只將 storageinsights.reportConfigs.* 權限授予必要人員，限制項目清單報表資源的存取權。

  • 建立庫存報表設定後，即使建立設定的使用者不再具備必要權限，系統仍會繼續產生庫存報表。如要停止產生庫存報表，可以編輯庫存報表設定中的結束日期，或完全刪除設定。

後續步驟

  • 如果產生庫存報表時遇到問題，請參閱「疑難排解」一節。