다음을 통해 공유

Java용 Azure SDK의 장기 실행 작업

이 문서에서는 Java용 Azure SDK에서 장기 실행 작업을 사용하는 방법에 대한 개요를 제공합니다.

Azure에서 특정 작업을 완료하는 데 시간이 오래 걸릴 수 있습니다. 이러한 작업은 빠른 요청/응답 흐름의 표준 HTTP 스타일을 벗어났습니다. 예를 들어 원본 URL에서 Storage Blob으로 데이터를 복사하거나 양식을 인식하도록 모델을 학습시키는 작업은 몇 초에서 몇 분 정도 걸릴 수 있습니다. 이러한 작업을 Long-Running 작업이라고 하며 종종 'LRO'로 축약됩니다. LRO는 요청된 작업 및 서버 쪽에서 수행해야 하는 프로세스에 따라 완료하는 데 몇 초, 분, 시간, 일 이상이 걸릴 수 있습니다.

Azure용 Java 클라이언트 라이브러리에는 모든 장기 실행 작업이 접두사로 begin 시작하는 규칙이 있습니다. 이 접두사는 이 작업이 장기 실행 중이며 이 작업과의 상호 작용 수단이 일반적인 요청/응답 흐름과 약간 다르다는 것을 나타냅니다. 접두사와 begin 함께 작업의 반환 형식도 일반적인 것과 다르기 때문에 전체 범위의 장기 실행 작업 기능을 사용할 수 있습니다. Java용 Azure SDK의 대부분의 항목과 마찬가지로 장기 실행 작업에 대한 동기 API와 비동기 API가 모두 있습니다.

  • 동기 클라이언트에서 장기 실행 작업은 인스턴스를 SyncPoller 반환합니다.
  • 비동기 클라이언트에서 장기 실행 작업은 인스턴스를 PollerFlux 반환합니다.

SyncPoller 및 PollerFlux 둘 다 장기 실행 서버 쪽 작업과의 상호 작용을 간소화하기 위한 클라이언트 쪽 추상화입니다. 이 문서의 나머지 부분에는 이러한 형식으로 작업할 때의 모범 사례가 간략하게 설명됩니다.

동기식 장기 실행 작업

SyncPoller를 반환하는 API를 호출하면 장기 실행 작업이 즉시 시작됩니다. API는 SyncPoller을 즉시 반환하므로 장기 실행 작업의 진행을 모니터링하고 최종 결과를 가져올 수 있습니다. 다음 예제는 SyncPoller를 사용하여 장기 실행 작업의 진행률을 모니터링하는 방법을 보여줍니다.

SyncPoller<UploadBlobProgress, UploadedBlobProperties> poller = syncClient.beginUploadFromUri(<URI to upload from>)
PollResponse<UploadBlobProgress> response;

do {
    response = poller.poll();
    System.out.println("Status of long running upload operation: " + response.getStatus());
    Duration pollInterval = response.getRetryAfter();
    TimeUnit.MILLISECONDS.sleep(pollInterval.toMillis());
} while (!response.getStatus().isComplete());

이 예제에서는 poll()의 SyncPoller 메서드를 사용하여 장기 실행 작업의 진행 상황에 대한 정보를 검색합니다. 이 코드는 상태를 콘솔에 출력하지만 더 나은 구현은 이 상태에 따라 관련 결정을 내립니다.

이 메서드는 getRetryAfter() 다음 폴링 전에 대기하는 시간에 대한 정보를 반환합니다. 대부분의 Azure 장기 실행 작업은 HTTP 응답(일반적으로 사용되는 retry-after 헤더)의 일부로 폴링 지연을 반환합니다. 응답에 폴링 지연이 포함되어 있지 않으면 메서드는 getRetryAfter() 장기 실행 작업을 호출할 때 지정된 기간을 반환합니다.

