一部の 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 リソースを取得するには、次の手順を完了します。
use宣言を追加して、型パスを短縮します。バケット ID、ソースフォルダ ID、宛先フォルダ ID を受け取る
async関数を定義します。StorageControlクライアントを初期化します。rename_folderリクエスト ビルダーを作成します。リクエストを送信し、バックグラウンド オペレーションを表す最初の
Operationリソースを待ちます。
オペレーションを開始したら、完了するまで待って最終結果を取得します。
長時間実行オペレーションを自動的にポーリングする
ほとんどのユースケースでは、send を直接呼び出すのではなく、Poller トレイトの until_done メソッドを使用します。ポーラーは 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を呼び出し、オペレーションのステータスを更新します。
手動ポーリングのコードを完成させる
次の関数は、すべての手動ポーリング ステップを組み合わせたものです。