发现和编目 Cloud Storage 数据

本文档介绍如何使用 Knowledge Catalog 自动发现功能，这是一项 Knowledge Catalog 功能，可让您扫描 Cloud Storage 存储分区中的数据，以提取元数据并将其编入目录。在发现扫描过程中，自动发现功能会为结构化数据创建 BigLake 表或外部表，并为非结构化数据创建对象表。借助 BigLake 表和外部表，您可以查询外部数据存储区中的结构化数据（请参阅 BigLake 表简介和外部表简介），而对象表则可提供 Cloud Storage 中非结构化数据的元数据索引（请参阅对象表简介）。这种集中式表格数据有助于利用 AI 获得数据洞见，并提升数据安全性和治理水平。

如需自动发现 Cloud Storage 数据，您可以创建并运行发现扫描。

自动发现也称为独立发现。

发现扫描概览

发现扫描会执行以下操作：

• 扫描 Cloud Storage 存储桶或路径中的数据。
• 将结构化数据和半结构化数据分组到表中。
• 收集元数据，例如表名称、架构和分区定义。
• 使用架构和分区定义在 BigQuery 中创建和更新 BigLake 外部、非 BigLake 外部或 BigLake 对象表。

结构化数据和半结构化数据

结构化和半结构化数据包括 Avro、Parquet 和 CSV 等格式。发现扫描会将这些文件组注册为 BigLake 外部表。仅当文件位于包含相同数据格式和兼容架构的文件夹中时，扫描才会检测到这些文件。

• 应用场景：将强类型结构化文件集中到 BigQuery 中，以便运行分析型 SQL 查询，而无需手动定义架构。
• 工作流程：
  1. 将结构化文件整理到文件夹中。确保每个文件夹中的文件具有相同的数据格式和兼容的架构。
  2. 创建发现扫描并提供您的 Google Cloud 资源连接 ID。
  3. 扫描会分组数据并将其注册为 BigLake 外部表。
  4. 使用 SQL 直接在 BigQuery 中查询已发布的表。

支持的格式

• Parquet
• Avro
• ORC
• JSON（仅限以换行符分隔的格式）
• CSV（但不包括包含注释行的 CSV 文件）

压缩格式

对于结构化和半结构化数据，发现扫描支持以下压缩格式：

• 以下格式的内部压缩：

  压缩	文件扩展名示例	支持的格式
  gzip	.gz.parquet	Parquet
  lz4	.lz4.parquet	Parquet
  Snappy	.snappy.parquet	Parquet、ORC、Avro
  lzo	.lzo.parquet	Parquet、ORC

• JSON 和 CSV 文件的外部压缩：

  • gzip
  • bzip2

非结构化数据

对于非结构化数据（例如图片和视频），发现扫描会检测并注册共享相同数据文件格式的文件组。文件必须位于包含相同文件格式的文件夹中。例如，gs://images/group1 必须仅包含 GIF 图片，而 gs://images/group2 必须仅包含 JPEG 图片，这样发现扫描才能检测并注册两个 BigLake 对象表。

• 使用情形：编目非结构化文件（例如图片或文档），以便使用 BigQuery ML 或远程函数执行机器学习推理。
• 工作流程：
  1. 将非结构化文件整理到文件夹中。确保每个文件夹中的文件采用相同的文件格式。
  2. 创建发现扫描。
  3. 扫描会分组非结构化数据，并将其注册为 BigLake 对象表。
  4. 直接在 BigQuery 中对非结构化文件执行推理。

支持的格式

发现扫描支持以下非结构化格式：

• 图片（例如 JPEG、PNG 和 BMP）
• 文档（例如 PDF、幻灯片演示文稿和文本报告）
• 音频或视频（例如 WAV、MP3 和 MP4）

如需了解详情，请参阅支持的对象文件。

压缩格式

对于对象表，压缩主要通过 Cloud Storage 对象元数据（而非 BigQuery 内部设置）进行管理。