위의 예제에서는 do..while 루프를 사용하여 장기적으로 실행되는 작업이 완료될 때까지 반복적으로 폴링합니다. 이러한 중간 결과에 관심이 없는 경우 대신 호출 waitForCompletion()할 수 있습니다. 이 호출은 장기 실행 작업이 완료되고 마지막 폴링 응답을 반환할 때까지 현재 스레드를 차단합니다.

PollResponse<UploadBlobProgress> response = poller.waitForCompletion();

마지막 폴링 응답에서 장기 실행 작업이 성공적으로 완료되었음을 나타내는 경우, getFinalResult()를 사용하여 최종 결과를 검색할 수 있습니다.

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    UploadedBlobProperties result = poller.getFinalResult();
}

기타 유용한 API는 다음과 같습니다.SyncPoller

  1. waitForCompletion(Duration): 지정된 시간 제한 기간 동안 장기 실행 작업이 완료되기를 기다립니다.
  2. waitUntil(LongRunningOperationStatus): 지정된 장기 실행 작업 상태가 수신될 때까지 기다립니다.
  3. waitUntil(LongRunningOperationStatus, Duration): 지정된 장기 실행 작업 상태가 수신되거나 지정된 시간 제한 기간이 만료될 때까지 기다립니다.

비동기 장기 실행 작업

PollerFlux이(가) 장기 실행 작업을 관찰할 수 있게 하는 방법을 아래 예제에서 보여 줍니다. 비동기 API에서 네트워크 호출은 호출 subscribe()하는 주 스레드와 다른 스레드에서 발생합니다. 즉, 결과를 사용할 수 있기 전에 주 스레드가 종료될 수 있습니다. 비동기 작업을 완료할 시간이 있기 전에 애플리케이션이 종료되지 않도록 해야 합니다.

비동기 API는 PollerFlux를 즉시 반환하지만, 장기 실행 작업 자체는 PollerFlux을 구독할 때까지 시작되지 않습니다. 이 프로세스는 모든 Flux기반 API의 작동 방식입니다. 다음 예제에서는 비동기 장기 실행 작업을 보여줍니다.

asyncClient.beginUploadFromUri(...)
    .subscribe(response -> System.out.println("Status of long running upload operation: " + response.getStatus()));

다음 예제에서는 장기 실행 작업에 대한 일시적인 상태 업데이트를 받습니다. 이러한 업데이트를 사용하여 장기 실행 작업이 예상된 방식으로 계속 작동하고 있는지 확인할 수 있습니다. 이 예제에서는 상태를 콘솔에 출력하지만 더 나은 구현으로 이 상태에 따라 관련 오류 처리 결정을 내릴 수 있습니다.

중간 상태 업데이트에 관심이 없고 최종 결과가 도착하면 알림을 받으려면 다음 예제와 유사한 코드를 사용할 수 있습니다.

asyncClient.beginUploadFromUri(...)
    .last()
    .flatMap(response -> {
        if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
            return response.getFinalResult();
        }
        return Mono.error(new IllegalStateException("Polling completed unsuccessfully with status: "+ response.getStatus()));
    })
    .subscribe(
        finalResult -> processFormPages(finalResult),
        ex -> countDownLatch.countDown(),
        () -> countDownLatch.countDown());

이 코드에서는 를 호출 last()하여 장기 실행 작업의 최종 결과를 검색합니다. 이 호출은 PollerFlux에 모든 폴링이 완료될 때까지 기다리라는 신호를 보내며, 그 후 장기 실행 작업이 완료됨을 나타내고 상태를 검사하여 결과를 확인할 수 있습니다. 폴러가 장기 실행 작업이 성공적으로 완료되었음을 나타내는 경우 최종 결과를 얻어 구독 호출을 통해 소비자에게 전달할 수 있습니다.

다음 단계

Java용 Azure SDK의 장기 실행 API에 익숙해졌으므로 HTTP 클라이언트를 추가로 사용자 지정하는 방법을 알아보려면 Java용 Azure SDK에서 프록시 구성 을 참조하세요.