장기 실행 작업 관리

Google Cloud API는 완료하는 데 상당한 시간이 걸릴 것으로 예상되는 호출 (예: Compute Engine 인스턴스 프로비저닝 또는 Dataflow 파이프라인 초기화)에 장기 실행 작업 (LRO)을 사용합니다. 이러한 API는 작업이 실행되는 동안 활성 장기 연결을 유지하거나 차단하지 않습니다. LRO API의 경우 자바용 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가 아닙니다(두 호출 모두 Dataproc 클러스터를 만듦). 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 값을 계속 사용합니다.

LRO 제한 시간

총 제한 시간이 초과되지 않는 한 라이브러리는 계속해서 폴링합니다. 총 제한 시간이 초과되면 라이브러리에서 '작업이 취소되었습니다'라는 메시지와 함께 java.util.concurrent.CancellationException이 발생합니다.

CancellationException가 백엔드 Google Cloud작업이 취소되었음을 의미하지는 않습니다. 이 예외는 호출이 총 제한 시간을 초과하고 응답을 수신하지 못한 경우 클라이언트 라이브러리에서 발생합니다. 제한 시간 후 바로 작업을 완료하더라도 클라이언트 라이브러리에서 응답을 확인할 수 없습니다.