订阅者可能会由于各种原因而无法处理消息。例如,检索处理消息所需的数据时可能会出现暂时性问题。或者,消息可能采用了订阅者不希望的格式。
本页面介绍了如何使用订阅重试政策或将未传送的消息转发到死信主题(也称为“死信队列”)来处理此类处理失败。
请注意,Dataflow 不支持这些功能。如需了解详情,请参阅 Dataflow 文档的不支持的 Pub/Sub 功能部分。
订阅重试政策
如果 Pub/Sub 尝试传送消息,但订阅者不能确认,则 Pub/Sub 会自动尝试重新发送消息。这种重新提交尝试称为订阅重试政策。您无法开启或关闭此功能。不过,您可以选择要使用的重试政策类型。
首次创建和配置订阅时,您可以选择使用以下重试政策之一,即立即重新传送或指数退避算法。默认情况下,订阅使用立即重新提交。
立即重新提交
默认情况下,Pub/Sub 会尝试立即(并且有可能)向同一订阅者客户端重新发送该消息。但是,如果阻止消息确认的条件没有更改,立即重新传送可能会导致出现问题。 在这种情况下,Pub/Sub 可能会重新发送多条无法确认的消息。
为了解决即时重新传送问题,Pub/Sub 允许您配置指数退避算法政策。
指数退避算法
利用指数退避算法,您可以在重试尝试之间逐渐添加较长的延迟时间。首次传送失败后,Pub/Sub 会等待最短退避时间,然后再重试。对于每个连续的消息失败,都会增加更多延迟,最长延迟为 0 秒和 600 秒。
最大和最小延迟间隔不固定,应根据应用的本地因素进行配置。
请注意关于指数退避算法的以下注意事项:
- 指数退避算法会在以下操作时触发:
- 收到否定确认时。
- 消息的确认截止期限到期时。
- 指数退避算法仅应用于每条消息,而不会应用于订阅中的所有消息(全局)。
- 使用指数退避算法时,即使之前的消息收到了负面确认,Pub/Sub 仍会继续传送其他消息(除非您使用有序消息传送)。
配置指数退避算法
控制台
创建新订阅时,您可以执行以下步骤来配置指数退避算法重试政策:
gcloud
如需使用指数退避算法重试政策创建新订阅,请使用下面显示的标志运行 gcloud pubsub create
命令:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --min-retry-delay=MIN_RETRY_DELAY \ --max-retry-delay=MAX_RETRY_DELAY
死信主题
如果 Pub/Sub 服务尝试传送消息,但订阅者无法确认,则 Pub/Sub 可以将无法传送的消息转发到死信主题。
死信主题如何与 Pub/Sub 配合使用
死信主题是订阅属性,而不是主题属性。这意味着,您可以在创建订阅(而不是创建主题)时设置死信主题。
如果您创建了死信主题,则可以设置以下订阅属性:
传送尝试次数上限:表示 Pub/Sub 针对特定消息进行的传送尝试次数的数值。如果订阅者客户端无法在配置的传送尝试次数内确认消息,则该消息将被转发到死信主题。
- 默认值 = 5
- 最大值 = 100
- 最小值 = 5
包含死信主题的项目:如果死信主题与订阅属于不同的项目,则您必须指定包含死信主题的项目。将死信主题设置为与订阅所附加的主题不同的主题。
如何计算传送尝试次数上限
仅当死信主题正确配置且包含正确的 IAM 权限时,Pub/Sub 才会统计传送尝试次数。
传送尝试次数上限是近似值,因为 Pub/Sub 会尽最大努力转发无法传送的消息。
跟踪的消息传送尝试次数也可能会重置为零,尤其是对于订阅者处于非活跃状态的拉取订阅。因此,消息传送至订阅者客户端的次数可能会超过配置的传送尝试次数上限。
配置死信主题
如需配置死信主题,源主题必须先具有订阅。您可以在创建订阅时指定死信主题,也可以更新现有订阅以使用死信主题。
以下是为订阅启用死信的工作流。
创建死信主题。此主题与源主题是相互独立的。
为源主题订阅设置死信主题。
为避免丢失死信主题中的消息,请至少将另一个订阅附加到死信主题。次要订阅会从死信主题接收消息。
向 Pub/Sub 服务帐号授予发布者和订阅者角色。如需了解详情,请参阅授予转发权限。
为新订阅设置死信主题
您可以使用 Google Cloud 控制台、Google Cloud CLI、客户端库或 Pub/Sub API 创建订阅并设置死信主题。
控制台
如需创建订阅并设置死信主题,请完成以下步骤:
在 Google Cloud 控制台中,进入订阅页面。
点击创建订阅。
输入订阅 ID。
从下拉菜单中选择或创建一个主题。
订阅将接收来自该主题的消息。
在死信部分,选择启用死信。
从下拉菜单中选择或创建死信主题。
如果所选的死信主题没有订阅,系统会提示您创建订阅。
在传送尝试次数上限字段中,指定一个 5 到 100 之间的整数。
点击创建。
详细信息面板会显示可能的操作项列表。如果有任何项显示错误图标
,请点击操作项以解决问题。
gcloud
如需创建订阅并设置死信主题,请使用 gcloud pubsub subscriptions create
命令:
gcloud pubsub subscriptions create subscription-id \ --topic=topic-id \ --dead-letter-topic=dead-letter-topic-name \ [--max-delivery-attempts=max-delivery-attempts] \ [--dead-letter-topic-project=dead-letter-topic-project]
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
Ruby
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
为现有订阅设置死信主题
您可以使用 Google Cloud 控制台、Google Cloud CLI、客户端库或 Pub/Sub API 更新订阅并设置死信主题。
控制台
如需更新订阅并设置死信主题,请完成以下步骤。
在 Google Cloud 控制台中,进入订阅页面。
在要更新的订阅旁边,点击更多操作more_vert。
在上下文菜单中,选择编辑。
在死信部分,选择启用死信。
从下拉菜单中选择或创建一个主题。
如果所选主题没有订阅,系统会提示您创建订阅。
在传送尝试次数上限字段中,指定一个 5 到 100 之间的整数。
点击更新。
详细信息面板会显示可能的操作项列表。如果有任何项显示错误图标
,请点击操作项以解决问题。
gcloud
如需更新订阅并设置死信主题,请使用 gcloud pubsub subscriptions update
命令:
gcloud pubsub subscriptions update subscription-id \ --dead-letter-topic=dead-letter-topic-name \ [--max-delivery-attempts=max-delivery-attempts] \ [--dead-letter-topic-project=dead-letter-topic-project]
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
Ruby
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
授予 IAM 角色以使用死信主题
如需将无法传送的消息转发到死信主题,Pub/Sub 必须具有执行以下操作的权限:
- 将消息发布到主题。
- 确认消息,此操作会将消息从订阅中移除。
Pub/Sub 会为每个项目创建并维护一个服务账号:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com
。您可以通过为此服务帐号分配发布者和订阅者角色来授予转发权限。
控制台
如需授予 Pub/Sub 将消息发布到死信主题的权限,请完成以下步骤:
在 Google Cloud 控制台中,进入订阅页面。
点击包含死信主题的订阅的名称。
点击死信标签页。
如需分配发布商角色,请点击授予发布商角色。如果成功分配发布者角色,您会看到蓝色的对勾标记
。如需分配订阅者角色,请点击授予订阅者角色。如果成功分配发布者角色,您会看到蓝色的对勾标记
。
gcloud
如需授予 Pub/Sub 将消息发布到死信主题的权限,请运行以下命令:
PUBSUB_SERVICE_ACCOUNT="service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com" gcloud pubsub topics add-iam-policy-binding dead-letter-topic-name \ --member="serviceAccount:$PUBSUB_SERVICE_ACCOUNT"\ --role="roles/pubsub.publisher"
如需授予 Pub/Sub 确认转发的无法传送的消息的权限,请运行以下命令:
PUBSUB_SERVICE_ACCOUNT="service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com" gcloud pubsub subscriptions add-iam-policy-binding subscription-id \ --member="serviceAccount:$PUBSUB_SERVICE_ACCOUNT"\ --role="roles/pubsub.subscriber"
跟踪递送尝试
为订阅启用死信主题后,来自该订阅的每条消息都有一个指定传送尝试次数的字段:
从拉取订阅接收的消息包含
delivery_attempt
字段。从推送订阅接收的消息包含
deliveryAttempt
字段。
以下示例展示了如何获取传送尝试次数:
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 C# 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C# API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Go
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Go 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Go API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Java
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Java 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Java API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Node.js
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
PHP
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Python
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Python 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Python API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
Ruby
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
当 Pub/Sub 将无法送达的消息转发到死信主题时,它会为消息添加以下属性:
CloudPubSubDeadLetterSourceDeliveryCount
:向源订阅传送消息的次数。CloudPubSubDeadLetterSourceSubscription
:源订阅的名称。CloudPubSubDeadLetterSourceSubscriptionProject
:包含源订阅的项目的名称。CloudPubSubDeadLetterSourceTopicPublishTime
:最初发布消息时的时间戳。CloudPubSubDeadLetterSourceDeliveryErrorMessage
:消息无法传送到原始目的地的原因。该属性仅适用于导出订阅。
监控转发的邮件
转发无法送达的消息后,Pub/Sub 服务会从订阅中移除消息。您可以使用 Cloud Monitoring 监控转发的消息。
如果您将订阅附加到死信主题,则这些消息会使用附加订阅的到期政策,而非具有死信主题属性的订阅的有效期。
subscription/dead_letter_message_count
指标用于记录 Pub/Sub 从订阅转发的无法传送的消息数量。
如需了解详情,请参阅监控转发的无法传送的消息。
移除死信主题
如需停止转发无法传送的消息,请从订阅中移除死信主题。
您可以使用 Google Cloud 控制台、Google Cloud CLI 或 Pub/Sub API 从订阅中移除死信主题。
控制台
如需从订阅中移除死信主题,请完成以下步骤:
在 Google Cloud 控制台中,进入订阅页面。
在订阅列表中,点击订阅旁边的 more_vert 进行更新。
从上下文菜单中选择修改。
在死信部分,清除启用死信。
点击更新。
gcloud
如需从订阅中移除死信主题,请使用 gcloud pubsub subscriptions update
命令和 --clear-dead-letter-policy
标志:
gcloud pubsub subscriptions update subscription-id \ --clear-dead-letter-policy
C++
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C++ 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C++ API 参考文档。
C#
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 C# 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub C# API 参考文档。
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Java 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Java API 参考文档。
Node.js
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Node.js API 参考文档。
PHP
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
Python
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Python 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Python API 参考文档。
Ruby
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Ruby 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
Ruby
试用此示例之前,请按照 Pub/Sub 快速入门:使用客户端库中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
要向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为本地开发环境设置身份验证。
价格
Pub/Sub 服务转发无法传送的消息时,您需要支付以下费用:
- 向与包含死信主题的项目相关联的结算账号计入的发布费用。
- 向与具有死信主题属性的订阅所属项目相关联的结算帐号收取的出站消息的订阅费用。
如果您设置了订阅的死信主题属性,但死信主题主题的消息存储位置政策不允许包含订阅的区域,则还需要支付出站消息的费用。
出站消息的发布费用将计入包含死信主题的项目。如需了解详情,请参阅价格。