处理长时间运行的操作

某些 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 资源,请完成以下步骤:

  1. 添加 use 声明以缩短类型路径:

    use anyhow::anyhow;
    use google_cloud_longrunning as longrunning;
    use google_cloud_storage::client::StorageControl;

  2. 定义一个接受存储桶 ID、源文件夹 ID 和目标文件夹 ID 的 async 函数:

    pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {

  3. 初始化 StorageControl 客户端:

    let client = StorageControl::builder().build().await?;

  4. 创建 rename_folder 请求构建器:

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)

  5. 发送请求并等待初始 Operation 资源,该资源表示后台操作:

    .send()
    .await?;

启动操作后,请等待其完成,以检索其最终结果。

自动轮询长时间运行的操作

对于大多数用例,请使用 Poller 特征的 until_done 方法,而不是直接调用 send。轮询器启动 LRO,根据客户端的退避和错误政策进行轮询,并解析为最终响应:

  1. 将 Poller 特征引入作用域:

    use google_cloud_lro::Poller;

  2. 初始化 StorageControl 客户端并配置 rename_folder 请求构建器:

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)

  3. 对请求构建器调用 poller 和 until_done,以等待完成并输出结果:

        .poller()
        .until_done()
        .await?;
    
    println!("LRO completed, response={response:?}");

完成自动轮询代码

以下函数展示了完整的自动轮询示例:

pub async fn automatic(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::Poller;

    let client = StorageControl::builder().build().await?;

    let response = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

    println!("LRO completed, response={response:?}");

    Ok(())
}

轮询具有中间结果的长时间运行的操作

until_done 方法仅返回最终结果,并省略中间元数据更新。如果您的应用在 LRO 运行时需要进度更新,请使用 poller 获取轮询器,并在循环中调用 poll:

  1. 导入 Poller 和 PollingResult:

    use google_cloud_lro::{Poller, PollingResult};

  2. 使用 poller 将请求构建器转换为轮询器:

    .poller();

  3. 在循环中调用 poller.poll().await 以处理 InProgress、PollingError 和 Completed 状态:

    while let Some(p) = poller.poll().await {
        match p {
            PollingResult::Completed(r) => {
                println!("LRO completed, response={r:?}");
            }
            PollingResult::InProgress(m) => {
                println!("LRO in progress, metadata={m:?}");
            }
            PollingResult::PollingError(e) => {
                println!("Transient error polling the LRO: {e}");
            }
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }

直接调用 poll 时,您的循环会控制轮询尝试之间的延迟时间。根据操作的预期时长选择合适的延迟时间。

用于轮询中间结果的完整代码

以下函数显示了完整的 poll 循环:

pub async fn polling(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_lro::{Poller, PollingResult};

    let client = StorageControl::builder().build().await?;

    let mut poller = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller();

    while let Some(p) = poller.poll().await {
        match p {
            PollingResult::Completed(r) => {
                println!("LRO completed, response={r:?}");
            }
            PollingResult::InProgress(m) => {
                println!("LRO in progress, metadata={m:?}");
            }
            PollingResult::PollingError(e) => {
                println!("Transient error polling the LRO: {e}");
            }
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
    }

    Ok(())
}

手动轮询长时间运行的操作

虽然 Poller 特征可以处理几乎所有用例,但您也可以使用 get_operation 手动轮询 Operation:

  1. 使用 send 启动 LRO 后,进入循环并检查 done 字段:

    let response: anyhow::Result<Folder> = loop {
        if operation.done {

  2. 检查 operation.result。result 字段是 Option,因为某些操作(例如删除)在完成时不会返回载荷。对于 rename_folder,该服务会返回 Folder 资源:

    match &operation.result {
        None => {
            break Err(anyhow!("missing result for finished operation"));
        }

  3. 检查操作是否已完成但出现错误。错误变体包含 Status 消息,以下示例会将其格式化为错误,您也可以使用 Error::service 将其转换为客户端错误:

    Some(r) => {
        break match r {
            longrunning::model::operation::Result::Error(s) => {
                Err(anyhow!("operation completed with error {s:?}"))
            }

  4. 如果操作成功,请将 Any 载荷解压缩为预期的 Folder 响应类型:

    longrunning::model::operation::Result::Response(any) => {
        let response = any.to_msg::<Folder>()?;
        Ok(response)
    }

  5. 添加通配符分支,因为 Rust 的 Cloud 客户端库中的枚举标记为 #[non_exhaustive]:

    _ => Err(anyhow!("unexpected result branch {r:?}")),

  6. 可选:当 operation.done 为 false 时,解压缩 operation.metadata 以检查进度更新:

    if let Some(any) = &operation.metadata {
        let metadata = any.to_msg::<RenameFolderMetadata>()?;
        println!("LRO in progress, metadata={metadata:?}");
    }

  7. 请稍后再进行轮询。为简便起见,此示例休眠固定的 500 毫秒;在生产代码中,请使用截断的指数退避算法:

    tokio::time::sleep(std::time::Duration::from_millis(500)).await;

  8. 使用 operation.name 调用 get_operation 以刷新操作状态:

    if let Ok(attempt) = client
        .get_operation()
        .set_name(&operation.name)
        .send()
        .await
    {
        operation = attempt;
    }

完整的手动轮询代码

以下函数结合了所有手动轮询步骤:

pub async fn manual(bucket: &str, folder: &str, dest: &str) -> anyhow::Result<()> {
    use google_cloud_storage::model::Folder;
    use google_cloud_storage::model::RenameFolderMetadata;

    let client = StorageControl::builder().build().await?;

    let operation = client
        .rename_folder()
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .send()
        .await?;
    println!("LRO started, response={operation:?}");

    let mut operation = operation;
    let response: anyhow::Result<Folder> = loop {
        if operation.done {
            match &operation.result {
                None => {
                    break Err(anyhow!("missing result for finished operation"));
                }
                Some(r) => {
                    break match r {
                        longrunning::model::operation::Result::Error(s) => {
                            Err(anyhow!("operation completed with error {s:?}"))
                        }
                        longrunning::model::operation::Result::Response(any) => {
                            let response = any.to_msg::<Folder>()?;
                            Ok(response)
                        }
                        _ => Err(anyhow!("unexpected result branch {r:?}")),
                    };
                }
            }
        }
        if let Some(any) = &operation.metadata {
            let metadata = any.to_msg::<RenameFolderMetadata>()?;
            println!("LRO in progress, metadata={metadata:?}");
        }
        tokio::time::sleep(std::time::Duration::from_millis(500)).await;
        if let Ok(attempt) = client
            .get_operation()
            .set_name(&operation.name)
            .send()
            .await
        {
            operation = attempt;
        }
    };
    println!("LRO completed, response={response:?}");

    Ok(())
}