• 标准元数据压缩：如果文件使用标准的 .gz 或 .bz2 扩展名，BigQuery 会自动识别使用 gzip 和 bzip2 压缩的文件。
• Content-Encoding：您可以使用 Cloud Storage 中的 Content-Encoding gzip 元数据来提供压缩文件，同时保留其原始内容类型。
• 媒体内部压缩：系统原生支持本身就经过压缩的格式（例如 JPEG [图片]、MP3 [音频]、MP4 [视频]）。

表格注册和可用性

发现的表会在 BigQuery 中注册为以下表类型之一，具体取决于数据格式和扫描配置：

• BigLake 对象表。专为非结构化数据（例如图片和视频）而设计。
• BigLake 外部表。在扫描配置期间提供 Google Cloud 资源连接 ID 时，为结构化和半结构化数据创建。
• 外部表（非 BigLake）：如果您不提供资源连接 ID，系统会为结构化和半结构化数据创建外部表。

注册后，您就可以在 BigQuery 中分析这些数据。还启用了 BigLake 表和对象表的元数据缓存。所有 BigLake 表都将自动提取到 Knowledge Catalog 中，以便进行搜索和发现。

如需开始使用新注册的表格，您可以执行以下操作：

• 在 BigQuery 中运行查询。
• 在 Knowledge Catalog 中搜索资源。

限制和配额

发现扫描不支持 Apache Iceberg 和 Delta Lake 表格式。

如需了解发现扫描支持的表数量上限，请参阅配额和限制。

准备工作

启用 Dataplex API。

启用 API 所需的角色

如需启用 API，您需要拥有 serviceusage.services.enable 权限。如果您创建了项目，则可能已经通过 Owner 角色 (roles/owner) 获得了此权限。否则，您可以通过 Service Usage Admin 角色 (roles/serviceusage.serviceUsageAdmin) 获得此权限。了解如何授予角色。

启用 API

注意： 下一部分中列出的角色适用于标准发现扫描。如果您想使用非结构化数据语义推理从文件中提取 AI 赋能的分析洞见，还必须应用使用非结构化数据分析洞见中列出的其他角色。

Knowledge Catalog 服务账号所需的角色

在开始之前，请向项目中的 Knowledge Catalog 服务账号分配 IAM 权限。

  [e-mail]
  

将 PROJECT_NUMBER 替换为已启用 Dataplex API 的项目。

如需确保知识目录服务账号拥有创建和运行发现扫描所需的权限，请让您的管理员为知识目录服务账号授予以下 IAM 角色：

重要提示：您必须向知识目录服务账号（而不是向您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。

• 针对存储桶的 Dataplex Discovery Service Agent (roles/dataplex.discoveryServiceAgent)
• 针对用户项目的 Dataplex Discovery Publishing Service Agent (roles/dataplex.discoveryPublishingServiceAgent)
• 创建 BigLake 表： 针对 BigQuery 连接的 Dataplex Discovery BigLake Publishing Service Agent (roles/dataplex.discoveryBigLakePublishingServiceAgent)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含创建和运行发现扫描所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和运行发现扫描，需要具备以下权限：

• 针对数据源项目的 bigquery.datasets.create
• 针对数据源存储桶的 storage.buckets.get
• 针对数据源存储桶的 storage.objects.get
• 针对数据源存储桶的 storage.objects.list
• 针对数据源项目的 bigquery.datasets.get
• 提供连接：
  • bigquery.connections.delegate 在 BigQuery 连接上
  • bigquery.connections.use 在 BigQuery 连接上

您的管理员也可以使用自定义角色或其他预定义角色为 Knowledge Catalog 服务账号授予这些权限。

BigQuery 连接服务账号所需的角色

如需确保 BigQuery Connection 服务账号拥有创建发现扫描所需的权限，请让您的管理员为 Cloud Storage 存储桶中的 BigQuery Connection 服务账号授予 Dataplex Discovery Service Agent (roles/dataplex.discoveryServiceAgent) IAM 角色。

