创建对象表

本文档介绍了如何通过创建对象表，使 Cloud Storage 中的非结构化数据可在 BigQuery 中进行访问。

如需创建对象表，您必须完成以下任务：

创建包含对象表的数据集。
创建连接以从 Cloud Storage 读取对象信息。
向与连接关联的服务账号授予 Storage Object Viewer (roles/storage.objectViewer) 角色。
使用 CREATE EXTERNAL TABLE 语句创建对象表并将其与连接相关联。

准备工作

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigQuery and BigQuery Connection API APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

所需的角色

如需创建对象表，您必须拥有项目的以下角色：

如需创建数据集和表，您必须拥有 BigQuery Data Editor (roles/bigquery.dataEditor) 角色。
如需创建连接，您必须拥有 BigQuery Connection Admin (roles/bigquery.connectionAdmin) 角色。
如需为连接的服务账号授予角色，您必须拥有 Project IAM Admin (roles/resourcemanager.projectIamAdmin) 角色。

如需查询对象表，您必须拥有项目的以下角色：

BigQuery Data Viewer (roles/bigquery.dataViewer) 角色
BigQuery Connection User (roles/bigquery.connectionUser) 角色

如需查看所需的确切权限，请展开所需权限部分：

所需权限

bigquery.datasets.create
bigquery.tables.create
bigquery.tables.update
bigquery.connections.create
bigquery.connections.get
bigquery.connections.list
bigquery.connections.update
bigquery.connections.use
bigquery.connections.delete
bigquery.connections.delegate
storage.bucket.*
storage.object.*
bigquery.jobs.create
bigquery.tables.get
bigquery.tables.getData
bigquery.readsessions.create

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

创建数据集

创建包含对象表的 BigQuery 数据集：

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

转到 BigQuery
在左侧窗格中，点击 探索器：

如果您没有看到左侧窗格，请点击 展开左侧窗格以打开该窗格。
在探索器窗格中，点击您的项目名称。
点击 查看操作 > 创建数据集。
在 创建数据集 页面上，执行以下操作：
1. 在数据集 ID 中，输入数据集的名称。
2. 在位置类型部分，选择区域或多区域。
  - 如果您选择了区域，请从区域列表中选择一个位置。
  - 如果您选择了多区域，请从多区域列表中选择美国或欧洲。
3. 点击创建数据集。

创建连接

如果您已配置默认连接，或者您具有 BigQuery Admin 角色，则可以跳过此步骤。

创建一个 Cloud 资源连接供对象表使用，并获取连接的服务账号。

转到 BigQuery 页面。

转到 BigQuery
在左侧窗格中，点击 探索器：
在浏览器窗格中，点击 添加数据。

系统随即会打开添加数据对话框。
在过滤条件窗格中的数据源类型部分，选择企业应用。

或者，在搜索数据源字段中，您可以输入 Vertex AI。
在精选数据源部分中，点击 Vertex AI。
点击 Vertex AI 模型：BigQuery 联合解决方案卡片。
在连接类型列表中，选择 Vertex AI 远程模型、远程函数、BigLake 和 Spanner（Cloud 资源）。
在连接 ID 字段中，为连接输入一个名称。
在位置类型部分，选择区域或多区域。
- 如果您选择了区域，请从区域列表中选择一个位置。
- 如果您选择了多区域，请从多区域列表中选择美国或欧洲。
点击创建连接。
点击转到连接。
在连接信息窗格中，复制服务账号 ID 以在后续步骤中使用。

向服务账号授予访问权限

向连接的服务账号授予 Storage Object Viewer 角色：

控制台

前往 IAM 和管理页面。

转到“IAM 和管理”
点击 Add。

系统随即会打开添加主账号对话框。
在新的主账号字段中，输入您之前复制的服务账号 ID。
在选择角色字段中，选择 Cloud Storage，然后选择 Storage Object Viewer。
点击保存。

gcloud

使用 gcloud projects add-iam-policy-binding 命令。

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

请替换以下内容：

PROJECT_NUMBER：要在其中授予角色的项目的编号。
MEMBER：您之前复制的服务账号 ID。

创建对象表

如需创建对象表，请执行以下操作：

SQL

使用 CREATE EXTERNAL TABLE 语句。

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

转到 BigQuery
在查询编辑器中，输入以下语句：
```
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET_ID.TABLE_NAME`
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID`| DEFAULT}
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['BUCKET_PATH'[,...]],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE');
```
请替换以下内容：
- PROJECT_ID：您的项目 ID。
- DATASET_ID：要包含对象表的数据集的 ID。
- TABLE_NAME：对象表的名称。
- REGION：包含连接的单区域或多区域。
- CONNECTION_ID：要与对象表搭配使用的 Cloud 资源连接的 ID。该连接会确定用于从 Cloud Storage 读取数据的服务账号。
  当您在 Google Cloud 控制台中查看连接详情时，连接 ID 是连接 ID 中显示的完全限定连接 ID 的最后一部分的值，例如 projects/myproject/locations/connection_location/connections/myconnection。
  
  如需使用默认连接，请指定 DEFAULT，而不是包含 PROJECT_ID.REGION.CONNECTION_ID 的连接字符串。
- BUCKET_PATH：包含对象表所表示的对象的 Cloud Storage 存储桶的路径，格式为 ['gs://bucket_name/[folder_name/]*']。
  您可以在每个路径中使用一个星号 (*) 通配符来限制对象表中包含的文件。例如，如果存储桶包含多种类型的非结构化数据，您可以通过指定 ['gs://bucket_name/*.pdf'] 仅对 PDF 对象创建对象表。如需了解详情，请参阅 Cloud Storage URI 的通配符支持。
  
  您可以通过提供多个路径为 uris 选项指定多个存储桶，例如 ['gs://mybucket1/*', 'gs://mybucket2/folder5/*']。
  
  如需详细了解如何在 BigQuery 中使用 Cloud Storage URI，请参阅 Cloud Storage 资源路径。
- STALENESS_INTERVAL：指定对对象表执行的操作是否使用了缓存的元数据，以及操作使用的缓存元数据的新鲜度。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
  如需停用元数据缓存，请指定 0。这是默认设置。
  
  如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会从 Cloud Storage 检索元数据。
- CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
  如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。
  
  如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。
  
  如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。
点击运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

示例

以下示例会创建一个元数据缓存过时间隔时间为 1 天的对象表：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://mybucket/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

以下示例会对三个 Cloud Storage 存储桶中的对象创建一个对象表：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',