本文档介绍了如何创建 BigQuery 订阅。 您可以使用 Google Cloud 控制台、Google Cloud CLI、客户端库 或使用 Pub/Sub API 创建 BigQuery 订阅。
准备工作
在阅读本文档之前,请确保您熟悉以下内容:
订阅的运作方式。
BigQuery 订阅的工作流。
如何配置 死信主题 以处理消息故障
除了熟悉 Pub/Sub 和 BigQuery 之外,您还需要确保在创建 BigQuery 订阅之前满足以下前提条件:
BigQuery 表已存在。或者,您可以创建一个 请按照下方说明创建 BigQuery 订阅, 请参阅本文档后面的部分。
Pub/Sub 主题的架构与 BigQuery 表。如果您添加不兼容的 您收到与兼容性相关的错误 消息。如需了解详情,请参阅 架构兼容性。
所需的角色和权限
以下是有关角色和权限的一系列指南:
如需创建订阅,您必须在项目中配置访问权限控制 。
如果您的 订阅和主题属于不同的项目,稍后讨论 部分。
要创建 BigQuery 订阅, Pub/Sub 服务账号必须具有写入 特定的 BigQuery 表如需详细了解如何 具体请参阅本文档的下一部分。
您可以在项目中配置 BigQuery 订阅 才能写入其他项目中的 BigQuery 表。
如需获得创建 BigQuery 订阅所需的权限,请让您的管理员为您授予项目的 Pub/Sub Editor (roles/pubsub.editor
) IAM 角色。
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
此预定义角色包含 创建 BigQuery 订阅所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
创建 BigQuery 订阅需要以下权限:
-
从订阅中拉取:
pubsub.subscriptions.consume
-
创建订阅:
pubsub.subscriptions.create
-
删除订阅:
pubsub.subscriptions.delete
-
获取订阅:
pubsub.subscriptions.get
-
列出订阅:
pubsub.subscriptions.list
-
更新订阅:
pubsub.subscriptions.update
-
将订阅附加到主题:
pubsub.topics.attachSubscription
-
获取订阅的 IAM 政策:
pubsub.subscriptions.getIamPolicy
-
为订阅配置 IAM 政策:
pubsub.subscriptions.setIamPolicy
如果您需要在一个项目中创建与另一个项目中的主题关联的 BigQuery 订阅,请让主题管理员为您授予该主题的 Pub/Sub Editor (roles/pubsub.editor)
IAM 角色。
为 Pub/Sub 服务账号分配 BigQuery 角色
某些 Google Cloud 服务具有由 Google Cloud 代管式服务账号,
服务访问您的资源。这些服务账号
称为服务代理Pub/Sub 会创建并维护
为每个项目创建服务账号,格式为
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
。
为了创建 BigQuery 订阅,Pub/Sub 服务账号必须拥有写入权限 并读取表元数据。
授予 BigQuery 数据编辑者 (roles/bigquery.dataEditor
)
授予 Pub/Sub 服务账号的权限。
在 Google Cloud 控制台中,转到 IAM 页面。
点击授予访问权限。
在添加主账号部分中,输入 Pub/Sub 的名称。 服务账号。服务账号的格式为
service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
。例如,对于具有project-number=112233445566
的项目,服务账号的格式为service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
。在分配角色部分中,点击添加其他角色。
在选择角色下拉菜单中,输入
BigQuery
。 然后选择 BigQuery Data Editor 角色。点击保存。
如需详细了解 BigQuery IAM 请参阅 BigQuery 角色和权限。
BigQuery 订阅属性
配置 BigQuery 订阅时,您可以指定以下内容 属性。
通用属性
了解常见的订阅属性 您可以为所有订阅设置此折扣
使用主题架构
此选项允许 Pub/Sub 使用架构 Pub/Sub 主题 已附加订阅。此外,Pub/Sub 将消息中的字段写入相应的 BigQuery 表中的列。
使用此选项时,请务必检查以下额外要求:
主题架构和 BigQuery 架构中的字段 必须具有相同的名称,并且其类型必须相互兼容。
主题架构中的任何选填字段也必须为 在 BigQuery 架构中是可选属性。
主题架构中的必填字段不必是 BigQuery 架构中必需的参数。
如果存在 BigQuery 字段不存在, 主题架构,这些 BigQuery 字段 必须采用
NULLABLE
模式。如果主题架构包含 BigQuery 架构中不存在的其他字段,并且可以舍弃这些字段,请选择舍弃未知字段选项。
您只能选择以下订阅属性之一:使用主题架构 或使用表架构。
如果您不选择使用主题架构或使用表架构选项,
确保 BigQuery 表有一个名为 data
的列,
类型 BYTES
、STRING
或 JSON
。Pub/Sub 会将消息写入到
此 BigQuery 列。
您可能看不到 Pub/Sub 主题架构更改或 BigQuery 表架构会在消息中立即生效 写入 BigQuery 表。例如,如果拖放 未知字段选项,且 Pub/Sub 架构(而非 BigQuery 架构) 写入 BigQuery 表的消息可能仍然不包含 该字段添加到 BigQuery 架构中。最终, 架构同步,后续消息包含 字段。
对 BigQuery 使用使用主题架构选项时 还可以利用 BigQuery 变更 数据捕获 (CDC)。CDC 通过以下方式更新 BigQuery 表: 处理更改并将其应用到现有行。
如需详细了解此功能,请参阅使用变更数据捕获流式传输表更新。
如需了解如何将此功能与 BigQuery 订阅搭配使用, 请参阅 BigQuery 变更数据捕获。
使用表架构
通过此选项,Pub/Sub 可以使用 用于写入 JSON 字段的 BigQuery 表 消息发送到相应的列。使用此选项时,请注意 请查看以下额外要求:
已发布的消息必须采用 JSON 格式。
支持以下 JSON 转换:
JSON 类型 BigQuery 数据类型 string
NUMERIC
、BIGNUMERIC
、DATE
、TIME
、DATETIME
或TIMESTAMP
number
NUMERIC
、BIGNUMERIC
、DATE
、TIME
、DATETIME
或TIMESTAMP
- 使用
number
进行DATE
、DATETIME
、TIME
或TIMESTAMP
转换时,数值必须符合支持的表示法。 - 使用
number
到NUMERIC
或BIGNUMERIC
的转换时,值的精度和范围受限于浮点运算的 IEEE 754 标准。如果您需要高精确度或范围更广泛的值,请改用string
到NUMERIC
或BIGNUMERIC
转换。 - 使用
string
进行NUMERIC
或BIGNUMERIC
转换时,Pub/Sub 会假定字符串是人类可读的数字(例如"123.124"
)。如果将字符串作为人类可读的数字处理失败,则 Pub/Sub 会将字符串视为使用 BigDecimalByteStringEncoder 编码的字节。
- 使用
如果订阅的主题 具有关联的架构 消息编码属性必须设置为
JSON
。如果存在 BigQuery 字段不存在, 消息,这些 BigQuery 字段必须采用
NULLABLE
模式。如果邮件中包含 可以删除 BigQuery 架构和这些字段,请选择 选项丢弃未知字段。
您只能选择以下订阅属性之一:使用主题架构 或使用表架构。
如果您不选择使用主题架构或使用表架构选项,
确保 BigQuery 表有一个名为 data
的列,
类型 BYTES
、STRING
或 JSON
。Pub/Sub 会将消息写入到
此 BigQuery 列。
您可能不会看到 BigQuery 表架构的更改 将消息写入 BigQuery 表后立即生效。 例如,如果启用了删除未知字段选项,但有一个字段 存在于消息中,但不存在于 BigQuery 架构中, 写入 BigQuery 表的消息可能仍然不包含 该字段添加到 BigQuery 架构中。最终, 架构同步,后续消息中会包含该字段。
针对 BigQuery 订阅使用使用表架构选项时,您需要 还可以利用 BigQuery 变更数据捕获 (CDC)。 CDC 通过处理更改并将其应用于现有表来更新 BigQuery 表 行。
如需详细了解此功能,请参阅使用变更数据捕获流式传输表更新。
如需了解如何将此功能与 BigQuery 订阅搭配使用,请参阅 BigQuery 变更数据捕获。
删除未知字段
此选项与使用主题架构或使用表架构搭配使用 选项。此选项可让 Pub/Sub 删除主题中存在的任何字段 但不包含在 BigQuery 架构中。不含未知丢弃 字段设置,则包含额外字段的消息不会被写入到 BigQuery 并保留在订阅积压消息中。通过 订阅将处于错误状态。
写入元数据
此选项可让 Pub/Sub 将每条消息的元数据写入 BigQuery 表。否则,元数据 不会写入 BigQuery 表。
如果您选择写入元数据选项,请确保 BigQuery 表包含下表中所述的字段。
如果您不选择写入元数据选项,则目标 BigQuery 表仅需要 data
字段,除非
use_topic_schema
为 true。如果您同时选择了 Write metadata 和
使用主题架构选项,则主题的架构必须
不包含任何名称与元数据参数匹配的字段。
此限制包括这些蛇形命名参数的驼峰命名版本。
参数 | |
---|---|
subscription_name |
STRING 订阅的名称。 |
message_id |
STRING 消息的 ID |
publish_time |
TIMESTAMP 发布消息的时间。 |
data |
BYTES、STRING 或 JSON 消息正文。 所有目标平台都必须填写 |
attributes |
STRING 或 JSON 包含所有消息属性的 JSON 对象。它还 包含属于 包含排序键的 Pub/Sub 消息。 (如果存在)。 |
创建 BigQuery 订阅
以下示例演示了如何创建使用 BigQuery 传送功能的订阅。
控制台
- 在 Google Cloud 控制台中,前往 订阅页面。
- 点击创建订阅。
- 对于订阅 ID 字段,输入名称。
对于 请参阅命名准则 主题或订阅。
- 从下拉菜单中选择或创建一个主题。订阅 从主题接收消息。
- 将传送类型选为写入 BigQuery。
- 为 BigQuery 表选择项目。
- 选择现有数据集或创建新数据集。
相关信息 如需了解如何创建数据集,请参阅创建数据集。
- 选择现有表或创建一个新表。
如需了解 如何创建表,请参阅创建表。
- 我们强烈建议您启用 Dead
字母以处理消息故障。
有关详情,请参阅终止 字母主题。
- 点击创建。
您还可以从主题页面创建订阅。 此快捷方式可帮助您将主题与订阅关联。
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
如需创建 Pub/Sub 订阅,请使用
gcloud pubsub subscriptions create
命令:gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --bigquery-table=PROJECT_ID:DATASET_ID.TABLE_ID
替换以下内容:
- SUBSCRIPTION_ID:指定 订阅。
- TOPIC_ID:指定主题的 ID。通过 主题需要架构。
- PROJECT_ID:指定项目的 ID。
- DATASET_ID:指定现有 ID 数据集。要创建数据集,请参阅 创建 数据集。
- TABLE_ID:指定现有表的 ID。 如果您的主题,则此表需要 data 字段 没有架构如需创建表,请参阅创建 具有架构定义的空表。
C++
在尝试此示例之前,请按照C++ Pub/Sub 快速入门: 客户端库。 有关详情,请参阅 Pub/Sub C++ API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
C#
在尝试此示例之前,请按照C# Pub/Sub 快速入门: 客户端库。 有关详情,请参阅 Pub/Sub C# API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Go
在尝试此示例之前,请按照Go Pub/Sub 快速入门: 客户端库。 有关详情,请参阅 Pub/Sub Go API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Java
在尝试此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Java 设置说明进行操作。 有关详情,请参阅 Pub/Sub Java API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Node.js
Node.js
PHP
在尝试此示例之前,请按照PHP Pub/Sub 快速入门: 客户端库。 有关详情,请参阅 Pub/Sub PHP API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Python
在尝试此示例之前,请按照Python Pub/Sub 快速入门: 客户端库。 有关详情,请参阅 Pub/Sub Python API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Ruby
在尝试此示例之前,请按照Ruby Pub/Sub 快速入门: 客户端库。 有关详情,请参阅 Pub/Sub Ruby API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
监控 BigQuery 订阅
Cloud Monitoring 提供多种指标 监控订阅。
获取与 Pub/Sub 相关的所有可用指标的列表 及其说明,请参阅 Pub/Sub 的监控文档。
您还可以在 Pub/Sub 中监控订阅。
后续步骤
- 使用
gcloud
命令创建或修改订阅。 - 使用 REST API 创建或修改订阅。
- 排查 BigQuery 订阅问题。