本文档介绍了如何设置将 Pub/Sub Lite 消息自动导出到 Pub/Sub 的设置。
以下是您可能使用此功能的一些场景:
- 在混合使用 Pub/Sub Lite 和 Pub/Sub 的工作负载之间进行互操作。
- 将 Pub/Sub Lite 工作负载迁移到 Pub/Sub。
- 通过基于 Pub/Sub Lite 的现有应用使用高级 Pub/Sub 功能,例如推送订阅和过滤。
- 整合多个数据流水线。
概览
如需将消息从 Pub/Sub Lite 导出到 Pub/Sub,您需要创建一个特殊类型的订阅,称为“导出订阅”。导出订阅会从精简版主题接收消息,将其转换为 Pub/Sub 消息,然后将转换后的消息发送到目标 Pub/Sub 主题。
精简版主题可以同时包含导出订阅和标准订阅。在配额用量和预留吞吐量方面,这两种订阅类型相同。导出订阅会消耗精简版订阅吞吐量容量,并根据 Pub/Sub 发布吞吐量收费。
导出订阅会将精简版主题关联到一个 Pub/Sub 主题。但是,精简版主题可以具有多个连接到不同 Pub/Sub 主题的导出订阅(扇出架构)。您还可以从多个精简版主题导出到同一个 Pub/Sub 主题(扇入架构)。
身份验证
导出订阅会访问 Pub/Sub Lite 和 Pub/Sub 资源。如需创建导出订阅,您需要以下权限:
pubsublite.subscriptions.create
。以下预定义角色包含此权限:roles/pubsublite.admin
roles/pubsublite.editor
请参阅 Pub/Sub Lite 的访问权限控制。
pubsub.topics.get
。以下预定义角色可提供此权限:roles/pubsub.admin
roles/pubsub.editor
roles/pubsub.viewer
请参阅 Pub/Sub 的访问权限控制。
服务代理
导出订阅会代表您发布到 Pub/Sub 主题。为此,它使用服务代理。
在项目中创建第一个导出订阅后,系统会自动创建 Pub/Sub Lite 服务代理。如果您在同一项目中创建其他导出订阅,这些订阅将使用同一服务代理。服务代理采用以下命名方案:service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com
。
创建服务代理时,该服务代理有权发布到导出订阅所在项目中的所有 Pub/Sub 和 Pub/Sub Lite 主题。如果目标 Pub/Sub 主题与导出订阅位于不同的项目中,则必须通过添加 Pub/Sub Publisher 角色 (roles/pubsub.publisher
) 来向服务代理授予额外的权限。您可以为整个项目或单个主题授予权限。我们建议遵循最小权限原则,在主题级别授予权限。
如需了解详情,请参阅通过 Google Cloud 控制台控制访问权限。您还可以使用 gcloud projects add-iam-policy-binding
命令添加 IAM 角色:
gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \ --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com --role=roles/pubsub.publisher
请替换以下内容:
- TOPIC_NAME:要添加 IAM 政策绑定的目标 Pub/Sub 主题的名称。
- PROJECT_NUMBER:Pub/Sub Lite 导出订阅所属项目的项目编号。
创建导出订阅
您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Pub/Sub Lite API 创建精简版导出订阅。
精简版导出订阅必须与其关联到的精简版主题位于同一项目和位置中。如需创建精简版主题,请参阅创建和管理精简版主题。
如果您将导出订阅附加到精简版主题,请确保发布到精简版主题的所有消息都与 Pub/Sub 兼容。如需了解详情,请参阅消息兼容性。
创建导出订阅后,您便无法将其更改为标准订阅,反之亦然。
控制台
gcloud
如需创建导出订阅,请使用 gcloud pubsub lite-subscriptions create
命令:
gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \ --location=LOCATION \ --topic=TOPIC_ID \ --export-pubsub-topic=PUBSUB_TOPIC_NAME \ --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \ --export-desired-state=DESIRED_STATE
请替换以下内容:
- SUBSCRIPTION_ID:要创建的精简版订阅的 ID。
- LOCATION:精简版订阅的位置。
- TOPIC_ID:要附加到精简版订阅的精简版主题的 ID。
- PUBSUB_TOPIC_NAME:作为导出目标的 Pub/Sub 主题的名称。如果主题位于其他项目中,请指定全名:
projects/my-project-id/topics/my-topic-id
。 - DEAD_LETTER_TOPIC_ID:可选。用作死信主题的精简版主题的 ID。死信主题必须与导出订阅位于同一位置(可用区或区域)和同一项目中。
- DESIRED_STATE:可选。订阅的起始状态。
支持以下值:
active
:订阅会将精简版消息导出到 Pub/Sub。(默认)。paused
:精简版消息的导出已暂停。
如果请求成功,命令行会显示一条确认消息:
Created [SUBSCRIPTION_ID].
协议
如需创建精简版导出订阅,请发送如下所示的 POST
请求:
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
请替换以下内容:
- REGION:用于存储精简版订阅的区域。
- PROJECT_NUMBER:要在其中创建精简版订阅的项目的编号。
- LOCATION:Pub/Sub Lite 支持的位置的名称。
- SUBSCRIPTION_ID:精简版订阅的 ID。
在请求正文中指定以下字段:
{ "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } } }
请替换以下内容:
- DELIVERY_REQUIREMENT:传送要求,为
DELIVER_AFTER_STORED
或DELIVER_IMMEDIATELY
。 - DESIRED_STATE:订阅的起始状态。支持以下值:
ACTIVE
:订阅会将精简版消息导出到 Pub/Sub。PAUSED
:精简版消息的导出已暂停。
- DEAD_LETTER_TOPIC_ID:要用作死信主题的现有精简版主题的 ID。主题必须与导出订阅本身位于同一位置(可用区或区域)和同一项目中。
- PUBSUB_TOPIC_NAME:作为导出目标的 Pub/Sub 主题的名称。示例格式:
projects/my-project-id/topics/my-topic-id
。
如果请求成功,则响应是 JSON 格式的精简版订阅:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }, "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", }
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在运行此示例之前,请按照 Pub/Sub Lite 客户端库中的 Java 设置说明进行操作。
Python
在运行此示例之前,请按照 Pub/Sub Lite 客户端库中的 Python 设置说明进行操作。
更新导出订阅
您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Pub/Sub Lite API 更新精简版订阅。新设置最长可能需要 30 秒才能应用。
控制台
前往精简版订阅页面。
点击精简版订阅 ID。
在精简版订阅详情页面中,点击修改。
gCloud
要更新精简版订阅,请使用 gcloud pubsub lite-subscriptions update
命令:
gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \ --location=LOCATION \ --delivery-requirement=DELIVERY_REQUIREMENT \ --export-pubsub-topic=PUBSUB_TOPIC_NAME \ --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \ --export-desired-state=DESIRED_STATE
请替换以下内容:
- SUBSCRIPTION_ID:精简版订阅的 ID
- LOCATION:精简版订阅的位置。
- DELIVERY_REQUIREMENT:可选。传送要求,为
deliver-after-stored
或deliver-immediately
。 - PUBSUB_TOPIC_NAME:可选。要导出到的 Pub/Sub 主题的名称。如果主题位于其他项目中,请指定全名:
projects/my-project-id/topics/my-topic-id
。 - DEAD_LETTER_TOPIC_ID:要用作死信主题的现有精简版主题的 ID。主题必须与导出订阅本身位于同一位置(可用区或区域)和同一项目中。
- DESIRED_STATE:可选。期望的订阅状态。
支持以下值:
active
:订阅会将精简版消息导出到 Pub/Sub。(默认)。paused
:精简版消息的导出已暂停。
如果请求成功,命令行将显示精简版订阅:
Updated subscription [SUBSCRIPTION_ID]. deliveryConfig: deliveryRequirement: DELIVERY_REQUIREMENT exportConfig: currentState: DESIRED_STATE deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID desiredState: DESIRED_STATE pubsubConfig: topic: PUBSUB_TOPIC_NAME name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID
协议
要更新精简版订阅,请发送 PATCH
请求,如下所示:
PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig Authorization: Bearer $(gcloud auth print-access-token)
请替换以下内容:
- REGION:创建精简版订阅的区域。
- PROJECT_NUMBER:创建精简版订阅的项目的编号。
- LOCATION:精简版订阅的创建位置。
- SUBSCRIPTION_ID:精简版订阅的 ID。
在请求正文中指定以下字段:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } } }
请替换以下内容:
- DELIVERY_REQUIREMENT:传送要求,为
DELIVER_AFTER_STORED
或DELIVER_IMMEDIATELY
。 - DESIRED_STATE:所需的订阅状态。支持以下值:
ACTIVE
:订阅会将精简版消息导出到 Pub/Sub。PAUSED
:精简版消息的导出已暂停。
- DEAD_LETTER_TOPIC_ID:要用作死信主题的现有精简版主题的 ID。主题必须与导出订阅本身位于同一位置(可用区或区域)和同一项目中。
- PUBSUB_TOPIC_NAME:目标 Pub/Sub 主题的名称。示例格式:
projects/my-project-id/topics/my-topic-id
。
如果请求成功,则响应是 JSON 格式的精简版订阅:
{ "deliveryConfig": { "deliveryRequirement": "DELIVERY_REQUIREMENT", }, "exportConfig": { "desiredState": "DESIRED_STATE", "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID", "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" } }, "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID", "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID", }
暂停或启动导出订阅
导出订阅具有一项名为“所需状态”的设置,该设置具有以下两个值之一:
- 活跃:该订阅会将精简版消息导出到 Pub/Sub。
- 已暂停:精简版消息的导出已暂停。
如需在 Google Cloud 控制台中更改期望的状态,请执行以下操作:
前往精简版订阅页面。
点击精简版订阅 ID。
在精简版订阅详情页面中,点击暂停或开始。
您还可以使用 Google Cloud CLI 或 Pub/Sub Lite API 更新期望状态。请参阅更新导出订阅。
最佳实践
本部分介绍了使用导出订阅时的一些最佳实践。
预留
我们建议将导出订阅与预留搭配使用,而不是明确设置订阅的吞吐量容量。
消息兼容性
如果 Pub/Sub Lite 消息与 Pub/Sub 不兼容,则导出订阅不会将该消息发布到 Pub/Sub。相反,它会将消息放入死信主题(如果已分配死信主题)。如果未分配死信主题,则不兼容的消息会被丢弃。
将消息发布到精简版主题时,请注意以下兼容性问题:
键。Pub/Sub 精简版键的类型为
bytes
,而 Pub/Sub 排序键的类型为string
。为了兼容,Pub/Sub 精简版密钥只能包含 UTF-8 字符。属性。消息属性具有以下要求:
- 为了兼容,所有 Pub/Sub Lite 消息属性都必须具有单个值。Pub/Sub Lite 支持具有多个值的消息属性,但 Pub/Sub 仅支持单值属性。
- 消息特性不得超过 Pub/Sub 消息限制,包括每条消息的特性数上限,以及每个特性的键和值大小上限。
死信主题
如需保留和处理不兼容的消息,我们建议您使用死信主题。您可以在创建导出订阅时分配死信主题,也可以更新现有导出订阅以使用死信主题。如果订阅收到与 Pub/Sub 不兼容的消息,则会将该消息发布到死信主题。
死信主题是常规的 Pub/Sub 精简版主题。它必须与导出订阅位于同一位置和项目中,并且必须与源主题不同。
通常,死信主题的吞吐量利用率较低。因此,我们建议为死信主题分配预留,而不是为主题分配吞吐量。
递送错误
导出订阅会尝试将所有兼容的消息都传送到目标 Pub/Sub 主题。如果消息传送失败,则导出订阅会暂停。如需查找错误类别,请查看 subscription/export_status
指标。以下值表示存在错误:
PERMISSION_DENIED
:权限不足,无法导出消息。NOT_FOUND
:未找到一个或多个资源;例如,目标主题不存在。
如需详细了解如何排查问题,请参阅排查导出订阅问题。
解决错误后,导出订阅会因定期重试而自动重启。
价格
您需要为导出订阅使用的 Pub/Sub Lite 和 Pub/Sub 资源付费。具体而言,您需要为为 Pub/Sub Lite 主题配置的 Pub/Sub Lite 订阅分配订阅吞吐量和存储空间付费。您还需要为发布到目标 Pub/Sub 主题付费。请参阅 Pub/Sub 价格。
使用导出功能不会产生额外费用,并且 Pub/Sub Lite 导出订阅和标准订阅之间没有价格差异。
排查导出订阅问题
本部分介绍了导出订阅的一些问题排查提示。
导出订阅已暂停
如果订阅暂停,系统不会导出任何消息。
要检测此问题,请执行以下操作:
Google Cloud 控制台:查看订阅详情。如果订阅已暂停,预期状态和当前状态将为
Paused
。指标:“
subscription/export_status
”指标为PAUSED
。
如需解决此问题,请开始订阅。
已删除目标主题或死信主题
如果删除附加到导出订阅的 Pub/Sub 主题,或者删除死信主题,则会发生错误。
要检测此问题,请执行以下操作:
Google Cloud 控制台:查看订阅详情。如果主题已删除,则当前状态为
Not found
。指标:
subscription/export_status
指标。如果主题已删除,则值为NOT_FOUND
。
如需解决此问题,请检查目标 Pub/Sub 主题和死信主题(如果已配置)。
如果目标位置 Pub/Sub 已被删除,请使用相同的名称重新创建主题。导出订阅将继续发布(假设权限未更改)。
如果死信主题已被删除,请创建新的死信主题,并更新导出订阅以引用该主题。
不兼容的消息
如果消息与 Pub/Sub 不兼容,则不会被导出。
要检测此问题,请执行以下操作:
- 指标:
subscription/unexportable_message_count
指标显示无法导出的不兼容消息的数量。
如需解决此问题,请使用死信主题来保留不兼容的消息。请检查消息以确定原因,然后根据需要转换和重新发布消息。请参阅消息兼容性。
导出受限
要检测此问题,请执行以下操作:
- 指标:
subscription/flow_control_status
指标显示了流控制原因NO_CLIENT_TOKENS
,这表示已达到每个分区的未完成字节数或消息数量上限。在问题得到解决之前,相关导出订阅的积压量会增加。
此错误有几个可能的根本原因。大多数可能的原因都发生在后端,但请检查以下情况:
- 请确保以低于每个密钥 1 MiB/秒的速率发布共享同一密钥的精简版消息。导出订阅将精简版消息键写入为 Pub/Sub 排序键,Pub/Sub 对每个排序键有 1 MiB/秒的限制。超过此限制可能会导致节流。
用户无权执行此操作
Pub/Sub Lite 服务代理必须具有发布到目标 Pub/Sub 主题的权限。
要检测此问题,请执行以下操作:
Google Cloud 控制台:查看订阅详情。如果存在权限错误,则当前状态为
Permission denied
。指标:“
subscription/export_status
”指标为PERMISSON_DENIED
。
例如,以下情况可能会导致此错误:
- Pub/Sub Lite 服务代理缺少正确的权限或角色,无法将消息发布到其他项目中的目标 Pub/Sub 主题。
- 服务代理已从导出订阅父项目的 IAM 政策中移除。
- Pub/Sub Lite 服务代理仍在设置中。当您在项目中创建第一个导出订阅时,系统会自动创建服务代理。权限错误应该会在 10 分钟内自动解决。
如需解决此问题,请检查是否向服务代理授予了正确的权限或角色。请参阅服务代理。