创建和管理资产清单报告

本页面介绍了如何创建和管理资产清单报告配置以及生成的资产清单报告，以便您可以获取给定存储桶中所有对象元数据的简略摘要。如需简要了解资产清单报告，请参阅存储空间分析资产清单报告概览文档。

准备工作

获取所需角色

为了获得创建和管理资产清单报告所需的权限，请让您的管理员向您授予将用于管理资产清单报告的项目或来源和目标存储桶的以下 IAM 角色。

  • 要创建和管理清单报告配置，请授予以下角色：

    • 针对源存储桶和目标存储桶的 roles/storage.admin

    • 针对项目的 roles/storageinsights.admin 权限

  • 如需读取和下载清单报告，请授予以下角色：

    • 针对目标存储桶的 roles/storage.objectViewer

    • 针对项目的 roles/storageinsights.viewer 权限

这些预定义角色包含创建和管理资产清单报告和配置所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和管理清单报告配置，请授予以下角色：

  • 针对源存储桶的 storage.buckets.get
  • 针对源存储桶的 storage.objects.list
  • 针对源存储桶的 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

控制台

如需启用 storageinsights.googleapis.com API，请按照启用服务中的说明操作。

命令行

如需在当前项目中启用 Storage Insights API，请运行以下命令：

gcloud services enable storageinsights.googleapis.com

如需详细了解如何为 Google Cloud 项目启用服务，请参阅启用和停用服务。

REST API

JSON API

使用 Google Cloud 控制台或 Google Cloud CLI 启用 Storage Insights API。

创建库存报告配置

控制台

如需创建资产清单报告配置，请完成以下步骤：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击要用作源存储桶的存储桶的名称。

  3. 在存储桶详细信息页面上，点击库存报告标签页。

  4. 点击创建报告配置。

  5. 在确定报告配置部分中，为库存报告配置创建显示名称。显示名称最多可包含 256 个字符。

  6. 在选择元数据字段部分中，选择要添加到库存报告中的元数据字段。

  7. 点击继续。

  8. 在选择文件格式部分中，选择用于生成资产清单报告的文件格式。

  9. 在选择目标存储桶部分中，选择要用作目标存储桶的存储桶。

    在输入目标路径（可选）部分中，您可以视需要指定生成资产清单报告的目标路径。

  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 替换为来源存储桶的网址。 例如 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 替换为您希望开始生成资产清单报告的世界协调时间 (UTC) 日期。例如 2022-01-15。

    • 将 FREQUENCY 替换为您希望生成资产清单报告的频率。值为 daily 或 weekly。

    • 将 END_DATE 替换为您希望停止生成资产清单报告的世界协调时间 (UTC) 日期。必须是 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 标头生成访问令牌。

    或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 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 替换为您希望开始生成资产清单报告的世界协调时间 (UTC) 日期。不能是当前日期，也不能是任何过去的日期。值必须是包含键 day、month 和 year 的对象。例如：{"day": 15, "month": 8, "year": 2022}。

    • 将 END_DATE 替换为您希望停止生成资产清单报告的世界协调时间 (UTC) 日期。值必须是包含键 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 替换为包含您要为其生成资产清单报告的对象的来源存储桶的名称。例如 my_example_bucket。

    • 将 METADATA_FIELD 替换为您要包含在资产清单报告中的元数据字段的英文逗号分隔列表。

    • 将 DESTINATION_BUCKET_NAME 替换为生成和存储资产清单报告的目标存储桶的名称。例如 my_example_destination_bucket。

    • 将 DESTINATION_PATH 替换为生成资产清单报告的目标存储桶的路径。此字段是可选字段。

      如果指定存储桶中文件夹的路径，则可以使用该路径中的关键字，在生成报告时，这些关键字将替换为相应的值。这样，您就可以使用 Hive 分区格式生成报告，从而在 BigQuery 中加载或查询数据，而无需额外的处理。

    例如，以下代码示例创建了名为“示例资产清单报告配置”的资产清单报告配置，该配置每周生成一次报告：

    {
  "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 通过 Insert 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

为服务代理授予所需的角色

首次设置库存报告配置时，系统会自动创建项目级服务代理。服务代理遵循命名格式 service-PROJECT_NUMBER@gcp-sa-storageinsights.iam.gserviceaccount.com，并显示在 Google Cloud 控制台的 IAM 页面上（如果您选择包括 Google 提供的角色授权复选框）。

如需允许存储空间分析生成和写入资产清单报告，请让您的管理员向服务代理授予以下 IAM 角色：

  • 针对源存储桶的 roles/storage.insightsCollectorService 权限（包括 storage.buckets.getObjectInsights 和 storage.buckets.get 权限）
  • 针对目标存储桶的 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 小时才能将第一份资产清单报告写入目标存储桶。

修改资产清单报告配置

创建资产清单报告配置后，您可以修改此配置的特定属性。

控制台

如需修改资产清单报告配置，请按照以下步骤操作：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击包含要修改的资产清单报告配置的源存储桶的名称。

  3. 在源存储桶的存储桶详情页面中，点击库存报告标签页。

  4. 点击要修改的资产清单报告配置的名称。

  5. 在显示的报告配置详细信息页面中，使用 修改按钮修改所需的属性。

命令行

如需修改资产清单报告配置，请按照以下步骤操作：

  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 替换为包含资产清单报告配置的来源存储桶的网址。

    • 将 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 标头生成访问令牌。

    或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

  2. 如需获取您要修改的资产清单报告配置的名称，请使用 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

    如果您要检索特定来源存储桶中的所有资产清单报告配置，请在请求中附加 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 替换为来源存储桶和目标存储桶所在项目的名称。
    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。
    • 将 BUCKET_NAME 替换为包含您要修改的资产清单报告配置的来源存储桶的名称。

  3. 创建一个包含要修改的属性更改的 JSON 文件。以下示例更新资产清单报告配置，以 Apache Parquet 格式每天生成资产清单报告：

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

  4. 如需应用资产清单报告配置，请使用 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

    • 将 REPORT_CONFIG_UUID 替换为资产清单报告配置的自动生成的 UUID。

列出资产清单报告配置

控制台

如需列出来源存储桶中的资产清单报告配置，请完成以下步骤：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击包含要查看的资产清单报告配置的来源存储桶的名称。

  3. 在存储桶详细信息页面上，点击库存报告标签页。

    此时会显示来源存储桶中的资产清单报告配置。

命令行

您可以使用 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 替换为包含资产清单报告配置的来源存储桶的网址。

  • 将 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 标头生成访问令牌。

    或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

    如果您要列出特定来来源存储桶中的所有资产清单报告配置，请在请求中附加 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

    • 将 BUCKET_NAME 替换为包含您要列出的资产清单报告配置的来来源存储桶的名称。

下载资产清单报告

控制台

下载各个报告

资产清单报告以对象形式生成并存储在目标存储桶中，因此您可以像下载常规对象一样下载它们。

如需下载资产清单报告，请完成以下步骤：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击包含要下载的库存报告的目标存储桶的名称。

  3. 在存储桶详细信息页面上，确保选中对象标签页。

  4. 点击与您要下载的库存报告关联的 下载。

如果您不知道目标存储桶，还可以通过生成报告的库存报告配置下载库存报告：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击包含生成您要下载的报告的库存报告配置的源存储桶的名称。

  3. 在存储桶详细信息页面上，点击库存报告配置的名称。

  4. 在显示的报告配置详情页面上，转到库存报告历史记录部分，然后点击要下载的库存报告的目标对象路径。

    系统会显示包含库存报告的目标存储桶的存储桶详情页面。

  5. 点击与您要下载的库存报告关联的 下载。

下载报告分片

如需下载拆分为一个或多个分片的资产清单报告，请完成以下步骤：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击您在创建资产清单报告配置时指定的目标存储桶的名称。

  3. 在存储桶详情页面上，检查是否存在清单文件。如果存在清单文件，则表示已生成资产清单报告的所有分片。

    示例清单文件名为 fc95c52f-157a-494f-af4a-d4a53a69ba66_2022-11-30T00:00_manifest.json。

  4. 在目标存储桶中，点击与清单文件关联的 下载。记下您要从 report_shards_file_names 字段中下载的分片文件的名称。

  5. 在目标存储桶中，点击与您要下载的分片文件关联的 下载。

命令行

下载各个报告

如需下载资产清单报告，请完成以下步骤：

  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 替换为目标存储桶的名称。

    • 将 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 替换为目标存储桶的名称。

    • 将 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

下载各个报告

如需下载资产清单报告，请完成以下步骤：

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

    或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

    • 将 REPORT_CONFIG_UUID 替换为生成您要下载的报告的资产清单报告配置的自动生成的 UUID。

  3. 如需获取单份报告的详细信息，请使用 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 LOCATION 替换为来源存储桶和目标存储桶的位置。例如 us-west1。

    • 将 REPORT_CONFIG_UUID 替换为生成您要下载的报告的资产清单报告配置的自动生成的 UUID。

    • 将 REPORT_DETAIL_ID 替换为您要下载的资产清单报告的名称。

下载报告分片

如需下载拆分为一个或多个分片的资产清单报告，请完成以下步骤：

  1. 安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

    或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 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 替换为目标存储桶的名称。

    • 将 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。

    清单文件的 report_shards_file_names 字段包含您可以下载的资产清单报告分片的名称。

  3. 如需下载资产清单报告分片文件，请使用 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。

删除资产清单报告配置

控制台

如需删除资产清单报告配置，请完成以下步骤：

  1. 在 Google Cloud 控制台中，进入 Cloud Storage 存储桶页面。

    进入“存储桶”

  2. 在存储桶列表中，点击包含要删除的库存报告配置的源存储桶的名称。

  3. 在源存储桶的存储桶详情页面中，点击库存报告标签页。

  4. 点击要删除的库存报告配置的名称。

  5. 在显示的报告配置详细信息页面中，点击 删除。

命令行

如需删除资产清单报告配置，请使用 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 标头生成访问令牌。

    或者，您可以创建访问令牌（使用 OAuth 2.0 Playground），并将其包含在 Authorization 标头中。

  2. 如需删除资产清单报告配置，请使用 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 替换为来源存储桶和目标存储桶所在项目的名称。

    • 将 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 控制台时，请在输入目标路径（可选）部分中指定关键字。此部分会在您创建资产清单报告配置时显示。

  • 使用 Google Cloud CLI 时，请使用 --destination 标志指定占位关键字。

  • 使用 JSON API 时，请在 ReportConfig 对象的 storage_destination_options.destination_path 字段中指定占位符关键字。

访问权限控制和安全

以下建议和注意事项与资产清单报告和配置的安全性和用法相关：

  • 我们建议具有 roles/storage.admin 角色的用户也具有 storageinsights.reportConfigs.* 权限，以便他们可以控制其存储桶中所有资源的使用情况，例如读取对象及其元数据。

  • 我们建议您通过仅向必要的个人授予 storageinsights.reportConfigs.* 权限来限制对资产清单报告资源的访问。

  • 创建资产清单报告配置后，即使创建该配置的用户不再拥有所需权限，它仍会继续生成资产清单报告。如需停止生成资产清单报告，您可以在资产清单报告配置中修改结束日期，也可以完全删除配置。

后续步骤

  • 如果您在生成资产清单报告时遇到问题，请参阅问题排查获取帮助。