使用庫存報表

本頁說明如何建立及管理目錄報告設定和產生的目錄報告，以便取得特定值區中所有物件中繼資料的摘要。如要瞭解庫存報表，請參閱庫存報表總覽說明文件。

事前準備

開始建立及管理資產盤點清單報告和資產盤點清單報告設定之前，請按照後續小節中的操作說明操作。

取得必要角色

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

如要建立及管理庫存報表設定，請按照下列步驟操作：
- 來源和目的地值區的 roles/storage.admin
- 專案的 roles/storageinsights.admin 權限
如要讀取及下載庫存報表，請按照下列步驟操作：
- 目的地值區的 roles/storage.objectViewer 權限
- 專案的 roles/storageinsights.viewer 權限

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

所需權限

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

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

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

目的地值區的 storage.objects.get 權限
專案的 storageinsights.reportDetails.get 權限
專案的 storageinsights.reportDetails.list 權限

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

如需如何使用角色控管值區存取權的操作說明，請參閱「使用 IAM」。如需如何使用角色控管專案存取權的操作說明，請參閱「管理存取權」。

啟用 Storage Insights API

控制台

啟用 Storage Insights API。

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

指令列

啟用 Storage Insights API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

gcloud services enable storageinsights.googleapis.com

REST API

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

如要啟用 Storage Insights 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。

建立庫存報表設定

控制台

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選要做為來源 bucket 的 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面上，按一下「Inventory reports」(清單報表) 分頁標籤。
按一下「建立報表設定」。
在「確認報表設定」部分，為庫存報表設定建立顯示名稱。顯示名稱的長度上限為 256 個字元。
在「選擇中繼資料欄位」部分，選取要納入廣告空間報表的中繼資料欄位。
按一下「繼續」。
在「選擇檔案格式」部分，選取要產生目錄報表的檔案格式。
在「選擇目的地 bucket」部分，選取要用做目的地 bucket 的 bucket。

在「輸入目的地路徑 (選填)」部分，您可以選擇指定目的地路徑，系統會在該路徑中產生廣告空間報表。
在「排程選項」部分，指定報表產生頻率、開始日期和結束日期。
點選「建立」。

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

指令列

如要建立庫存報表設定，請執行 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，並將其替換為來源值區的網址。例如：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，並提供要產生庫存報表的值區或資料夾。例如 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 日起停止產生商品目錄報表。

用戶端程式庫

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

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

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

