使用 Cloud Asset Inventory 导出资产元数据

使用 Cloud Asset Inventory 导出资产元数据

本快速入门介绍如何使用 Cloud Asset Inventory 和 Google Cloud CLI gcloud asset 命令导出某个时间点的资产元数据。

准备工作

您必须先启用 Cloud Asset Inventory API 和 Google Cloud CLI 并分配权限，然后才能开始使用 Cloud Asset Inventory。Google Cloud CLI 与 Cloud Asset Inventory 和其他 Google Cloud 服务进行交互。详细了解 gcloud CLI。

启用 Cloud Asset Inventory API 和 Google Cloud CLI

1. 登录您的 Google Cloud 帐号。如果您是 Google Cloud 新手，请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

2. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

3. 启用所需的 API。

   启用 API

4. 安装 Google Cloud CLI。

5. 如需初始化 gcloud CLI，请运行以下命令：

   gcloud init

6. 在 Google Cloud Console 中的项目选择器页面上，选择或创建一个 Google Cloud 项目。

   注意：如果您不打算保留在此过程中创建的资源，请创建新的项目，而不要选择现有的项目。完成本教程介绍的步骤后，您可以删除所创建的项目，并移除与该项目关联的所有资源。

   转到“项目选择器”

7. 启用所需的 API。

   启用 API

8. 安装 Google Cloud CLI。

9. 如需初始化 gcloud CLI，请运行以下命令：

   gcloud init

配置权限

如需调用 Cloud Asset Inventory API，您必须先配置权限。

搜索资源

如需搜索资源元数据，请运行以下命令。

gcloud asset search-all-resources \
    --scope=SCOPE \
    --query="QUERY" \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --order-by="ORDER_BY" \
    --read-mask="READ_MASK"

请提供以下值：

• SCOPE：可选。范围可以是项目、文件夹或组织。搜索范围仅限于此范围内的 Google Cloud 资源。调用者必须被授予所需范围的 cloudasset.assets.searchAllResources 权限。如果未指定，则系统会使用已配置的项目属性。

  允许使用的值包括：

  • projects/PROJECT_ID

  • projects/PROJECT_NUMBER

    如何查找 Google Cloud 项目编号

    控制台

    如需查找 Google Cloud 项目编号，请完成以下步骤：

    1. 前往 Google Cloud 控制台中的信息中心页面。

       前往信息中心

    2. 点击菜单栏中的切换器框。
    3. 从请选择：框中选择您的组织，然后搜索项目名称。
    4. 点击项目名称以切换到该项目。项目信息卡片中会显示项目编号。

    gcloud CLI

    您可以使用以下命令检索 Google Cloud 项目编号：

    gcloud projects describe PROJECT_ID --format="value(projectNumber)"

  • folders/FOLDER_ID

    如何查找 Google Cloud 文件夹 ID

    控制台

    如需查找 Google Cloud 文件夹 ID，请完成以下步骤：

    1. 转到 Google Cloud 控制台。

       转到 Google Cloud 控制台

    2. 点击菜单栏中的切换器框。
    3. 点击选择范围框，然后选择您的组织。
    4. 搜索文件夹名称。文件夹 ID 会显示在文件夹名称旁边。

    gcloud CLI

    您可以使用以下命令检索位于组织级别的 Google Cloud 文件夹 ID：

    gcloud resource-manager folders list \
        --organization=$(gcloud organizations describe ORGANIZATION_NAME \
          --format="value(name.segment(1))") \
        --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
        --format="value(ID)"

    其中，TOP_LEVEL_FOLDER_NAME 可以是完全或部分字符串匹配。移除 --format 选项可查看有关找到的文件夹的更多信息。

    如需获取其他文件夹中某个文件夹的 ID，请列出各子文件夹：

    gcloud resource-manager folders list --folder=FOLDER_ID

  • organizations/ORGANIZATION_ID

    如何查找 Google Cloud 组织 ID

    控制台

    如需查找 Google Cloud 组织 ID，请完成以下步骤：

    1. 转到 Google Cloud 控制台。

       转到 Google Cloud 控制台

    2. 点击菜单栏中的切换器框。
    3. 点击选择范围框，然后选择您的组织。
    4. 点击全部标签页。组织 ID 显示在组织名称旁边。

    gcloud CLI

    您可以使用以下命令检索 Google Cloud 组织 ID：

    gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

• QUERY：可选。查询语句。如需了解详情，请参阅查询语法。如果未指定或为空，Cloud Asset Inventory 搜索指定 scope 中的所有资源。

  示例：

  • name:Important，用于查找名称包含 Important 一词的 Google Cloud 资源。

  • name=Important，用于查找名称确切的 Google Cloud 资源：Important。

  • displayName:Impor*，用于查找显示名称包含 Impor 作为前缀的 Google Cloud 资源。

  • location:us-west*，用于查找位置同时包含 us 和 west 作为前缀的 Google Cloud 资源。

  • labels:prod，用于查找标签中包含 prod 作为键或值的 Google Cloud 资源。

  • labels.env:prod，用于查找具有 env 标签且其值为“prod”的 Google Cloud 资源。

  • labels.env:* 用于查找标签为 env 的 Google Cloud 资源。

  • kmsKeys:key，用于查找使用客户管理的加密密钥加密的 Google Cloud 资源，该密钥的名称中包含 key 一词。

  • sccSecurityMarks.key=value，用于查找以一对安全标记（其键为 key，值为 value）附加的 Google Cloud 资源。

  • sccSecurityMarks.key:*，用于查找通过一对安全标记（密钥为 key）附加的 Google Cloud 资源。

  • state:ACTIVE，用于查找状态包含 ACTIVE 一词的 Google Cloud 资源。

  • NOT state:ACTIVE，用于查找状态不包含 ACTIVE 这个单词的 Google Cloud 资源。

  • createTime<1609459200、createTime<2021-01-01 或 createTime<"2021-01-01T00:00:00"，用于查找在世界协调时间 (UTC) 2021-01-01 00:00:00 之前创建的 Google Cloud 资源。1609459200 是 2021-01-01 00:00:00 UTC 的纪元时间戳（以秒为单位）。

  • updateTime>1609459200、updateTime>2021-01-01 或 updateTime>"2021-01-01T00:00:00"，用于查找在世界协调时间 (UTC) 2021 年 1 月 1 日 00:00:00 之后更新的 Google Cloud 资源。1609459200 是 2021-01-01 00:00:00 UTC 的纪元时间戳（以秒为单位）。

  • project:12345 用于查找属于编号为 12345 的 Google Cloud 项目的 Google Cloud 资源。项目 ID 不受支持。

  • folders:(123 or 456)，用于查找作为编号为 123 或 456 的 Google Cloud 文件夹后代的 Google Cloud 资源。

  • organization:123，用于查找作为编号为 123 的 Google Cloud 组织的后代的 Google Cloud 资源。

  • parentFullResourceName:ImportantName，用于查找父级名称包含 ImportantName 的 Google Cloud 资源。

  • parentAssetType:Project，用于查找父项资产类型包含 Project 的 Google Cloud 资源。

  • Important，用于查找任何可搜索字段中包含 Important 字词的 Google Cloud 资源。

  • Impor*，用于查找在任何可搜索字段中包含 Impor 作为前缀的 Google Cloud 资源。

  • Important location:(us-west1 OR global)，用于查找任何可搜索字段中包含“重要”一词且位于 us-west1 区域或 global 位置的 Google Cloud 资源。

• ASSET_TYPE：可选。以英文逗号分隔的可搜索素材资源类型列表。支持与 RE2 兼容的正则表达式。如果正则表达式与任何受支持的素材资源类型都不匹配，则会返回 INVALID_ARGUMENT 错误。

• ORDER_BY：可选。以英文逗号分隔的字段列表，用于指定结果的排序顺序。默认顺序是升序。在字段名称后面添加 " DESC" 以表示降序。多余的空格字符会被忽略。示例："location DESC, name"。只有响应中的单个基元字段可以排序：

  • name

  • assetType

  • project

  • displayName

  • description

  • location

  • createTime

  • updateTime

  • state

  • parentFullResourceName

  • parentAssetType

  重复字段（例如 networkTags、kmsKeys）、映射字段（例如 labels）和结构体字段（例如 additionalAttributes）等其他字段不受支持。

