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 に対して、指数ポーリング バックオフを構成します。
個々のリクエストでポリシーをオーバーライドしない限り、この構成はクライアントによって開始されたすべての LRO に適用されます。この例では、クライアント ライブラリは最初のポーリング後に 250 ミリ秒、2 回目のポーリング後に 500 ミリ秒待機します。その後、遅延は 1 秒、2 秒、4 秒、8 秒と倍増し、それ以降のすべてのポーリングでは 10 秒で上限に達します。
特定のリクエストのポーリング頻度を構成する
個々のリクエスト ビルダーでポーリング頻度を構成することもできます。これにより、クライアント レベルのポーリング バックオフ ポリシーがオーバーライドされます。RequestOptionsBuilder をスコープに含め、リクエスト ビルダーで with_polling_backoff_policy を呼び出します。
クライアントのすべてのリクエストに対してポーリング エラー ポリシーを構成する
ループが再試行するポーリング エラーと、ポーリングを停止するタイミングを制御するには、Aip194Strict などの PollingErrorPolicy トレイトを実装する型を渡します。
ポーリング エラー ポリシーは、LRO 待機ループ中のエラーのみを管理します。LRO を開始する最初のリクエストを送信するときに一時的なエラーを処理するには、クライアントで標準の再試行ポリシーも構成します。
特定のリクエストのポーリング エラー ポリシーを構成する
単一のリクエストのポーリング エラー ポリシーをオーバーライドするには、RequestOptionsBuilder をスコープに含め、リクエスト ビルダーで with_polling_error_policy を呼び出します。