다음을 통해 공유

Java용 Azure SDK의 장기 실행 작업

  • 아티클

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

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

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

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

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

동기 장기 실행 작업

API를 반환하는 API를 SyncPoller 호출하면 장기 실행 작업이 즉시 시작됩니다. 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();
}

SyncPoller의 다른 유용한 API는 다음과 같습니다.

  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에서 프록시 구성을 참조하세요.