• READ_MASK：可选。以英文逗号分隔的字段列表，用于指定要在结果中返回哪些字段。如果未指定，则系统会返回除 versionedResources 之外的所有字段。如果仅指定 "*"，则返回所有字段。示例："name,location"、"name,versionedResources"、"*"。

如需详细了解如何搜索资源，请参阅搜索资源。

搜索 IAM 政策

如需搜索 Identity and Access Management (IAM) 政策，请运行以下命令。

gcloud asset search-all-iam-policies \
  --scope=SCOPE \
  --query="QUERY" \
  --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
  --order-by="ORDER_BY"

请提供以下值：

• SCOPE：可选。范围可以是项目、文件夹或组织。搜索范围仅限于此范围内的 IAM 资源。调用者必须被授予所需范围的 cloudasset.assets.searchAllIamPolicies 权限。如果未指定，则系统会使用已配置的项目属性。

  允许使用的值包括：

  • projects/PROJECT_ID

  • projects/PROJECT_NUMBER

    如何查找 Google Cloud 项目编号

    控制台

    如需查找 Google Cloud 项目编号，请完成以下步骤：

    1. 前往 Google Cloud 控制台中的信息中心页面。

       前往信息中心

    2. 点击菜单栏中的切换器框。
    3. 从请选择：框中选择您的组织，然后搜索项目名称。
    4. 点击项目名称以切换到该项目。项目信息卡片中会显示项目编号。

    gcloud CLI

    您可以使用以下命令检索 Google Cloud 项目编号：

    gcloud projects describe PROJECT_ID --format="value(projectNumber)"

  • folders/FOLDER_ID

    如何查找 Google Cloud 文件夹 ID

    控制台

    如需查找 Google Cloud 文件夹 ID，请完成以下步骤：

    1. 转到 Google Cloud 控制台。

       转到 Google Cloud 控制台

    2. 点击菜单栏中的切换器框。
    3. 点击选择范围框，然后选择您的组织。
    4. 搜索文件夹名称。文件夹 ID 会显示在文件夹名称旁边。

    gcloud CLI

    您可以使用以下命令检索位于组织级别的 Google Cloud 文件夹 ID：

    gcloud resource-manager folders list \
        --organization=$(gcloud organizations describe ORGANIZATION_NAME \
          --format="value(name.segment(1))") \
        --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
        --format="value(ID)"

    其中，TOP_LEVEL_FOLDER_NAME 可以是完全或部分字符串匹配。移除 --format 选项可查看有关找到的文件夹的更多信息。

    如需获取其他文件夹中某个文件夹的 ID，请列出各子文件夹：

    gcloud resource-manager folders list --folder=FOLDER_ID

  • organizations/ORGANIZATION_ID

    如何查找 Google Cloud 组织 ID

    控制台

    如需查找 Google Cloud 组织 ID，请完成以下步骤：

    1. 转到 Google Cloud 控制台。

       转到 Google Cloud 控制台

    2. 点击菜单栏中的切换器框。
    3. 点击选择范围框，然后选择您的组织。
    4. 点击全部标签页。组织 ID 显示在组织名称旁边。

    gcloud CLI

    您可以使用以下命令检索 Google Cloud 组织 ID：

    gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

