某些 Google Cloud API 方法需要很长时间才能完成。这些方法不会阻塞,直到工作完成,而是会返回一个表示正在进行的操作的 Operation 资源,以便您的应用可以轮询其状态和最终结果。
Rust 版 Cloud 客户端库提供了用于处理这些长时间运行的操作 (LRO) 的辅助程序。本文档介绍了如何启动 LRO、自动轮询直至完成、检查中间进度更新以及手动轮询。
准备工作
本文档使用 Cloud Storage 来使代码示例具体化,但相同的概念适用于使用 LRO 的任何 Google Cloud 服务。
在运行本文档中的代码之前,请先完成以下前提条件:
- 创建或选择一个已启用结算功能的 Google Cloud 项目。
- 按照 Rust 使用入门中的说明设置开发环境和凭据。
- 创建一个启用了分层命名空间的 Cloud Storage 存储桶,并创建一个要重命名的源文件夹。
- 向您的主账号授予具有管理文件夹权限的 Identity and Access Management (IAM) 角色,例如 Storage Admin (
roles/storage.admin)。
依赖项
将客户端库和 LRO crate 添加到 Cargo.toml 文件中:
cargo add google-cloud-storage google-cloud-lro google-cloud-longrunning anyhow
添加 tokio 以实现异步执行和计时器:
cargo add tokio --features full
启动长时间运行的操作
本文档中的示例调用了 Cloud Storage 重命名文件夹操作,该操作会返回 LRO。如需直接启动 LRO 并获取初始 Operation 资源,请完成以下步骤:
添加
use声明以缩短类型路径:定义一个接受存储桶 ID、源文件夹 ID 和目标文件夹 ID 的
async函数:初始化
StorageControl客户端:创建
rename_folder请求构建器:发送请求并等待初始
Operation资源,该资源表示后台操作:
启动操作后,请等待其完成,以检索其最终结果。
自动轮询长时间运行的操作
对于大多数用例,请使用 Poller 特征的 until_done 方法,而不是直接调用 send。轮询器启动 LRO,根据客户端的退避和错误政策进行轮询,并解析为最终响应:
将
Poller特征引入作用域:初始化
StorageControl客户端并配置rename_folder请求构建器:对请求构建器调用
poller和until_done,以等待完成并输出结果:
完成自动轮询代码
以下函数展示了完整的自动轮询示例:
轮询具有中间结果的长时间运行的操作
until_done 方法仅返回最终结果,并省略中间元数据更新。如果您的应用在 LRO 运行时需要进度更新,请使用 poller 获取轮询器,并在循环中调用 poll:
导入
Poller和PollingResult:使用
poller将请求构建器转换为轮询器:在循环中调用
poller.poll().await以处理InProgress、PollingError和Completed状态:
直接调用 poll 时,您的循环会控制轮询尝试之间的延迟时间。根据操作的预期时长选择合适的延迟时间。
用于轮询中间结果的完整代码
以下函数显示了完整的 poll 循环:
手动轮询长时间运行的操作
虽然 Poller 特征可以处理几乎所有用例,但您也可以使用 get_operation 手动轮询 Operation:
使用
send启动 LRO 后,进入循环并检查done字段:检查
operation.result。result字段是Option,因为某些操作(例如删除)在完成时不会返回载荷。对于rename_folder,该服务会返回Folder资源:检查操作是否已完成但出现错误。错误变体包含
Status消息,以下示例会将其格式化为错误,您也可以使用Error::service将其转换为客户端错误:如果操作成功,请将
Any载荷解压缩为预期的Folder响应类型:添加通配符分支,因为 Rust 的 Cloud 客户端库中的枚举标记为
#[non_exhaustive]:可选:当
operation.done为false时,解压缩operation.metadata以检查进度更新:请稍后再进行轮询。为简便起见,此示例休眠固定的 500 毫秒;在生产代码中,请使用截断的指数退避算法:
使用
operation.name调用get_operation以刷新操作状态:
完整的手动轮询代码
以下函数结合了所有手动轮询步骤: