長時間実行オペレーションを管理する

Cloud de Confiance by S3NS API は、完了までに時間がかかることが予想される呼び出し（Compute Engine インスタンスのプロビジョニングや Dataflow パイプラインの初期化など）に長時間実行オペレーション（LRO）を使用します。 これらの API は、タスクの実行中にアクティブな長時間接続を維持したり、ブロックしたりしません。LRO API の場合、Cloud Client Libraries for Java は後で確認できるように future を返します。

API が LRO かどうかを判断する

API が LRO かどうかを判断するには、主に次の 2 つの方法があります。

• LRO API には、サフィックス Async（createClusterAsync など）または OperationCallable（createClusterOperationCallable など）が付いています。
• LRO API は、OperationFuture または OperationCallable を返します。

次のスニペットは、Java-Dataproc を例として、2 つのバリエーションを示しています。

// Async suffix (#1) returns OperationFuture (#2)
public final OperationFuture<Cluster, ClusterOperationMetadata> createClusterAsync(CreateClusterRequest request)

// OperationCallable suffix (#1) returns OperationCallable (#2)
public final OperationCallable<CreateClusterRequest, Cluster, ClusterOperationMetadata> createClusterOperationCallable()

これらは同じ API の 2 つのバリエーションであり、2 つの異なる API ではありません（どちらの呼び出しも Managed Service for Apache Spark クラスタを作成します）。Async バリアントが推奨されます。

LRO のハイレベル フロー

LRO API は、基本的に最初のリクエスト呼び出しと、それに続く一連の小さなポーリング呼び出しです。最初の呼び出しはリクエストを送信し、サーバーに「オペレーション」を作成します。サーバーへの後続のポーリング呼び出しはすべて、オペレーションのステータスを追跡します。オペレーションが完了すると、レスポンスが返されます。 それ以外の場合は、不完全なステータスが返され、クライアント ライブラリは再度ポーリングするかどうかを判断します。

デフォルトでは、クライアントがポーリング ロジックを処理します。特定の要件がない限り、ポーリング メカニズムを構成する必要はありません。

ユーザーから見ると、レスポンスが受信されるまで呼び出しはバックグラウンドで実行されます。ポーリング呼び出しとタイムアウト構成には、サービスチームが API の予想時間に基づいて事前構成したデフォルト値があります。これらの構成は、ポーリングの頻度や、あきらめるまでの待機時間など、多くの要素を制御します。

Cloud Client Libraries for Java は、OperationFuture を使用して LRO とやり取りするためのインターフェースを提供します。

次のスニペットは、Java-Dataproc を例として、オペレーションを呼び出してレスポンスを待つ方法を示しています。

try (ClusterControllerClient clusterControllerClient = ClusterControllerClient.create()) {
  CreateClusterRequest request =
      CreateClusterRequest.newBuilder().build();
  OperationFuture<Cluster, ClusterOperationMetadata> future =
      clusterControllerClient.createClusterAsync(request);
  // Blocks until there is a response
  Cluster response = future.get();
} catch (CancellationException e) {
  // Exceeded the timeout without the Operation completing.
  // Library is no longer polling for the Operation's status.
}

LRO のデフォルト値

デフォルト値は、各クライアントの StubSettings クラスにあります。initDefaults() メソッドは、ネストされた Builder クラス内の LRO 設定を初期化します。

たとえば、Java-Aiplatform v3.24.0 では、deployModel LRO 呼び出しのデフォルト パラメータは次のようになります。

OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(5000L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(45000L))
    .setTotalTimeoutDuration(Duration.ofMillis(300000L))
    .setInitialRpcTimeoutDuration(Duration.ZERO) // not used
    .setRpcTimeoutMultiplier(1.0) // not used
    .setMaxRpcTimeoutDuration(Duration.ZERO) // not used
    .build()));

再試行と LRO は同じ RetrySettings クラスを共有します。次の表に、RetrySettings 内のフィールドと LRO 機能のマッピングを示します。

LRO 値を構成するタイミング

LRO 値を手動で構成する主なユースケースは、LRO タイムアウトが原因でポーリング頻度を変更することです。デフォルト値はサービスチームによって見積もりとして構成されていますが、特定の要因によりタイムアウトが発生する可能性があります。

タイムアウトの数を減らすには、合計タイムアウト値を増やします。他の値を増やすことも有効です。期待どおりの動作になることを確認するためにテストする必要があります。

LRO 値を構成する方法

LRO 値を構成するには、OperationTimedPollAlgorithm オブジェクトを作成し、特定の LRO のポーリング アルゴリズムを更新します。次のスニペットでは、Java-Dataproc を例として使用します。

ClusterControllerSettings.Builder settingsBuilder = ClusterControllerSettings.newBuilder();
// Create a new OperationTimedPollAlgorithm object
TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(500L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(5000L))
    .setTotalTimeoutDuration(Duration.ofHours(24L))
    .build());
// Set the new polling settings for the specific LRO API 
settingsBuilder.createClusterOperationSettings().setPollingAlgorithm(timedRetryAlgorithm);
ClusterControllerClient clusterControllerClient = ClusterControllerClient.create(settingsBuilder.build());

この構成では、createClusterOperation RPC の LRO 値のみが変更されます。クライアントの他の RPC は、変更されない限り、RPC ごとに事前構成された LRO 値を使用します。

LRO タイムアウト

合計タイムアウトを超えない限り、ライブラリはポーリングを続行します。合計タイムアウトを超えた場合、ライブラリは「Task was cancelled」というメッセージとともに java.util.concurrent.CancellationException をスローします。

CancellationException は、バックエンド Cloud de Confiance by S3NS タスクがキャンセルされたことを意味するものではありません。この例外は、呼び出しが合計タイムアウトを超えてレスポンスを受信しなかった場合に、クライアント ライブラリからスローされます。タイムアウトの直後にタスクが完了した場合でも、クライアント ライブラリはレスポンスを確認できません。