• QUERY：可选。查询语句。如需了解详情，请参阅查询语法。如果未指定或为空，Cloud Asset Inventory 搜索指定 scope 中的所有 IAM 政策。系统会将查询字符串与每个 IAM 政策绑定（包括其主帐号、角色和 IAM 条件）进行比较。返回的 IAM 政策仅包含与您的查询匹配的绑定。如需详细了解 IAM 政策结构，请参阅政策结构。

  示例：

  • policy:[e-mail] 以查找指定用户 [e-mail] 的 IAM 政策绑定。

  • policy:roles/compute.admin，以查找指定 Compute Admin 角色的 IAM 政策绑定。

  • policy:comp*，用于查找包含 comp 作为绑定中任何单词前缀的 IAM 政策绑定。

  • policy.role.permissions:storage.buckets.update 查找指定包含 storage.buckets.update 权限的角色的 IAM 政策绑定。如果调用方对某个角色的包含权限没有 iam.roles.get 访问权限，则指定此角色的政策绑定将从搜索结果中删除。

  • policy.role.permissions:upd*，以查找 IAM 政策绑定，这些绑定指定包含 upd 作为角色权限中任何字词前缀的角色。请注意，如果调用方对某个角色包含的权限没有 iam.roles.get 访问权限，系统会从搜索结果中删除指定此角色的政策绑定。

  • resource:organizations/123456，用于查找在“organizations/123456”上设置的 IAM 政策绑定。

  • resource=//cloudresourcemanager.googleapis.com/projects/myproject，用于查找在名为 myproject 的项目上设置的 IAM 政策绑定。

  • Important，用于查找任何可搜索字段中包含 Important 一词的 IAM 政策绑定（包含的权限除外）。

  • resource:(instance1 OR instance2) policy:amy，用于查找在资源 instance1 或 instance2 上设置的 IAM 政策绑定，还指定了用户 amy。

  • roles:roles/compute.admin，以查找指定 Compute Admin 角色的 IAM 政策绑定。

  • memberTypes:user，用于查找包含 user 主帐号类型的 IAM 政策绑定。

• ASSET_TYPE：可选。IAM 政策所附加到的可搜索资产类型的逗号分隔列表。如果为空，则 Cloud Asset Inventory 搜索附加到所有可搜索资产类型的 IAM 政策。支持正则表达式。如果正则表达式与任何受支持的资源类型类型都不匹配，则会返回 INVALID_ARGUMENT 错误。

• ORDER_BY：可选。以英文逗号分隔的字段列表，用于指定结果的排序顺序。默认顺序是升序。在字段名称后面添加 " DESC" 以表示降序。多余的空格字符会被忽略。示例："location DESC, name"。只有响应中的单个基元字段可以排序：

  • resource

  • assetType

  • project

  重复字段（如 folders）和非基元字段（如 policy）等其他字段不受支持。

如需详细了解如何搜索 IAM 政策，请参阅搜索 IAM 政策。

将资源快照导出到 Cloud Storage

如需将给定时间戳处的所有资产元数据导出到 Cloud Storage 存储桶中的文件，请完成以下步骤。

1. 创建新存储桶（如果您还没有存储桶）。