建立包含下列資訊的 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"
    }
  }
}
```
更改項目：
- SOURCE_BUCKET_NAME，其中包含您要產生目錄報表物件的來源值區名稱。例如：my_example_bucket。
- METADATA_FIELD，並以半形逗號分隔的清單，指定要納入商品目錄報表的中繼資料欄位。
- DESTINATION_BUCKET_NAME，其中 destination bucket 是指系統產生並儲存庫存報表的目標 bucket 名稱。例如：my_example_destination_bucket。
- 將 DESTINATION_PATH 改成目的地值區的路徑，系統會將產生的庫存報表存放在該處。這是選填欄位。
  
  指定值區內資料夾的路徑時，您可以在路徑中使用關鍵字，產生報表時，這些關鍵字會替換為相應的值。這樣一來，您就能以 Hive 分區格式產生報表，以便在 BigQuery 中載入或查詢資料，不必進行額外處理。
注意： 如要以 Apache Parquet 格式產生目錄報表，請在目錄報表設定中加入 "parquet_options": {}，而非 "csv_options": {...}。

舉例來說，下列程式碼範例會建立名為「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"
    }
  }
}
```
如要套用目錄報表設定，請使用 cURL 透過 Create ReportConfig 要求呼叫 JSON API：
```
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，並提供來源和目的地值區的位置。例如：us-west1。

將必要角色授予服務代理

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

如要讓 Storage Insights 產生及寫入清單報表，請要求管理員授予服務代理程式下列 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 小時，才能將第一份庫存報表寫入目的地值區。

編輯庫存報表設定

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

控制台

如要編輯廣告空間報表設定，請按照下列步驟操作：

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，按一下包含要編輯的清單報表設定的來源 bucket 名稱。
在來源值區的「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，並以半形逗號分隔，列出要做為排序依據的資源欄位索引鍵名稱。預設為遞增排序。如要指定特定欄位採用遞減排序，請在該欄位前面加上 ~。
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

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

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

使用 cURL 透過 Get ReportConfig 要求呼叫 JSON API，取得要編輯的目錄報表設定名稱：
```
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，並提供來源和目的地值區的位置。例如：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，並提供來源和目的地值區的位置。例如：us-west1。
- BUCKET_NAME，並提供來源值區名稱，其中包含要編輯的目錄報表設定。
建立 JSON 檔案，其中包含要編輯的屬性變更。以下範例會更新庫存報表設定，以每天產生 Apache Parquet 格式的庫存報表：
```
{
  "ReportConfig": {
    "frequency_options": {
      "frequency": "DAILY"
    },
    "parquet_options": {
    }
  }
```
如要套用目錄報表設定，請使用 cURL 透過 Patch ReportConfig 要求呼叫 JSON API：
```
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，並提供來源和目的地值區的位置。例如：us-west1。
- REPORT_CONFIG_UUID，其中包含自動產生的資產盤點清單報告設定 UUID。

列出資產盤點清單報告設定

控制台

如要列出來源 bucket 中的目錄報告設定，請完成下列步驟：

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，按一下包含要查看的目錄報表設定的來源 bucket 名稱。
在「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，並以半形逗號分隔，列出要做為排序依據的資源欄位索引鍵名稱。預設為遞增排序。如要指定特定欄位採用遞減排序，請在該欄位前面加上 ~。

用戶端程式庫

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

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

如要列出專案中特定位置的所有廣告空間報表設定，請使用列出廣告空間報表設定的要求：
```
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，並提供來源和目的地值區的位置。例如：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，並提供來源和目的地值區的位置。例如：us-west1。
- BUCKET_NAME，並將其替換為包含要列出之商品目錄報表設定的來源值區名稱。

下載商品目錄報表

控制台

下載個別報表

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

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要下載的目錄報表的目標 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面中，確認已選取「Objects」(物件) 分頁標籤。
按一下要下載的廣告空間報表所對應的「下載」。

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有產生要下載報表之商品目錄報表設定的來源 bucket 名稱。
在「Bucket details」(Bucket 詳細資料) 頁面中，按一下清查報告設定的設定名稱。
在隨即顯示的「報表設定詳細資料」頁面中，前往「庫存報表記錄」部分，然後按一下要下載的庫存報表目的地物件路徑。

系統會顯示包含商品目錄報表的目標 bucket 的「Bucket details」(bucket 詳細資料) 頁面。
按一下要下載的廣告空間報表所對應的「下載」。

下載報表分片

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在值區清單中，按一下您建立商品型錄報表設定時指定目的地值區的名稱。
在「Bucket details」(值區詳細資料) 頁面中，檢查是否有資訊清單檔案。如果存在資訊清單檔案，表示所有庫存報表分片都已產生。

資訊清單檔案名稱範例：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。
在目標值區中，按一下資訊清單檔案的「下載」。請記下要從 report_shards_file_names 欄位下載的分片檔案名稱。
在目標值區中，按一下要下載的分片檔案所對應的「下載」。

指令列

下載個別報表

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

