管理長時間執行的作業

Cloud de Confiance by S3NS API 會使用長時間執行的作業 (LRO)，呼叫預計需要相當長的時間才能完成的作業 (例如佈建 Compute Engine 執行個體或初始化 Dataflow 管道)。這些 API 不會維持長時間的有效連線，也不會在工作執行時封鎖。如果是 LRO API，Java 適用的 Cloud 用戶端程式庫會傳回 future，供您稍後檢查。

判斷 API 是否為 LRO

判斷 API 是否為 LRO 的主要方式有兩種：

LRO API 的後置字元為 Async (例如 createClusterAsync) 或 OperationCallable (例如 createClusterOperationCallable)。
LRO API 會傳回 OperationFuture 或 OperationCallable。

下列程式碼片段顯示這兩種變體，並以 Java-Dataproc 為例：

// 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 的變體，並非兩個不同的 API (這兩個呼叫都會建立 Managed Service for Apache Spark 叢集)。建議使用 Async 變體。

LRO 的高階流程

LRO API 基本上是先發出初始要求呼叫，然後再發出一連串小型輪詢呼叫。初始呼叫會傳送要求，並在伺服器上建立「作業」。後續所有對伺服器的輪詢呼叫都會追蹤作業狀態。如果作業已完成，系統會傳回回應。否則會傳回不完整狀態，用戶端程式庫會判斷是否要再次輪詢。

根據預設，用戶端會處理輪詢邏輯，除非有特定需求，否則不需要設定輪詢機制。

從您的角度來看，通話會在背景執行，直到收到回應為止。輪詢呼叫和逾時設定的預設值，是由服務團隊根據 API 的預期時間預先設定。這些設定可控制許多因素，例如輪詢頻率和放棄前的等待時間。

Java 適用的 Cloud 用戶端程式庫提供介面，可使用 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 功能的對應關係：

RetrySettings	說明
InitialRetryDelay	第一次輪詢前的初始延遲。
MaxRetryDelay	每次輪詢之間的延遲時間上限。
RetryDelayMultiplier	輪詢之間輪詢重試延遲的乘數。
TotalTimeoutDuration	長時間執行的作業可等待的時間上限。

設定 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 值。

長時間執行作業逾時

只要未超過總逾時時間，程式庫就會持續輪詢。如果總逾時時間已超過，程式庫會擲回 java.util.concurrent.CancellationException，並顯示「工作已取消」訊息。

CancellationException 並不代表後端 Cloud de Confiance by S3NS工作已取消。如果呼叫超過總逾時時間且未收到回應，用戶端程式庫就會擲回這項例外狀況。即使工作在逾時後立即完成，用戶端程式庫也不會看到回應。