排查 BigQuery 订阅问题

本页面介绍了关于 BigQuery 订阅的一些常见问题排查提示。

检查 BigQuery 订阅的状态

如需检查订阅的状态，请执行以下步骤：

  1. 在 Google Cloud 控制台中，转到 Pub/Sub 订阅页面。

    前往订阅页面

  2. 检查 BigQuery 订阅的状态图标。

    如果图标是一个绿色对勾标记，则表示订阅健康状况良好。

    如果该图标是红色感叹号，则表示订阅处于错误状态。

  3. 点击 BigQuery 订阅。

    系统会打开订阅详情页面。

  4. 查看订阅状态以查看错误消息。

  5. 根据错误消息，转到本页面中的相关部分排查问题。

问题解决后，订阅最终会恢复为正常运行状态。

无法创建或更新订阅

以下是创建或更新 BigQuery 订阅时可能会遇到的一些常见问题。

“未找到表”错误

如果您在创建或更新订阅工作流中指定的表不存在，则工作流会返回“未找到表”错误。在 Google Cloud 控制台中，该消息类似于以下内容：

The BigQuery table or dataset specified cannot be found.

如需解决此问题，请创建表，并确保在将其与 BigQuery 订阅搭配使用之前，可以查看其state。

架构不匹配错误

如果表的架构和主题不兼容，则创建或更新订阅工作流会返回架构不匹配错误。在 Google Cloud 控制台中，该消息类似于以下内容：

Incompatible schema type for field project_ids: expected INT64, got STRING

指定的错误消息是因为名为 project_ids 的字段的架构不匹配。您可能会看到错误消息的不同变体，具体取决于架构不匹配的类型。

如需解决此问题，请检查架构映射是否兼容。

服务账号错误

如果您尚未为 Pub/Sub 服务帐号配置适当的权限，则创建或更新订阅工作流会返回错误。在 Google Cloud 控制台中，该消息类似于以下内容：

Service account service-1234234234@gcp-sa-pubsub.iam.gserviceaccount.com
is missing permissions required to write to the BigQuery table:
bigquery.tables.get, bigquery.tables.updateData.

如需解决此问题，请检查服务帐号是否具有正确的权限。

订阅状态显示红色感叹号

如果您在创建订阅后修改该表，则可能会影响 Pub/Sub 向表中写入消息的方式。如果某项更改导致出现问题，相应订阅的状态字段会设置为错误状态。

在订阅详情页面中，检查 Subscription state 字段的状态。Subscription state 字段提供更具体的错误，可能是以下某种错误：

  • 找不到表：表已删除。创建一个表并检查该表的状态。 请参阅获取表信息。

  • 表权限被拒绝：Pub/Sub 服务帐号不再具有表的写入权限。检查服务帐号是否具有正确的权限。

  • 表架构不匹配：表架构不再与 BigQuery 订阅设置兼容。请检查架构映射是否兼容。

当 Pub/Sub 订阅处于错误状态时，消息不会写入 BigQuery 表，并且会保留在订阅积压消息中。请注意，如果配置了死信主题，消息将不会递送到附加的死信主题。未确认的消息会保留 message_retention_duration 中设置的时间段（默认为 7 天）。

积压输入量正在增加

如果您发现订阅中积压消息，或者有消息发送到订阅的死信主题，请查看以下可能的原因。

INVALID_ARGUMENT 错误消息

如果所提供的消息采用 Pub/Sub 认为有效的格式，但 BigQuery 目标表架构无效，就会发生此错误。 这意味着消息中的一个或多个字段具有 BigQuery 表架构不允许使用的值。查看架构兼容性以验证数据类型和格式是否正确。最常见的错误包括：

  • 空字符串 ("") 不是有效的 JSON。将数据发送到可为 null 的 JSON BigQuery 表列时，请提供空的 JSON 对象 ({})、null 或空的 JSON 字符串 ("\"\"") 来表示缺失值。发送空字符串会导致错误。

  • 如果消息字段值超过 BigQuery 字段的长度上限，则消息会因大小限制而失败。

如需排查 INVALID_ARGUMENT 错误，请向相关订阅添加死信主题。死信主题会捕获无法写入 BigQuery 的消息，以及一个名为 CloudPubSubDeadLetterSourceDeliveryErrorMessage 的属性（用于说明失败原因）。

这些传送失败的情况还可在 Metrics Explorer 中看到。选择指标 pubsub.googleapis.com/subscription/push_request_count 并按 response_code=invalid_argument 进行过滤。

RESOURCE_EXHAUSTED 错误消息

如果消息写入 BigQuery 的速度缓慢，您可能需要增加项目的 Pub/Sub 推送配额或 BigQuery 存储写入吞吐量配额。如需检查是否遇到了配额限制，请检查推送请求指标 (subscription/push_request_count) 中是否存在任何 resource_exhausted 错误。

诊断配额问题的另一种方法是查看项目的配额。在包含 Pub/Sub 资源或 BigQuery 实例的项目中，转到 IAM 和管理 > 配额。搜索相关配额（pubsub.googleapis.com/regionalpushsubscriber 或 bigquerystorage.googleapis.com/write/append_bytes）。如果其中任一配额需要增加，您可以申请更高配额。

每小时分区表，在分区 ID 列中显示“__UNPARTITIONED__”

当 BigQuery 目标表按小时分区时，行最初位于 INFORMATION_SCHEMA.PARTITIONS 视图中标记为 __UNPARTITIONED__ 的特殊分区中。对于使用提取时间分区的表，这符合预期。

BigQuery 采用流式缓冲区来优化写入过程。 数据可能会保留在 __UNPARTITIONED__ 分区中，直到累积到足够的数据或至少过了一小时为止。满足这些条件后，BigQuery 会将数据重新分区到相应的每小时分区中。

您可以使用 INFORMATION_SCHEMA.PARTITIONS 视图监控 __UNPARTITIONED__ 分区中的数据。

后续步骤

  • 如果您的 BigQuery 订阅仍有问题，请参阅获取支持。