建立及管理商品目錄報表

控制台

如要啟用 storageinsights.googleapis.com API，請按照「啟用服務」一文中的操作說明進行。

指令列

如要在目前專案中啟用 Storage Insights API，請執行下列指令：

gcloud services enable storageinsights.googleapis.com

如要進一步瞭解如何為 Google Cloud 專案啟用服務，請參閱啟用及停用服務。

REST API

控制台

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

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下要當做來源值區的值區名稱。

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

4. 按一下「建立報表設定」。

5. 在「確認報表設定」部分，為庫存報表設定建立顯示名稱。顯示名稱的長度上限為 256 個字元。

6. 在「選擇中繼資料欄位」部分，選取要納入廣告空間報表的中繼資料欄位。

7. 按一下「繼續」。

8. 在「選擇檔案格式」部分，選取要產生目錄報表的檔案格式。

9. 在「選擇目的地 bucket」部分，選取要用做目的地 bucket 的 bucket。

   在「輸入目的地路徑 (選填)」部分，您可以選擇指定目的地路徑，系統會在該路徑中產生廣告空間報表。

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

11. 點選「建立」。

    系統隨即會顯示「報表設定詳細資料」頁面。頁面會顯示所產生庫存報表的相關中繼資料。

指令列

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，其中 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，並指定要產生庫存報表的 bucket 或 bucket 中的資料夾。例如 gs://my_example_destination_bucket 或 gs://my_example_destination_bucket/path/to/inventory/report。

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

   • METADATA_FIELD，並以半形逗號分隔，列出要納入商品目錄報表的中繼資料欄位。

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

   • FREQUENCY，設定產生目錄報表的頻率。值為 daily 或 weekly。

   • END_DATE，以世界標準時間為準，指定停止產生商品目錄報表的日期。必須是「START_DATE」之後的值。舉例來說，如果您指定 2022-02-15，系統將於 2022 年 2 月 16 日起停止產生商品目錄報表。

用戶端程式庫

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

控制台

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

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下包含要編輯的目錄報表設定來源值區名稱。

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

4. 按一下要編輯的商品目錄報表設定名稱。

5. 在隨即顯示的「報表設定詳細資料」頁面中，使用「編輯」edit按鈕編輯所需屬性。

指令列

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

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

   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"

用戶端程式庫

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

控制台

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

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下包含要查看的目錄報表設定來源值區名稱。

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

   系統會顯示來源值區中的資產盤點清單報告設定。

指令列

您可以使用 gcloud storage insights inventory-reports list 指令，列出來源值區中的所有廣告空間設定：

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，並以半形逗號分隔要排序的資源欄位鍵名稱。預設為遞增排序。如要依某個欄位遞減排序，請在該欄位加上 ~ 前置字串。

用戶端程式庫

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

控制台

下載個別報表

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

如要下載庫存報表，請完成下列步驟：

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下包含要下載的目錄報表的目標值區名稱。

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

4. 按一下要下載的廣告空間報表所對應的「下載」file_download。

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

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下包含產生要下載報表之商品目錄報表設定的來源值區名稱。

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

4. 在隨即顯示的「報表設定詳細資料」頁面中，前往「庫存報表記錄」部分，然後按一下要下載的庫存報表目的地物件路徑。

   系統會顯示目的地值區的「Bucket details」(值區詳細資料) 頁面，其中包含商品目錄報表。

5. 按一下要下載的廣告空間報表所對應的「下載」file_download。

下載報表分片

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

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下您建立商品型錄報表設定時指定的目的地值區名稱。

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

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

4. 在目標值區中，按一下資訊清單檔案相關聯的 file_download「下載」。請記下要從 report_shards_file_names 欄位下載的分片檔案名稱。

5. 在目標值區中，按一下要下載的碎片檔案所對應的「下載」file_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。

下載報表分片

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

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

   gcloud storage cp gs://BUCKET_NAME/MANIFEST_FILE_NAME DOWNLOAD_PATH

   取代：

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

   • MANIFEST_FILE_NAME，並遵循下列命名慣例：

     REPORT_CONFIG_UUID_TARGET_DATETIME_manifest.json

     其中：

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

     • TARGET_DATETIME 是指產生庫存報表的日期和時間。

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

   • DOWNLOAD_PATH，並提供要儲存目錄報告的檔案系統路徑。例如：./example_report.csv。

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

   gcloud storage cp gs://BUCKET_NAME/SHARD_FILE_NAME DOWNLOAD_PATH

   取代：

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

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

   • DOWNLOAD_PATH，並提供要儲存目錄報告的檔案系統路徑。例如：./example_report.csv。

用戶端程式庫

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

控制台

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

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

   前往「Buckets」(值區) 頁面

2. 在值區清單中，按一下包含要刪除的目錄報表設定來源值區名稱。

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

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

5. 在隨即顯示的「報表設定詳細資料」頁面中，按一下 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 會刪除指定庫存報表設定所產生所有庫存報表的中繼資料。但不會刪除目錄報表物件本身。

用戶端程式庫

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