导出到 BigQuery

本主题介绍如何将组织、文件夹或项目的资产元数据导出到 BigQuery 表,然后对目录运行数据分析。BigQuery 提供类似于 SQL 的体验,让用户可以分析数据,并生成有意义的分析洞见,而无需使用自定义脚本。

准备工作

在开始之前,请完成以下步骤。

  1. 在将运行 API 命令的项目中启用 Cloud Asset Inventory API。
    启用 Cloud Asset Inventory API

  2. 使用 gcloud 工具API 配置调用 Cloud Asset Inventory API 所需的权限

  3. 完成以下步骤以设置您的环境。

    gcloud

    要设置环境以使用 gcloud 工具调用 Cloud Asset Inventory API,请在本地客户端上安装 Cloud SDK

    API

    要设置环境以使用 Unix curl 命令调用 Cloud Asset Inventory API,请完成以下步骤。

    1. 在本地机器上安装 oauth2l,以便与 Google OAuth 系统进行互动。
    2. 确认您可以使用 Unix curl 命令。
    3. 确保向您的账号授予项目、文件夹或组织的以下角色之一。

      • Cloud Asset Viewer 角色 (roles/cloudasset.viewer)
      • Owner 基本角色 (roles/owner)
  4. 如果您要导出到未启用 Cloud Asset Inventory API 的项目中的 BigQuery 数据集,则还必须将以下角色授予目标项目中的 service-${CONSUMER_PROJECT_NUMBER}@gcp-sa-cloudasset.iam.gserviceaccount.com 服务帐号。

    • BigQuery Data Editor 角色 (roles/bigquery.dataEditor)
    • BigQuery User 角色 (roles/bigquery.user)

    只需调用 API 一次就可创建服务帐号,或者您也可以使用以下命令:

      gcloud beta services identity create --service=cloudasset.googleapis.com --project=PROJECT_ID
    

  5. 创建 BigQuery 数据集

导出资产快照

如需导出给定时间戳的资产快照,请完成以下步骤。

gcloud

要导出项目中的资产,请运行以下命令。此命令将导出的快照存储在 BIGQUERY_TABLE 的 BigQuery 表中。

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force

其中:

  • CONTENT_TYPE 是资产内容类型
  • PROJECT_ID 是要导出其元数据的项目的 ID。此项目可以是您从中运行导出的项目,也可以是其他项目。
  • SNAPSHOT_TIME(可选)是您希望截取资源快照的时间。值必须是当前时间或过去的时间。默认情况下,截取当前时间的快照。如需了解时间格式,请参阅 gcloud topic datetimes
  • BIGQUERY_TABLE 是您要将元数据导出到其中的表,格式为 projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME
  • --output-bigquery-force 会覆盖目标表(如果存在)。

如需导出组织或文件夹的资源,您可以使用以下标志之一来替换 --project

您只能为 --organization 导出 access-policy

API

要导出项目中的资产元数据,请运行以下命令。此命令将导出的快照存储在名为 TABLE_NAME 的 BigQuery 表中。详细了解 exportAssets 方法。

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

设置内容类型

每个 BigQuery 表由描述列名、数据类型和其他信息的架构进行定义。在导出过程中设置的内容类型决定了表的架构。

  • 资源或未指定:如果将内容类型设置为 RESOURCE 或未设置内容类型,就会创建具有图 1 所示架构的 BigQuery 表。Resource.data 是表示为 JSON 字符串的资源元数据。

  • IAM 政策:如果在 REST API 中将内容类型设置为 IAM_POLICY,或在 gcloud 工具中将内容类型设置为 iam-policy,就会创建具有图 2 所示架构的 BigQuery 表。iam_policy RECORD 是完全展开的。

  • 组织政策:如果在 REST API 中将内容类型设置为 ORG_POLICY,或在 gcloud 工具中将内容类型设置为 org-policy,就会创建具有图 3 所示架构的 BigQuery 表。

  • VPCSC 政策:如果在 REST API 中将内容类型设置为 ACCESS_POLICY,或在 gcloud 工具中将内容类型设置为 access-policy,就会创建具有图 4 所示架构的 BigQuery 表。

  • OSConfig 实例清单:在 REST API 中将内容类型设置为 OS_INVENTORYgcloud 工具中的 os-inventory 时,您需要创建一个 BigQuery 表格,该表格具有图 5 所示架构。

按资源类型导出到不同的表

如需按资源类型导出给定时间戳的资产快照,请完成以下步骤:

gcloud

如需按资源类型导出项目中的资产,请运行以下命令。此命令会将导出的快照存储在零个表(如果快照结果为空)或多个 BigQuery 表中。每个表都包含一个资产类型的结果,并且 BIGQUERY_TABLE_(下划线)和资产类型名称串联。非字母数字字符将被替换为 _

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --output-bigquery-force \
     --per-asset-type

其中:

  • CONTENT_TYPE 是资产内容类型
  • PROJECT_ID 是要导出其元数据的项目的 ID。此项目可以是您从中运行导出的项目,也可以是其他项目。
  • SNAPSHOT_TIME(可选)是您希望截取资源快照的时间。值必须是当前时间或过去的时间。默认情况下,截取当前时间的快照。如需详细了解有效的时间格式,请参阅 gcloud topic datetimes
  • BIGQUERY_TABLE 是您要将元数据导出到其中的表,格式为 projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME
  • --output-bigquery-force 会覆盖目标表(如果存在)。
  • --per-asset-type 按资源类型导出到多个 BigQuery 表。

API

如需按资源类型导出项目中的资产,请运行以下命令。此命令会将导出的快照存储在零个表(如果快照结果为空)或多个 BigQuery 表中。每个表都包含一个资产类型的结果,并且 BIGQUERY_TABLE_(下划线)和资产类型名称串联。非字母数字字符将被替换为 _。如需了解详情,请参阅 exportAssets 方法。

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "separateTablesPerAssetType": true \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

如果导出到任何表失败,整个导出操作将会失败并返回第一个错误。但成功导出的结果将会保留。

在导出过程中设置的内容类型决定了每个表的架构。

  • 资源:如果将内容类型设置为 RESOURCE,每个表格的架构将包含映射到该资产类型的 Resource.data 字段中的嵌套字段的记录类型列,最多可为 BigQuery 支持的 15 个嵌套级别。请参阅 projects/export-assets-examples/datasets/structured_export 中的示例表的按类型 BigQuery 架构。

  • IAM 政策、组织政策、VPCSC 政策或未指定:如果将内容类型设置为 IAM_POLICYORG_POLICYACCESS_POLICY 或者不设置内容类型,每个表的架构与将 per-asset-type 设置为 False 时的架构相同。如需了解详情,请参阅设置内容类型部分中的架构。

以下类型会打包到 JSON 字符串中,以克服 JSON3BigQuery 类型之间的兼容性问题。

  • google.protobuf.Timestamp
  • google.protobuf.Duration
  • google.protobuf.FieldMask
  • google.protobuf.ListValue
  • google.protobuf.Value
  • google.protobuf.Struct
  • google.api.*

导出到分区表

如需按分区表中的给定时间戳导出资产快照,请完成以下步骤。

gcloud

如需将项目中的资产导出到分区表中,请运行以下命令。此命令将导出的快照存储在 BigQuery 表 BIGQUERY_TABLE 中,该表具有每天粒度和两个额外的时间戳列 readTimerequestTime,其中一列将是分区键(根据 partition-key 参数)。

  gcloud asset export \
     --content-type CONTENT_TYPE \
     --project 'PROJECT_ID' \
     --snapshot-time 'SNAPSHOT_TIME' \
     --bigquery-table 'BIGQUERY_TABLE' \
     --partition-key 'PARTITION_KEY' \
     --output-bigquery-force \

其中:

  • CONTENT_TYPE 是资产内容类型
  • PROJECT_ID 是其元数据被导出的项目的 ID。此项目可以是您从中运行导出的项目,也可以是其他项目。
  • SNAPSHOT_TIME(可选)是您希望截取资源快照的时间。值必须是当前时间或过去的时间。默认情况下,截取当前时间的快照。如需了解时间格式,请参阅 gcloud topic datetimes
  • BIGQUERY_TABLE 是您要将元数据导出到其中的表,格式为 projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_NAME
  • PARTITION_KEY 是导出到 BigQuery 分区表时的分区键列
  • --output-bigquery-force 会覆盖目标表(如果存在)。

API

