本页面介绍如何为精简版订阅启动和跟踪还原操作。
Pub/Sub 精简版还原功能允许您重放和完全清除消息。它具有与 Pub/Sub 还原功能相同的用例。 与 Pub/Sub 不同,您无需将精简版主题或订阅配置为使用还原功能,并且无需支付额外费用。
您可以使用长时间运行的操作跟踪还原功能传播给订阅者的情况。这是 Google Cloud 产品用来跟踪长时间运行的任务进度的 API 模式。
启动还原功能
Pub/Sub 精简版还原操作在带外(即通过 Google Cloud CLI 或单独的 Pub/Sub Lite API)启动并传播到订阅者。在线订阅者将在上线时收到还原通知并做出回应。离线订阅者会在处于在线状态后响应还原。
您必须为还原指定目标位置,该位置可以是下列位置的其中一个:
- 消息积压开始:重放所有保留的消息。请注意,可用积压量由精简版主题的消息保留期限和存储容量决定。
- 消息结束积压:通过跳过当前发布的所有消息来完全清除消息。
- 发布时间戳:还原至(服务器生成的)发布时间戳晚于或等于指定时间戳的第一个消息。如果找不到此消息,则还原至消息积压的结尾。可保证后续消息的发布时间戳晚于或等于指定时间戳,但指定时间戳是将来时间的情况除外。
- 事件时间戳:还原到(用户指定的)事件时间戳晚于或等于指定时间戳的第一个消息。如果找不到此消息,则还原至消息积压的结尾。由于事件时间戳由用户提供,因此后续消息的事件时间戳可能早于指定的事件时间,并且应由客户端根据需要过滤。如果消息未设置事件时间戳,则其发布时间戳将用作后备。
您可以使用 Google Cloud CLI 或 Pub/Sub Lite API 发起精简版订阅还原。
gcloud
如需还原精简版订阅,请使用 gcloud pubsub lite-subscriptions seek
命令:
gcloud pubsub lite-subscriptions seek SUBSCRIPTION_ID \ --location=LITE_LOCATION \ (--publish-time=PUBLISH_TIME | --event-time=EVENT_TIME | \ --starting-offset=STARTING_OFFSET) \ [--async]
替换以下内容:
SUBSCRIPTION_ID:精简版订阅的 ID
LITE_LOCATION:精简版订阅的位置
PUBLISH_TIME:要还原到的发布时间戳
EVENT_TIME:要还原到的事件时间戳
STARTING_OFFSET:
beginning
或end
如需了解时间格式,请参阅 gcloud topic datetimes
。
如果您指定了 --async
标志且请求成功,命令行将显示还原操作的 ID:
Check operation [projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID] for status.
使用 gcloud pubsub lite-operations describe
命令获取操作状态。
REST
要还原精简版订阅,请发送 POST
请求,如下所示:
POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID:seek Authorization: Bearer $(gcloud auth print-access-token)
替换以下内容:
REGION:精简版订阅所在的区域
PROJECT_NUMBER:具有精简版订阅的项目的项目编号
LITE_LOCATION:精简版订阅的位置
SUBSCRIPTION_ID:精简版订阅的 ID
要还原到消息积压项的开头或结尾,请在请求正文中设置以下字段:
{ "namedTarget": NAMED_TARGET }
替换以下内容:
- NAMED_TARGET:消息积压的
TAIL
(开始)或HEAD
(结束)。
如需还原到发布时间戳,请在请求正文中设置以下字段:
{ "timeTarget": { "publishTime": TIMESTAMP } }
指定 "eventTime"
可还原至事件时间戳。
替换以下内容:
- TIMESTAMP:采用 RFC 3339 世界协调时间 (UTC) 格式的时间戳,精度为纳秒,最多保留九位小数。示例:
"2014-10-02T15:01:23Z"
和"2014-10-02T15:01:23.045123456Z"
。
如果请求成功,则响应是采用 JSON 格式的长时间运行的操作:
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
Go
在尝试此示例之前,请按照《快速入门:使用客户端库》中的 Go 设置说明进行操作。 如需了解详情,请参阅 Pub/Sub Go API 参考文档。
Java
在运行此示例之前,请按照 Pub/Sub Lite 客户端库中的 Java 设置说明进行操作。
Python
在运行此示例之前,请按照 Pub/Sub Lite 客户端库中的 Python 设置说明进行操作。
如果还原请求成功,则响应为长时间运行的操作 ID。如果您需要了解订阅者何时对还原做出反应,请参阅有关跟踪还原传播的信息(见下文)。
支持的客户端
还原操作要求使用以下 Pub/Sub Lite 客户端库和最低版本的订阅者:
- java-pubsublite:版本 0.15.0。
- java-pubsublite-kafka:版本 0.6.0。使用方还必须启用自动提交。
- python-pubsublite:版本 0.6.0。
- google-cloud-go:pubsublite 版本 0.10.0。
将 Pub/Sub Lite 与 Apache Beam 或 Apache Spark 搭配使用时,还原操作不起作用,因为这些系统会自行跟踪分区内偏移。解决方法是排空、还原和重启工作流。
Pub/Sub 精简版服务能够检测不支持还原操作(例如旧客户端库版本或不受支持的框架)的订阅者客户端,并通过 FAILED_PRECONDITION
错误状态取消还原操作。
跟踪还原传播
如果为初始还原请求返回长时间运行的操作 ID,则表示还原已成功在 Pub/Sub 精简版服务中注册,并且最终将传播到订阅者(如果客户端支持,则如上所述)。该操作会跟踪此传播,并在订阅者响应所有分区的还原后完成。
如果订阅者在线,则他们最多可能需要 30 秒才能收到还原通知。还原通知会针对每个分区单独发送,因此分区可能不会在同一时刻对还原操作做出反应。如果订阅者离线,则还原操作会在订阅者在线后完成。
如果之前的还原调用尚未完成传播到订阅者,则此调用会中止并被新的还原操作取代。还原操作元数据在 30 天后过期,这实际上会中止任何未完成的还原操作。
还原操作状态
您可以使用 Google Cloud CLI 或 Pub/Sub Lite API 获取还原操作的状态。
gcloud
要获取有关精简版操作的详细信息,请使用 gcloud pubsub lite-operations describe
命令:
gcloud pubsub lite-operations describe OPERATION_ID \ --location=LITE_LOCATION
替换以下内容:
OPERATION_ID:精简版操作的 ID
LITE_LOCATION:精简版操作的位置
如果请求成功,命令行会显示有关精简版操作的元数据:
metadata: '@type': type.googleapis.com/google.cloud.pubsublite.v1.OperationMetadata createTime: '2021-01-02T03:04:05Z' target: projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID verb: seek name: projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID
REST
如需获取有关精简版操作的详细信息,请发送 GET
请求,如下所示:
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID Authorization: Bearer $(gcloud auth print-access-token)
替换以下内容:
REGION:精简版操作所在的区域
PROJECT_NUMBER:具有精简版操作的项目的项目编号
LITE_LOCATION:精简版操作的位置
OPERATION_ID:精简版操作的 ID
如果请求成功,则响应是采用 JSON 格式的长时间运行的操作:
{ "name": projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID, ... }
列出还原操作
可以使用 Google Cloud CLI 或 Pub/Sub Lite API 列出已完成和活跃的还原操作。
gcloud
如需列出项目中的精简版操作,请使用 gcloud pubsub lite-operations list
命令:
gcloud pubsub lite-operations list \
--location=LITE_LOCATION \
[--subscription=SUBSCRIPTION] \
[--done=DONE] \
[--limit=LIMIT]
替换以下内容:
LITE_LOCATION:精简版操作所在的位置
SUBSCRIPTION:按精简版订阅过滤操作
DONE:
true
以仅包含完成的操作,false
以仅包含活跃的操作LIMIT:此标志值为一个整数,用于限制返回的操作数
如果请求成功,命令行会显示精简版操作的摘要:
OPERATION_ID TARGET CREATE_TIME DONE ERROR_CODE MESSAGE operation2 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-05-06T07:08:00Z True operation1 projects/PROJECT_NUMBER/locations/LITE_LOCATION/subscriptions/SUBSCRIPTION_ID 2021-01-02T03:04:00Z True
REST
如需列出项目中的精简版操作,请发送 GET
请求,如下所示:
GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations Authorization: Bearer $(gcloud auth print-access-token)
替换以下内容:
REGION:精简版操作所在的区域
PROJECT_NUMBER:具有精简版操作的项目的项目编号
LITE_LOCATION:精简版操作所在的位置
如果请求成功,则响应是以 JSON 格式列出的精简版操作列表:
{ "operations": [ { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... }, { "name": "projects/PROJECT_NUMBER/locations/LITE_LOCATION/operations/OPERATION_ID", ... } ] }