Udostępnij za pośrednictwem

Długotrwałe operacje w zestawie Azure SDK dla języka Java

  • Artykuł

Ten artykuł zawiera omówienie używania długotrwałych operacji z zestawem Azure SDK dla języka Java.

Wykonanie niektórych operacji na platformie Azure może zająć dużo czasu. Te operacje znajdują się poza standardowym stylem HTTP szybkiego żądania/przepływu odpowiedzi. Na przykład kopiowanie danych ze źródłowego adresu URL do obiektu blob usługi Storage lub trenowanie modelu do rozpoznawania formularzy to operacje, które mogą potrwać od kilku sekund do kilku minut. Takie operacje są określane jako Operacje długotrwałe i są często skracane jako "LRO". Ukończenie operacji LRO może potrwać kilka sekund, minut, godzin, dni lub dłużej, w zależności od żądanej operacji i procesu, który należy wykonać po stronie serwera.

W bibliotekach klienta Java dla platformy Azure istnieje konwencja, że wszystkie długotrwałe operacje zaczynają się od prefiksu begin . Ten prefiks wskazuje, że ta operacja jest długotrwała i że sposób interakcji z tą operacją jest nieco inny niż zwykły przepływ żądania/odpowiedzi. Wraz z prefiksem begin typ zwracany z operacji jest również inny niż zwykle, aby umożliwić pełny zakres funkcji długotrwałych operacji. Podobnie jak w przypadku większości elementów zestawu Azure SDK dla języka Java, istnieją zarówno synchroniczne, jak i asynchroniczne interfejsy API dla długotrwałych operacji:

  • W przypadku klientów synchronicznych długotrwałe operacje będą zwracać SyncPoller wystąpienie.
  • W przypadku klientów asynchronicznych długotrwałe operacje będą zwracać PollerFlux wystąpienie.

Zarówno SyncPoller abstrakcje po stronie klienta, jak i PollerFlux są przeznaczone do uproszczenia interakcji z długotrwałymi operacjami po stronie serwera. W pozostałej części tego artykułu opisano najlepsze rozwiązania dotyczące pracy z tymi typami.

Synchroniczne długotrwałe operacje

Wywołanie dowolnego interfejsu API zwracającego SyncPoller element spowoduje natychmiastowe uruchomienie długotrwałej operacji. Interfejs API zwróci SyncPoller natychmiast, umożliwiając monitorowanie postępu długotrwałej operacji i pobieranie końcowego wyniku. W poniższym przykładzie pokazano, jak monitorować postęp długotrwałej operacji przy użyciu elementu 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());

W tym przykładzie SyncPoller użyto poll() metody w kodzie , aby pobrać informacje o postępie długotrwałej operacji. Ten kod wyświetla stan konsoli, ale lepsza implementacja podejmuje odpowiednie decyzje na podstawie tego stanu.

Metoda getRetryAfter() zwraca informacje o tym, jak długo czekać przed następnym sondą. Większość długotrwałych operacji platformy Azure zwraca opóźnienie sondowania w ramach odpowiedzi HTTP (czyli często używanego retry-after nagłówka). Jeśli odpowiedź nie zawiera opóźnienia sondy, getRetryAfter() metoda zwraca czas trwania podany w momencie wywołania długotrwałej operacji.

W powyższym przykładzie użyto do..while pętli do wielokrotnego sondowania do momentu ukończenia długotrwałej operacji. Jeśli nie interesuje Cię te wyniki pośrednie, możesz wywołać metodę waitForCompletion(). To wywołanie spowoduje zablokowanie bieżącego wątku do momentu zakończenia długotrwałej operacji i zwrócenie ostatniej odpowiedzi sondy:

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

Jeśli ostatnia odpowiedź sondy wskazuje, że długotrwała operacja zakończyła się pomyślnie, możesz pobrać wynik końcowy przy użyciu polecenia getFinalResult():

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

Inne przydatne interfejsy API w systemie SyncPoller to:

  1. waitForCompletion(Duration): poczekaj na ukończenie długotrwałej operacji dla danego limitu czasu.
  2. waitUntil(LongRunningOperationStatus): poczekaj na odebranie danego długotrwałego stanu operacji.
  3. waitUntil(LongRunningOperationStatus, Duration): poczekaj na odebranie danego długotrwałego stanu operacji lub do momentu wygaśnięcia danego limitu czasu.

Operacje asynchroniczne długotrwałe

W poniższym przykładzie pokazano, jak PollerFlux można obserwować długotrwałą operację. W asynchronicznych interfejsach API wywołania sieciowe są wykonywane w innym wątku niż główny wątek, który wywołuje metodę subscribe(). Oznacza to, że główny wątek może zakończyć się przed udostępnieniem wyniku. Należy upewnić się, że aplikacja nie kończy działania przed ukończeniem operacji asynchronicznych.

Asynchroniczny interfejs API zwraca PollerFlux wartość natychmiast, ale długotrwała operacja nie zostanie uruchomiona, dopóki nie zasubskrybujesz elementu PollerFlux. Ten proces polega na tym, jak działają wszystkie Fluxinterfejsy API oparte na systemie. W poniższym przykładzie przedstawiono operację asynchroniową długotrwałą:

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

W poniższym przykładzie uzyskasz sporadyczne aktualizacje stanu dla długotrwałej operacji. Za pomocą tych aktualizacji można określić, czy długotrwała operacja nadal działa zgodnie z oczekiwaniami. W tym przykładzie stan jest wyświetlany w konsoli programu , ale lepsza implementacja pozwoliłaby podejmować odpowiednie decyzje dotyczące obsługi błędów w oparciu o ten stan.

Jeśli nie interesuje Cię aktualizacja stanu pośredniego i po prostu chcesz otrzymywać powiadomienia o końcowym wyniku po nadejściu, możesz użyć kodu podobnego do następującego przykładu:

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());

W tym kodzie pobierasz końcowy wynik długotrwałej operacji, wywołując metodę last(). To wywołanie informuje PollerFlux , że chcesz poczekać na ukończenie wszystkich sondowania, w którym momencie długotrwała operacja osiągnęła stan terminalu, i możesz sprawdzić jego stan, aby określić wynik. Jeśli poller wskazuje, że długotrwała operacja została ukończona pomyślnie, możesz pobrać wynik końcowy i przekazać go do odbiorcy w wywołaniu subskrypcji.

Następne kroki

Teraz, gdy znasz długotrwałe interfejsy API w zestawie Azure SDK dla języka Java, zobacz Konfigurowanie serwerów proxy w zestawie Azure SDK dla języka Java , aby dowiedzieć się, jak dalej dostosowywać klienta HTTP.