如要列出庫存報表設定產生的所有庫存報表，並擷取 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
```
如要下載商品目錄報表，請先擷取 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。

下載報表分片

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

使用 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，代表產生您要下載報表分片的庫存報表設定。
  - TARGET_DATETIME 是指產生庫存報表的日期時間。
  例如 fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。
- DOWNLOAD_PATH，並提供要儲存目錄報告的檔案系統路徑。例如：./example_report.csv。
如要下載分片檔案，請使用 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。

用戶端程式庫

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

下載個別報表

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

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

使用 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，並提供來源和目的地值區的位置。例如：us-west1。
- REPORT_CONFIG_UUID，其中包含產生要下載報表的庫存報表設定自動產生的 UUID。
如要取得個別報表的詳細資料，請使用 cURL 透過 Get ReportDetails 要求呼叫 JSON API：
```
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，並提供來源和目的地值區的位置。例如：us-west1。
- REPORT_CONFIG_UUID，其中包含產生要下載報表的庫存報表設定自動產生的 UUID。
- 將 REPORT_DETAIL_ID 替換為要下載的商品目錄報表名稱。

下載報表分片

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

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

如要下載目錄報表的資訊清單檔案，請使用 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，代表產生您要下載報表分片的資產盤點清單報表設定。
  - TARGET_DATETIME 是指產生目錄報表的日期。
例如 fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。

資訊清單檔案的 report_shards_file_names 欄位包含可下載的目錄報表分片名稱。
如要下載目錄報表分片檔案，請使用 curl 透過 Get 物件要求呼叫 Cloud Storage JSON API：
```
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，並填入包含庫存報表的目標值區名稱。例如：my-bucket。
- SHARD_FILE_NAME，並將其替換為要下載的檔案分片名稱 (經過網址編碼)。例如：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:54_0.csv。

刪除庫存報表設定

控制台

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在值區清單中，按一下包含要刪除的目錄報表設定來源值區名稱。
在來源值區的「Bucket details」(值區詳細資料) 頁面中，按一下「Inventory reports」(清單報表) 分頁標籤。
按一下要刪除的庫存報表設定名稱。
在隨即顯示的「報表設定詳細資料」頁面中，按一下「刪除」。

指令列

如要刪除庫存報表設定，請使用 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

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

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

如要刪除目錄報表設定，請使用 cURL 透過 Delete ReportConfig 要求呼叫 JSON API：
```
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，並提供來源和目的地值區的位置。例如：us-west1。
- REPORT_CONFIG_UUID，並提供要刪除的庫存報表設定自動產生的 UUID。

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

進階：以 Hive 分區格式產生廣告空間報表

建立廣告空間報表設定時，您可以指定目的地路徑，也就是目的地值區中要產生廣告空間報表的位置。這項功能可讓您以 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.* 權限，以便控管值區中所有資源的使用情形，例如讀取物件及其中繼資料。
建議您僅授予必要人員 storageinsights.reportConfigs.* 權限，限制存取廣告空間報表資源。
建立庫存報表設定後，即使建立設定的使用者不再具備必要權限，系統仍會繼續產生庫存報表。如要停止產生庫存報表，請編輯庫存報表設定中的結束日期，或完全刪除設定。

後續步驟

如果生成商品目錄報表時遇到問題，請參閱疑難排解。

使用庫存報表 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

取得必要角色

所需權限

啟用 Storage Insights API

控制台

指令列

REST API

建立庫存報表設定

控制台

指令列

用戶端程式庫

Java

REST API

JSON API

將必要角色授予服務代理

編輯庫存報表設定

控制台

指令列

用戶端程式庫

Java

REST API

JSON API

列出資產盤點清單報告設定

控制台

指令列

用戶端程式庫

Java

REST API

JSON API

下載商品目錄報表

控制台

下載個別報表

下載報表分片

指令列

下載個別報表

下載報表分片

用戶端程式庫

Java

REST API

JSON API

下載個別報表

下載報表分片

刪除庫存報表設定

控制台

指令列

用戶端程式庫

Java

REST API

JSON API

進階：以 Hive 分區格式產生廣告空間報表

目的地路徑關鍵字

存取控管和安全性

後續步驟

使用庫存報表