重要提示：您必须向 BigQuery Connection 服务账号（而不是向您的用户账号）授予此角色。如果未能向正确的主账号授予此角色，可能会导致权限错误。

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含创建发现扫描所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建发现扫描，需要具备以下权限：

• 针对数据源项目的 bigquery.datasets.create
• 针对数据源存储桶的 storage.buckets.get
• 针对数据源存储桶的 storage.objects.get
• 针对数据源存储桶的 storage.objects.list
• 针对数据源项目的 bigquery.datasets.get
• 提供连接：
  • bigquery.connections.delegate 在 BigQuery 连接上
  • bigquery.connections.use 在 BigQuery 连接上

您的管理员也可以使用自定义角色或其他预定义角色为 BigQuery 连接服务账号授予这些权限。

最终用户所需的角色

如需获得创建和管理数据发现扫描所需的权限，请让您的管理员为您授予 Cloud Storage 存储桶的以下 IAM 角色：

• 对 DataScan 资源拥有完全访问权限： Dataplex DataScan Administrator (roles/dataplex.dataScanAdmin) - your project
• 对 DataScan 资源的写入权限： 针对项目的 Dataplex DataScan Editor (roles/dataplex.dataScanEditor)
• 对 DataScan 资源（不包括结果）的读取权限： 针对项目的 Dataplex DataScan Viewer (roles/dataplex.dataScanViewer)
• 对 DataScan 资源（包括结果）的读取访问权限： Dataplex DataScan DataViewer (roles/dataplex.dataScanDataViewer) - your project

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含创建和管理数据发现扫描所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建和管理数据发现扫描，需要具备以下权限：

• 创建 DataScan： 针对项目的 dataplex.datascans.create
• 删除 DataScan：针对项目或 DataScan 资源的 dataplex.datascans.delete
• 查看 DataScan 详细信息，不包括结果： 针对项目或 DataScan 资源的 dataplex.datascans.get
• 查看 DataScan 详细信息，包括结果： 针对项目或 DataScan 资源的 dataplex.datascans.getData
• 列出 DataScan： 针对项目或 DataScan 资源的 dataplex.datascans.list
• 运行 DataScan：针对项目或 DataScan 资源的 dataplex.datascans.run
• 更新 DataScan 的说明： 针对项目或 DataScan 资源的 dataplex.datascans.update
• 查看 DataScan 的 IAM 权限：针对项目或 DataScan 资源的 dataplex.datascans.getIamPolicy
• 为 DataScan 设置 IAM 权限：针对项目或 DataScan 资源的 dataplex.datascans.setIamPolicy

您也可以使用自定义角色或其他预定义角色来获取这些权限。

创建发现扫描

如需发现数据，您必须创建并运行发现扫描。您可以为扫描设置时间表，也可以按需运行扫描。

运行发现扫描时，系统会在 BigQuery 中创建一个与扫描的 Cloud Storage 存储桶对应的新数据集。BigQuery 数据集名称与 Cloud Storage 存储桶名称相同。存储桶名称中的无效字符会替换为下划线。如果数据集名称不可用，系统会附加后缀（例如 _discovered_001）。该数据集包含通过发现扫描创建的 BigLake 外部表或非 BigLake 外部表，以便进一步分析。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 点击创建。

3. 为扫描任务输入一个名称。

4. 在 ID 字段中，输入一个遵循 Google Cloud 中的资源命名规范的唯一 ID。如果您未提供 ID，则发现扫描会生成扫描 ID。

5. 可选：提供扫描的说明。

6. 如需指定包含要扫描的文件的 Cloud Storage 存储桶，请在存储桶字段中浏览并选择相应存储桶。

7. 可选：通过提供 用于文件过滤的 glob 模式列表，定义要从发现扫描中包含或排除的数据。

   • 包含：如果只应扫描部分数据，请提供与要包含的对象匹配的通配符模式列表。
   • 排除：提供与要排除的对象匹配的通配符模式列表。

   例如，如果您想从发现扫描中排除 gs://test_bucket/foo/..，请输入 **/foo/** 作为排除路径。引号会导致错误。请务必输入 **/foo/**，而不是 "**/foo/**"。

   如果您同时提供了包含模式和排除模式，系统会首先应用排除模式。

8. 对于非结构化数据选项，选择启用语义推理。

   如果您想在 Knowledge Catalog 中查看非结构化数据的分析洞见，则必须选择此选项。如需了解详情，请参阅非结构化数据分析简介。

9. 可选：在项目 ID 中，选择包含通过发现扫描创建的 BigLake 外部表或非 BigLake 外部表的 BigQuery 数据集项目。如果未提供，系统会在包含 Cloud Storage 存储桶的项目中创建数据集。

10. 在位置类型中，请选择在其中创建 BigQuery 发布数据集的区域或多区域（以哪个可用为准）。

11. 如需根据扫描的数据创建 BigLake 表，请在连接 ID 字段中提供您的 Google Cloud 资源连接 ID。如需了解详情，请参阅 BigQuery 中的Google Cloud 资源连接。

    您可以在与 BigQuery 数据集位置相同的位置创建新的连接 ID，该位置与 Cloud Storage 存储桶位置兼容。

    如果您不提供资源连接 ID，发现扫描会创建非 BigLake 外部表。如需了解这些外部表类型之间的区别以及发现服务可能会选择其中一种的原因，请参阅行为差异比较。

12. 在发现频率部分中，配置您希望发现扫描何时运行：

    • 重复：扫描按预定义的时间表运行。提供开始时间、运行扫描的天数以及频率（例如每小时）。

    • 按需：扫描按需运行。

13. 可选：在 JSON 或 CSV 规范部分中，指定扫描应如何处理 JSON 和 CSV 文件。点击 JSON 或 CSV 规范。

    1. 如需配置 JSON 选项，请选择启用 JSON 解析选项。
       • 停用类型推断：发现扫描是否应在扫描数据时推断数据类型。如果您为 JSON 数据停用类型推断，所有列都会注册为其原始类型，例如字符串、数字或布尔值。
       • 编码格式：数据的字符编码，例如 UTF-8、US-ASCII 或 ISO-8859-1。如果您未指定值，则系统会使用 UTF-8 作为默认值。
    2. 如需配置 CSV 选项，请选择启用 CSV 解析选项。
       • 停用类型推断：发现扫描是否应在扫描数据时推断数据类型。如果您为 CSV 数据停用类型推断，则所有列都会注册为字符串。
       • 标题行：标题行数，可以是 0 或 1。如果您指定值 0，发现扫描会推断标题并从文件中提取列名称。默认值为 0。
       • 列分隔符：用于分隔值的字符。提供单个字符 \r（回车）或 \n（换行）。默认为英文逗号 (,)。
       • 编码格式：数据的字符编码，例如 UTF-8、US-ASCII 或 ISO-8859-1。如果您未指定值，则系统会使用 UTF-8 作为默认值。

14. 点击创建（对于定期扫描）、立即运行（对于按需扫描）或创建并运行（对于一次性扫描）。

    • 定期扫描：系统会按照您设置的时间表运行定期扫描。
    • 按需扫描：在创建时会立即运行一次，您可以随时运行扫描。发现扫描可能需要几分钟才能完成。
    • 一次性扫描：自动执行。当发现扫描达到其定义的存留时间 (TTL) 阈值（用于确定发现扫描在执行后保持有效的时间）时，系统会自动将其删除。TTL 值可以介于 0 秒（立即删除）到 365 天之间。未指定 TTL 的发现扫描会在 24 小时后自动删除。

gcloud

如需创建发现扫描，请使用 gcloud dataplex datascans create data-discovery 命令。

gcloud dataplex datascans create data-discovery --location=LOCATION \
  --data-source-resource=BUCKET_PATH

