Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用庫存報表

本頁面說明如何建立及管理庫存報表設定，以及如何產生庫存報表，以便取得特定 bucket 中所有物件中繼資料的高階摘要。如要概略瞭解庫存報表，請參閱庫存報表總覽說明文件。

事前準備

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

取得必要角色

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

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

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

所需權限

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

來源 bucket 上的 storage.buckets.get
來源 bucket 的 storage.objects.list
來源 bucket 上的 storage.buckets.getObjectInsights
storage.buckets.get 目的地 bucket
storage.objects.create 目的地 bucket
專案的 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

控制台

如果尚未啟用，請啟用 Storage Insights API。

啟用 API 所需的角色

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

啟用 API

指令列

如果尚未啟用 Storage Insights API，請啟用：

啟用 API 所需的角色

gcloud services enable storageinsights.googleapis.com

REST API

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

如要啟用儲存空間分析 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」(商品目錄報表) 分頁標籤。
按一下「Create report configuration」(建立報表設定)。
在「Identify your report configuration」(確認報表設定) 部分，建立庫存報表設定的顯示名稱。顯示名稱最多可包含 256 個字元。
在「Choose metadata fields」(選擇中繼資料欄位) 區段中，選取要納入清查報表的中繼資料欄位。
按一下「繼續」。
在「選擇檔案格式」部分，選取要產生廣告空間報表的檔案格式。
在「選擇目的地 bucket」部分，選取要用做目的地 bucket 的 bucket。

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

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

指令列

如要建立庫存報表設定，請執行 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。
  
  指定值區內資料夾的路徑時，您可以在路徑中使用關鍵字，系統會在產生報表時，將這些關鍵字替換為相應的值。這樣一來，您就能以 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"
    }
  }
}
```
更改項目：
- 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，其中 DESTINATION_BUCKET_NAME 是目的地 bucket 的名稱，系統會產生並儲存庫存報表。例如：my_example_destination_bucket。
- DESTINATION_PATH：產生庫存報表的目的地 bucket 路徑。這是選填欄位。
  
  指定 bucket 內資料夾的路徑時，您可以在路徑中使用關鍵字，系統會在產生報表時將關鍵字替換為對應的值。這樣一來，您就能以 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 呼叫 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 命名格式，並在您選取「包含 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 小時，才能將第一份庫存報表寫入目的地值區。

編輯庫存報表設定

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

控制台

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

前往 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呼叫 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 的名稱，其中包含要編輯的商品目錄報表設定。

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

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

如要套用清查報表設定，請使用 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 中的目錄報表設定，請完成下列步驟：

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選來源 bucket 的名稱，其中包含您要查看的庫存報表設定。
在「Bucket details」(值區詳細資料) 頁面中，按一下「Inventory reports」(庫存報表) 分頁標籤。

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

指令列

您可以使用 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

安裝並初始化 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，其中包含來源和目的地 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 中，因此您可以像下載一般物件一樣下載報表。

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要下載清查報表的目的地 bucket 名稱。
在「Bucket details」(值區詳細資料) 頁面中，確認已選取「Objects」(物件) 分頁標籤。
按一下要下載的商品目錄報表相關聯的「Download」(下載)。

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

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

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

下載報表分片

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

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

資訊清單檔案名稱範例如下：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。
在目的地 bucket 中，按一下與資訊清單檔案相關聯的「 Download」(下載)。記下要從 report_shards_file_names 欄位下載的 shard 檔案名稱。
在目標 bucket 中，按一下要下載的 shard 檔案所對應的「下載」。

指令列

下載個別報表

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

如要列出由盤點報表設定產生的所有盤點報表，並擷取其 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，代表產生您要下載的報表 shard 的庫存報表設定。
  - 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 替換為要下載的 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

下載個別報表

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

安裝並初始化 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 替換為來源和目的地 bucket 的位置。例如：us-west1。
- REPORT_CONFIG_UUID 替換為自動生成的 UUID，該 UUID 屬於產生您要下載報表的盤點報表設定。
如要取得個別報表的詳細資料，請使用 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。
- 將 REPORT_DETAIL_ID 替換為要下載的目錄報表名稱。

下載報表分片

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

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
如要下載目錄報表的資訊清單檔案，請使用 cURL 呼叫 JSON API，並發出 GET 物件要求：
```
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 欄位包含可下載的商品目錄報表分片名稱。
如要下載商品目錄報表分片檔案，請使用 curl 呼叫 Cloud Storage JSON API，並發出 Get Object 要求：
```
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 替換為要下載的分片檔案的網址編碼名稱。例如：fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:54_0.csv。

刪除庫存報表設定

控制台

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

前往 Google Cloud 控制台的「Cloud Storage bucket」頁面。
前往「Buckets」(值區) 頁面
在 bucket 清單中，點選含有要刪除廣告空間報表設定的來源 bucket 名稱。
在來源 bucket 的「Bucket details」(bucket 詳細資料) 頁面中，按一下「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 呼叫 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.* 權限，以便控管值區中所有資源的使用情形，例如讀取物件及其中繼資料。
建議您只授予必要人員 storageinsights.reportConfigs.* 權限，限制存取項目清單報表資源。
建立庫存報表設定後，即使建立設定的使用者不再具備必要權限，系統仍會繼續產生庫存報表。如要停止產生庫存報表，可以編輯庫存報表設定中的結束日期，或完全刪除設定。

後續步驟

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

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

事前準備

取得必要角色

所需權限

啟用儲存空間分析 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 分區格式產生清查報表

目的地路徑關鍵字

存取控管和安全性

後續步驟

使用庫存報表