如需将项目中的资产导出到分区表中,请运行以下命令。此命令将导出的快照存储在 BigQuery 表 BIGQUERY_TABLE 中,该表具有每天粒度和两个额外的时间戳列 readTimerequestTime,其中一列将是分区键(根据 partition-key 参数)。详细了解 exportAssets 方法。

gcurl -d '{"contentType":"CONTENT_TYPE", \
  "outputConfig":{ \
    "bigqueryDestination": { \
      "dataset": "projects/PROJECT_ID/datasets/DATASET_ID",\
      "table": "TABLE_NAME", \
      "force": true \
      "partitionSpec": {"partitionKey": "PARTITION_KEY"} \
    } \
  }}' \
  https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER:exportAssets

如果目标表已存在,则系统会通过附加额外的列来更新现有表的架构。如果任何列的类型或模式发生变化(例如从可选变为重复),架构更新将失败。然后,如果 output-bigquery-force 标志设置为 TRUE,则快照结果将覆盖相应的分区,但一个或多个不同分区中的数据将保持不变。如果 output-bigquery-force 未设置或为 FALSE,它会将数据附加到相应的分区。

如果架构更新或附加数据的尝试失败,导出操作将失败。

检查导出状态

如需检查导出状态,请运行以下命令。

gcloud

如需检查导出状态,您可以运行以下命令。运行导出命令后,它会显示在 gcloud 工具中。

gcloud asset operations describe OPERATION_ID

API

要查看导出的状态,请使用导出响应中返回的操作 ID 运行以下命令。

  1. 您可以在导出响应的 name 字段中找到 OPERATION_ID,其格式如下所示:

    "name": "projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID"
    
  2. 要检查导出状态,请使用 OPERATION_ID 运行以下命令:

    gcurl https://cloudasset.googleapis.com/v1/projects/PROJECT_NUMBER/operations/ExportAssets/CONTENT_TYPE/OPERATION_ID
    

查看资产快照

如需查看包含资源快照元数据的表,请完成以下步骤。

控制台

  1. 转到 Cloud Console 中的 BigQuery 页面。
    转到 BigQuery 页面

  2. 要显示数据集中的表和视图,请打开导航面板。在资源部分,选择项目以将其展开,然后选择数据集。

  3. 从列表中选择您的表。

  4. 选择详情并记下行数中的值。使用 gcloud 工具或 API 时,您可能需要此值来控制结果的起点。

  5. 要查看一组数据示例,请选择预览

API

如需浏览表的数据,请调用 tabledata.list。在 tableId 参数中,指定表的名称。

您可以配置以下可选参数来控制输出。

  • maxResults 是要返回的结果数上限。
  • selectedFields 是要返回的列的逗号分隔列表;如果未指定此参数,则会返回所有列。
  • startIndex 是要读取的起始行的索引(从零开始)。

返回的值会封装在一个 JSON 对象中,您必须对此对象进行解析,具体请参阅 tabledata.list 参考文档。

导出结果列出了资产及其资源名称

查询资源快照

将快照导出到 BigQuery 后,您便可以对资产元数据运行查询。 如需详细了解多种使用场景,请参阅导出到 BigQuery 示例查询

默认情况下,BigQuery 运行交互式(也称为按需)查询作业,也就是说,查询会尽快执行。交互式查询计入并发速率限制和每日限制

查询结果会保存到临时表或永久表中。您可以选择在现有表中附加或覆盖数据,或者创建新表(如果不存在同名的表)。

如需运行将输出写入临时表的交互式查询,请完成以下步骤。

控制台

  1. 转到 Cloud Console 中的 BigQuery 页面。
    转到 BigQuery 页面

  2. 选择 编写新查询

  3. 查询编辑器文本区域中,输入有效的 BigQuery SQL 查询。

  4. (可选)如需更改数据处理位置,请完成以下步骤。

    1. 选择更多,然后选择查询设置
    2. 处理位置下,选择自动选择,然后选择数据的位置
    3. 要更新查询设置,请选择保存
  5. 选择运行

API

  1. 要启动新作业,请调用 jobs.insert 方法。在作业资源中,设置以下参数。

    • configuration 字段中,将 query 字段设置为描述 BigQuery 查询作业的 JobConfigurationQuery

    • jobReference 字段中,为您的作业适当设置 location 字段。

  2. 要轮询结果,请调用 getQueryResults。直到 jobComplete 等于 true。您可以在 errors 列表中检查错误和警告。