長時間実行オペレーションによる作業

一部の Google Cloud API メソッドは、完了するまでにかなりの時間がかかります。これらのメソッドは、処理が完了するまでブロックするのではなく、進行中のオペレーションを表す Operation リソースを返します。これにより、アプリケーションはステータスと最終結果をポーリングできます。

Rust 用 Cloud クライアント ライブラリには、これらの長時間実行オペレーション(LRO)を操作するためのヘルパーが用意されています。このドキュメントでは、LRO を開始し、完了するまで自動的にポーリングし、中間進行状況の更新を検査して、手動でポーリングする方法について説明します。

始める前に

このドキュメントでは、コード例を具体的にするために Cloud Storage を使用していますが、LRO を使用するすべての Google Cloud サービスに同じコンセプトが適用されます。

このドキュメントのコードを実行する前に、次の前提条件を満たしてください。

  • 課金が有効になっている Google Cloud プロジェクトを作成または選択します。
  • Rust を使ってみるの手順に沿って、開発環境と認証情報を設定します。
  • 階層型名前空間を有効にして Cloud Storage バケットを作成し、名前を変更するソースフォルダを作成します。
  • プリンシパルに、フォルダを管理する権限を持つ Identity and Access Management(IAM)ロール(ストレージ管理者(roles/storage.admin)など)を付与します。

依存関係

クライアント ライブラリと LRO クレートを 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?;

オペレーションを開始したら、完了するまで待って最終結果を取得します。

長時間実行オペレーションを自動的にポーリングする

ほとんどのユースケースでは、send を直接呼び出すのではなく、Poller トレイトの until_done メソッドを使用します。ポーラーは 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(())
}