替换以下内容：

• LOCATION：您要创建发现扫描的位置
• BUCKET_PATH：要扫描的存储桶的 Cloud Storage 路径

REST

如需创建发现扫描，请使用 dataScans.create 方法。

查询已发布的 BigLake 表

运行发现扫描后，BigLake 表会发布到 BigQuery 中的一个新数据集中。然后，您可以使用 SQL 在 BigQuery 中分析这些表。

您可以在 BigQuery 中查看或查询表。如需详细了解如何在 BigQuery 中运行查询，请参阅运行查询。

管理已发布的 BigLake 表

已发布的 BigLake 表由发现扫描在 BigQuery 中创建和管理。默认情况下，每次运行预定或按需扫描时，发现扫描都会处理新数据发现、架构推断和架构演变。为了表明元数据由扫描管理，扫描会发布标签 metadata-managed-mode 设置为 discovery-managed 的表。

如果您想自行管理架构和其他元数据（例如 CSV 或 JSON 选项），请将 metadata-managed-mode 标签设置为 user_managed。这样，在下次运行发现扫描时，架构将保持不变。如果发现扫描推断出的架构不正确或与给定表的预期架构不同，此方法会非常有用。当 metadata-managed-mode 标签设置为 user_managed 时，可以降低费用。

如需更新标签，您可以将标签键 metadata-managed-mode 的值修改为 user_managed，而不是 discovery-managed。在这种情况下，只要表附加了 user_managed 标签，发现扫描就不会更新表的架构。

注意：即使您的表由发现扫描管理，您也可以应用访问权限政策，例如列级安全性和行级安全性。

更新已发布的 BigLake 表

对于使用默认配置的发现扫描作业发布的 BigLake 表，架构和其他元数据会在每项发现扫描作业按预定频率运行时自动更新。

如需更新已发布的 BigLake 表，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

2. 更新一个或多个表格属性。

3. 在左侧窗格中，点击 探索器：

   

   如果您没有看到左侧窗格，请点击 展开左侧窗格以打开该窗格。

4. 在探索器窗格中，展开您的项目，点击数据集，然后选择一个数据集。

5. 点击概览 > 表，然后选择相应表。

6. 在详细信息标签页的标签部分，确保 metadata-managed-mode 标签已设置为 user_managed。如果设置为其他值，请按以下步骤操作：

   1. 点击 编辑详细信息。

   2. 在 metadata-managed-mode 键旁边的 value 字段中，输入 user_managed。

注意：更新架构的表可用于 SQL 查询和 Spark 查询。下次运行发现扫描时，表元数据保持不变。

删除已发布的 BigLake 表

如需删除已发布的 BigLake 表，请按以下步骤操作：

1. 在 Cloud Storage 存储桶中删除该表的数据文件。

2. 在 Google Cloud 控制台中，前往 BigQuery 页面。

   转到 BigQuery

3. 在左侧窗格中，点击 探索器：

   

4. 在探索器窗格中，展开您的项目，点击数据集，然后选择一个数据集。

5. 点击概览 > 表，然后选择相应表。

6. 在详细信息窗格中的标签部分，确保 metadata-managed-mode 标签未设置为 user_managed。如果已设置为 user_managed，请按以下步骤操作：

   1. 点击编辑详细信息 。

   2. 在 metadata-managed-mode 键旁边的 value 字段中，输入 discovery-managed。

      注意：如果元数据管理模式标签设置为 user_managed，则发现扫描不会替换表元数据，这会导致您的表不会被删除。

7. 点击运行。发现扫描是按需运行的。

运行发现扫描后，BigLake 表会在 BigQuery 中删除，并且无法通过 Spark 列出或查询。

按需运行发现扫描

如需按需运行发现扫描，请选择以下选项之一：

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 点击要运行的发现扫描。

3. 点击立即运行。

gcloud

如需运行发现扫描，请使用 gcloud dataplex datascans run 命令：

