ポーリング ポリシーの構成

Rust 用 Cloud クライアント ライブラリには、長時間実行オペレーション(LRO)の進行状況をモニタリングするヘルパー関数が用意されています。これらのヘルパーは、ポリシーを使用してポーリング頻度を構成し、どのポーリング エラーが一時的で再試行しても安全か、どのエラーが回復不能かを判断します。

LRO ポーリング ループの動作は、次の 2 つのポリシーで制御されます。

  • ポーリング バックオフ ポリシーは、進行中の LRO のステータスをポーリングする前にループが待機する時間を制御します。
  • ポーリング エラー ポリシーは、ポーリング エラーの処理方法を制御します。一部のポーリング エラーは回復不能です。これは、オペレーションが停止したか、呼び出し元にステータスを確認する権限がないことを示します。その他のポーリング エラーは一時的なもので、ネットワークまたはサービスの一時的な問題を示しています。

各ポリシーは、クライアントで開始されたすべての LRO または個々のリクエストに対して個別に設定できます。

始める前に

このドキュメントでは、Cloud Storage を使用してポーリング ポリシーの構成を説明しますが、同じコンセプトは LRO を使用するすべての Google Cloud サービスに適用されます。

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

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

依存関係

必要なクレートを Cargo.toml ファイルに追加します。

cargo add google-cloud-storage google-cloud-lro google-cloud-gax anyhow

クライアントのすべてのリクエストのポーリング頻度を構成する

クライアントのほとんどのリクエストで同じポーリング バックオフ ポリシーを使用する場合は、クライアント ビルダーでポリシーを構成します。次の例では、StorageControl クライアントによって開始されたすべての LRO に対して、指数ポーリング バックオフを構成します。

pub async fn client_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use google_cloud_lro::Poller;
    use std::time::Duration;

    let client = StorageControl::builder()
        .with_polling_backoff_policy(
            ExponentialBackoffBuilder::new()
                .with_initial_delay(Duration::from_millis(250))
                .with_maximum_delay(Duration::from_secs(10))
                .build()?,
        )
        .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(())
}

個々のリクエストでポリシーをオーバーライドしない限り、この構成はクライアントによって開始されたすべての LRO に適用されます。この例では、クライアント ライブラリは最初のポーリング後に 250 ミリ秒、2 回目のポーリング後に 500 ミリ秒待機します。その後、遅延は 1 秒、2 秒、4 秒、8 秒と倍増し、それ以降のすべてのポーリングでは 10 秒で上限に達します。

特定のリクエストのポーリング頻度を構成する

個々のリクエスト ビルダーでポーリング頻度を構成することもできます。これにより、クライアント レベルのポーリング バックオフ ポリシーがオーバーライドされます。RequestOptionsBuilder をスコープに含め、リクエスト ビルダーで with_polling_backoff_policy を呼び出します。

pub async fn rpc_backoff(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::exponential_backoff::ExponentialBackoffBuilder;
    use std::time::Duration;
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

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

    let response = client
        .rename_folder()
        .with_polling_backoff_policy(
            ExponentialBackoffBuilder::new()
                .with_initial_delay(Duration::from_millis(250))
                .with_maximum_delay(Duration::from_secs(10))
                .build()?,
        )
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

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

    Ok(())
}

クライアントのすべてのリクエストに対してポーリング エラー ポリシーを構成する

ループが再試行するポーリング エラーと、ポーリングを停止するタイミングを制御するには、Aip194Strict などの PollingErrorPolicy トレイトを実装する型を渡します。

ポーリング エラー ポリシーは、LRO 待機ループ中のエラーのみを管理します。LRO を開始する最初のリクエストを送信するときに一時的なエラーを処理するには、クライアントで標準の再試行ポリシーも構成します。

pub async fn client_errors(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_gax::retry_policy;
    use google_cloud_gax::retry_policy::RetryPolicyExt;
    use std::time::Duration;
    use google_cloud_lro::Poller;

    let builder = StorageControl::builder().with_polling_error_policy(
        Aip194Strict
            .with_attempt_limit(100)
            .with_time_limit(Duration::from_secs(300)),
    );

    let client = builder
        .with_retry_policy(
            retry_policy::Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .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(())
}

特定のリクエストのポーリング エラー ポリシーを構成する

単一のリクエストのポーリング エラー ポリシーをオーバーライドするには、RequestOptionsBuilder をスコープに含め、リクエスト ビルダーで with_polling_error_policy を呼び出します。

pub async fn rpc_errors(bucket: &str, folder: &str, dest: &str) -> Result<()> {
    use google_cloud_gax::polling_error_policy::Aip194Strict;
    use google_cloud_gax::polling_error_policy::PollingErrorPolicyExt;
    use google_cloud_gax::retry_policy;
    use google_cloud_gax::retry_policy::RetryPolicyExt;
    use std::time::Duration;
    use google_cloud_gax::options::RequestOptionsBuilder;
    use google_cloud_lro::Poller;

    let client = StorageControl::builder()
        .with_retry_policy(
            retry_policy::Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .build()
        .await?;

    let response = client
        .rename_folder()
        .with_polling_error_policy(
            Aip194Strict
                .with_attempt_limit(100)
                .with_time_limit(Duration::from_secs(300)),
        )
        .set_name(format!("projects/_/buckets/{bucket}/folders/{folder}"))
        .set_destination_folder_id(dest)
        .poller()
        .until_done()
        .await?;

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

    Ok(())
}