2. 如需导出项目中的资产元数据，请运行以下命令。此命令会将导出的快照存储在位于 gs://BUCKET_NAME/FILENAME 的文件中。

   项目

   gcloud asset export \
       --project=PROJECT_ID \
       --billing-project=BILLING_PROJECT_ID \
       --content-type=CONTENT_TYPE \
       --snapshot-time="SNAPSHOT_TIME" \
       --output-path="gs://BUCKET_NAME/FILENAME"
   

   请提供以下值：

   • PROJECT_ID：您要导出其元数据的项目的 ID。

   • BILLING_PROJECT_ID：可选。默认 Cloud Asset Inventory 服务代理所在的项目 ID，用于向您的 Cloud Storage 存储桶写入数据。如果您已切换到具有 gcloud config set project 的结算项目，则无需执行此操作。详细了解结算项目。

   • CONTENT_TYPE：可选。要导出的资产的内容类型。如果未指定内容类型，则仅返回资产名称。详细了解内容类型。

   • SNAPSHOT_TIME：可选。您希望截取资产快照的时间。值必须是当前时间或过去 35 天内的时间。如果未提供，系统会在当前时间截取快照。如需了解时间格式，请参阅 gcloud topic DateTimes。

   • BUCKET_NAME：要写入数据的 Cloud Storage 存储桶的名称。

   • FILENAME：Cloud Storage 存储桶中要写入数据的文件。

   文件夹

   gcloud asset export \
       --folder=FOLDER_ID \
       --billing-project=BILLING_PROJECT_ID \
       --content-type=CONTENT_TYPE \
       --snapshot-time="SNAPSHOT_TIME" \
       --output-path="gs://BUCKET_NAME/FILENAME"
   

   请提供以下值：

   • FOLDER_ID：您要导出其元数据的文件夹的 ID。

     如何查找 Google Cloud 文件夹 ID

     控制台

     如需查找 Google Cloud 文件夹 ID，请完成以下步骤：

     1. 转到 Google Cloud 控制台。

        转到 Google Cloud 控制台

     2. 点击菜单栏中的切换器框。
     3. 点击选择范围框，然后选择您的组织。
     4. 搜索文件夹名称。文件夹 ID 会显示在文件夹名称旁边。

     gcloud CLI

     您可以使用以下命令检索位于组织级别的 Google Cloud 文件夹 ID：

     gcloud resource-manager folders list \
         --organization=$(gcloud organizations describe ORGANIZATION_NAME \
           --format="value(name.segment(1))") \
         --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
         --format="value(ID)"

     其中，TOP_LEVEL_FOLDER_NAME 可以是完全或部分字符串匹配。移除 --format 选项可查看有关找到的文件夹的更多信息。

     如需获取其他文件夹中某个文件夹的 ID，请列出各子文件夹：

     gcloud resource-manager folders list --folder=FOLDER_ID

   • BILLING_PROJECT_ID：可选。默认 Cloud Asset Inventory 服务代理所在的项目 ID，用于向您的 Cloud Storage 存储桶写入数据。如果您已切换到具有 gcloud config set project 的结算项目，则无需执行此操作。详细了解结算项目。

   • CONTENT_TYPE：可选。要导出的资产的内容类型。如果未指定内容类型，则仅返回资产名称。详细了解内容类型。

   • SNAPSHOT_TIME：可选。您希望截取资产快照的时间。值必须是当前时间或过去 35 天内的时间。如果未提供，系统会在当前时间截取快照。如需了解时间格式，请参阅 gcloud topic DateTimes。

   • BUCKET_NAME：要写入数据的 Cloud Storage 存储桶的名称。

   • FILENAME：Cloud Storage 存储桶中要写入数据的文件。

   组织

   gcloud asset export \
       --organization=ORGANIZATION_ID \
       --billing-project=BILLING_PROJECT_ID \
       --content-type=CONTENT_TYPE \
       --snapshot-time="SNAPSHOT_TIME" \
       --output-path="gs://BUCKET_NAME/FILENAME"
   

   请提供以下值：

   • ORGANIZATION_ID：您要导出其元数据的组织的 ID。

     如何查找 Google Cloud 组织 ID

     控制台

     如需查找 Google Cloud 组织 ID，请完成以下步骤：

     1. 转到 Google Cloud 控制台。

        转到 Google Cloud 控制台

     2. 点击菜单栏中的切换器框。
     3. 点击选择范围框，然后选择您的组织。
     4. 点击全部标签页。组织 ID 显示在组织名称旁边。

     gcloud CLI

     您可以使用以下命令检索 Google Cloud 组织 ID：

     gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

   • BILLING_PROJECT_ID：可选。默认 Cloud Asset Inventory 服务代理所在的项目 ID，用于向您的 Cloud Storage 存储桶写入数据。如果您已切换到具有 gcloud config set project 的结算项目，则无需执行此操作。详细了解结算项目。

   • CONTENT_TYPE：可选。要导出的资产的内容类型。如果未指定内容类型，则仅返回资产名称。详细了解内容类型。

   • SNAPSHOT_TIME：可选。您希望截取资产快照的时间。值必须是当前时间或过去 35 天内的时间。如果未提供，系统会在当前时间截取快照。如需了解时间格式，请参阅 gcloud topic DateTimes。

   • BUCKET_NAME：要写入数据的 Cloud Storage 存储桶的名称。

   • FILENAME：Cloud Storage 存储桶中要写入数据的文件。

3. 可选：如需检查导出状态，请运行以下命令。运行导出命令后，它会显示在 gcloud CLI 中。

   gcloud asset operations describe OPERATION_PATH
   

查看资产快照

如需在将资产快照导出到 Cloud Storage 后对其进行查看，请完成以下步骤。

1. 转到 Google Cloud 控制台中的 Cloud Storage 存储分区页面。

   进入“存储桶”

2. 打开元数据导出到的文件。

导出文件会列出资产及其资源名称。

后续步骤

• 详细了解 Cloud Asset Inventory。

• 了解如何获取资产的历史记录。