创建对象表

本文档介绍了如何通过创建对象表，使 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',
  uris = ['gs://bucket1/*','gs://bucket2/folder1/*','gs://bucket3/*']
);

以下示例仅会对 Cloud Storage 存储桶中的 PDF 对象创建对象表：

CREATE EXTERNAL TABLE `my_dataset.object_table`
WITH CONNECTION `us.my-connection`
OPTIONS(
  object_metadata = 'SIMPLE',
  uris = ['gs://bucket1/*.pdf']
);

bq

使用 bq mk 命令。

bq mk --table \
--external_table_definition=BUCKET_PATH@REGION.CONNECTION_ID \
--object_metadata=SIMPLE \
--max_staleness=STALENESS_INTERVAL \
--metadata_cache_mode=CACHE_MODE \
PROJECT_ID:DATASET_ID.TABLE_NAME

请替换以下内容：

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。
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。这是默认设置。

如需启用元数据缓存，请使用 INTERVAL 数据类型文档中所述的 Y-M D H:M:S 格式指定 30 分钟到 7 天之间的间隔时间值。例如，指定 0-0 0 4:0:0 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会从 Cloud Storage 检索元数据。
CACHE_MODE：指定元数据缓存是自动刷新还是手动刷新。如需详细了解元数据缓存注意事项，请参阅启用元数据缓存以提高性能。
如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。

如果 STALENESS_INTERVAL 设置为大于 0 的值，您必须设置 CACHE_MODE。

示例

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

bq mk --table \
--external_table_definition=gs://mybucket/*@us.my-connection \
--object_metadata=SIMPLE \
--max_staleness=0-0 1 0:0:0 \
--metadata_cache_mode=AUTOMATIC \
my_dataset.object_table

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

bq mk --table \
--external_table_definition=gs://bucket1/*,gs://bucket2/folder1/*,gs://bucket3/*@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

以下示例仅会对 Cloud Storage 存储桶中的 PDF 对象创建对象表：

bq mk --table \
--external_table_definition=gs://bucket1/*.pdf@us.my-connection \
--object_metadata=SIMPLE \
my_dataset.object_table

API

调用 tables.insert 方法。添加 ExternalDataConfiguration 对象，并在传入的 Table 资源中将 objectMetadata 字段设置为 SIMPLE。

以下示例展示了如何使用 curl 调用此方法：

ACCESS_TOKEN=$(gcloud auth print-access-token) curl \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST \
-d '{"tableReference": {"projectId": "my_project", "datasetId": "my_dataset", "tableId": "object_table_name"}, "externalDataConfiguration": {"objectMetadata": "SIMPLE", "sourceUris": ["gs://mybucket/*"]}}' \
https://www.googleapis.com/bigquery/v2/projects/my_project/datasets/my_dataset/tables

Terraform

本示例创建一个启用了手动刷新元数据缓存的对象表。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

为对象表指定的关键字段是 google_bigquery_table.external_data_configuration.object_metadata、google_bigquery_table.external_data_configuration.metadata_cache_mode 和 google_bigquery_table.max_staleness。如需详细了解每种资源，请参阅 Terraform BigQuery 文档。


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection-id".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection-id"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.project_id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This defines a Google BigQuery dataset.
resource "google_bigquery_dataset" "default" {
  dataset_id = "my_dataset_id"
}

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "bucket_name_suffix" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.bucket_name_suffix.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This defines a BigQuery object table with manual metadata caching.
resource "google_bigquery_table" "default" {
  deletion_protection = false
  table_id            = "my-table-id"
  dataset_id          = google_bigquery_dataset.default.dataset_id
  external_data_configuration {
    connection_id = google_bigquery_connection.default.name
    autodetect    = false
    # `object_metadata is` required for object tables. For more information, see
    # https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/bigquery_table#object_metadata
    object_metadata = "SIMPLE"
    # This defines the source for the prior object table.
    source_uris = [
      "gs://${google_storage_bucket.default.name}/*",
    ]

    metadata_cache_mode = "MANUAL"
  }

  # This ensures that the connection can access the bucket
  # before Terraform creates a table.
  depends_on = [
    google_project_iam_member.default
  ]
}

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

启动 Cloud Shell。
设置要应用 Terraform 配置的默认 Google Cloud 项目。

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

将示例代码复制到新创建的 main.tf 中。

（可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。
查看和修改要应用到您的环境的示例参数。
保存更改。
初始化 Terraform。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

查询对象表

您可以像查询任何其他 BigQuery 表一样查询对象表，例如：

SELECT *
FROM mydataset.myobjecttable;

查询对象表会返回底层对象的元数据。如需了解详情，请参阅对象表架构。

后续步骤

了解如何对图片对象表运行推理。
了解如何使用远程函数分析对象表。