gcloud dataplex datascans run DATASCAN \
  --location=LOCATION

执行以下变量替换操作：

• LOCATION：在其中创建发现扫描的 Google Cloud 区域。
• DATASCAN：发现扫描的名称。

REST

如需按需运行发现扫描，请使用 Dataplex API 中的 dataScans.run 方法。

列出发现扫描

如需列出您的发现扫描，请选择以下选项之一。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 系统会列出在项目中创建的发现扫描。

gcloud

gcloud dataplex datascans list --location=LOCATION --project=PROJECT_ID

替换以下内容：

• LOCATION：项目的位置
• PROJECT_ID：您的 Google Cloud 项目 ID

REST

如需检索项目中的发现扫描列表，请使用 Dataplex API 中的 dataScans.list 方法。

查看发现扫描

如需查看发现扫描，请选择以下选项之一。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 点击要查看其详细信息的发现扫描。

   • 扫描详情部分显示有关发现扫描的详细信息。
   • 扫描状态部分显示最新扫描作业的发现结果。

gcloud

gcloud dataplex datascans jobs describe JOB \
  --location=LOCATION \
  --datascan=DATASCAN \
  --view=FULL

替换以下内容：

• JOB：发现扫描作业的 ID。
• LOCATION：在其中创建发现扫描的 Google Cloud 区域。
• DATASCAN：作业所属的发现扫描的名称。

REST

如需查看数据发现扫描的结果，请使用 Dataplex API 中的 dataScans.get 方法。

查看历史发现扫描结果

如需查看历史发现扫描结果，请选择以下选项之一。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 点击要查看其详细信息的发现扫描。

3. 点击扫描历史记录窗格。扫描历史记录窗格提供有关过往作业的信息，包括每个作业中扫描的记录数、每个作业的状态以及作业运行时间。

4. 如需查看有关作业的详细信息，请点击任务 ID 列中的相应作业。

gcloud

gcloud dataplex datascans jobs list \
  --location=LOCATION \
  --datascan=DATASCAN

替换以下内容：

• LOCATION：在其中创建发现扫描的 Google Cloud 区域。
• DATASCAN：作业所属的发现扫描的名称。

REST

如需查看发现扫描的所有作业，请使用 Dataplex API 中的 dataScans.jobs.list 方法。

更新发现扫描

如需更改发现扫描的时间表（例如，将时间表从按需更改为定期），请更新发现扫描。

注意： 一次性发现扫描不支持更新。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 对于要更新的发现扫描，请依次点击操作 > 修改。

3. 修改值。

4. 点击保存。

gcloud

如需更新发现扫描，请使用 gcloud dataplex datascans update data-discovery 命令。

gcloud dataplex datascans update data-discovery SCAN_ID --location=LOCATION --description=DESCRIPTION

替换以下内容：

• SCAN_ID：您要更新的发现扫描的 ID
• LOCATION：在其中创建发现扫描的 Google Cloud 区域
• DESCRIPTION：发现扫描的新说明

REST

如需更新发现扫描，请使用 Dataplex API 中的 dataScans.patch 方法。

删除发现扫描

如需删除发现扫描，请选择以下选项之一。

控制台

1. 在 Google Cloud 控制台中，前往 Cloud Storage 发现页面。

   前往 Cloud Storage 发现

2. 对于要删除的发现扫描，请依次点击操作 > 删除。

3. 点击删除。

gcloud

gcloud dataplex datascans delete SCAN_ID --location=LOCATION --async

替换以下内容：

• SCAN_ID：要删除的发现扫描的 ID
• LOCATION：在其中创建发现扫描的 Google Cloud 区域。

REST

如需删除发现扫描，请使用 Dataplex API 中的 dataScans.delete 方法。

后续步骤

• 了解如何在 Knowledge Catalog 中搜索资源。
• 了解非结构化数据分析。
• 了解如何针对非结构化数据使用发现扫描。
• 了解如何使用 Knowledge Catalog 客户端库。