Dlouhodobé operace v Azure SDK pro Javu

Tento článek vysvětluje dlouhotrvající operace v Azure SDK pro Java a ukazuje, jak sledovat průběh a načítat konečné výsledky s menší logikou ručního dotazování.

Dokončení některých operací Azure trvá delší dobu. Tyto operace nedodržují standardní styl HTTP rychlého požadavku a toku odpovědi. Například kopírování dat ze zdrojové adresy URL do objektu blob úložiště nebo trénování modelu pro rozpoznávání formulářů jsou operace, které můžou trvat několik sekund až několik minut. Tyto operace jsou dlouhotrvající operace, často zkrácené jako LRO. Dokončení LRO může trvat několik sekund, minut, hodin, dnů nebo déle v závislosti na požadované operaci a procesu, který musí server provést.

V Java klientských knihovnách pro Azure začínají všechny dlouhotrvající operace s předponoubegin. Tato předpona označuje, že operace je dlouhotrvající a že se způsob interakce s touto operací mírně liší od obvyklého toku požadavků a odpovědí. Kromě předpony begin se návratový typ operace liší i od obvyklého typu, aby bylo možné povolit celou řadu funkcí dlouhotrvajících operací. Stejně jako u většiny věcí v Azure SDK pro Java mají dlouhotrvající operace synchronní i asynchronní rozhraní API:

  • U synchronních klientů vracejí dlouhotrvající operace instanci typu SyncPoller.
  • Asynchronní klienti vracejí u dlouhotrvajících operací instanci PollerFlux.

Jak SyncPoller, tak PollerFlux jsou klientské abstrakce, které zjednodušují interakci s dlouho běžícími operacemi na straně serveru. Zbytek tohoto článku popisuje osvědčené postupy při práci s těmito typy.

Synchronní dlouhotrvající operace

Když zavoláte rozhraní API, které vrací SyncPoller, dlouhotrvající operace se spustí okamžitě. Rozhraní API ihned vrátí SyncPoller, takže můžete sledovat průběh dlouhotrvající operace a získat konečný výsledek. Následující příklad ukazuje, jak monitorovat průběh dlouhotrvající operace pomocí SyncPollernástroje .

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

Tento příklad používá metodu poll()SyncPoller k získání informací o průběhu dlouhotrvající operace. Tento kód vypíše stav do konzoly, ale lepší implementace provede relevantní rozhodnutí na základě tohoto stavu.

Metoda getRetryAfter() vrátí informace o tom, jak dlouho čekat před dalším dotazem. Většina dlouhotrvajících operací Azure vrací zpoždění dotazování jako součást odpovědi HTTP (to znamená běžně používané retry-after hlavičky). Pokud odpověď neobsahuje interval dotazování, metoda getRetryAfter() vrátí dobu zadanou při vyvolání dlouho běžící operace.

Předchozí příklad používá smyčku do..while k opakovanému dotazování, dokud se dlouhotrvající operace nedokončí. Pokud vás tyto průběžné výsledky nezajímají, můžete místo toho zavolat waitForCompletion(). Toto volání blokuje aktuální vlákno, dokud dlouhotrvající operace nedokončí a nevrátí poslední odpověď dotazu:

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

Pokud poslední odpověď dotazování značí, že dlouhotrvající operace úspěšně skončí, můžete konečný výsledek získat pomocí getFinalResult():

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

Mezi další užitečná rozhraní API SyncPoller patří:

  • waitForCompletion(Duration): počkat na dokončení dlouho běžící operace po zadanou dobu časového limitu.
  • waitUntil(LongRunningOperationStatus): Počkejte, až bude přijat stav dané dlouhotrvající operace.
  • waitUntil(LongRunningOperationStatus, Duration): Počkejte, až se přijme daný stav dlouhotrvající operace nebo dokud nevyprší daná doba časového limitu.

Asynchronní dlouhotrvající operace

Následující příklad ukazuje, jak vám PollerFlux umožňuje sledovat dlouhotrvající operaci. V asynchronních rozhraních API probíhají síťová volání v jiném vlákně než v hlavním vlákně, které volá subscribe(). Tato architektura znamená, že hlavní vlákno může před dostupností výsledku ukončit. Před dokončením asynchronní operace musíte zajistit, aby se aplikace neodekončila.

Asynchronní rozhraní API vrátí okamžitě PollerFlux , ale dlouhotrvající operace se nespustí, dokud se nepřihlásíte k odběru PollerFlux. Tento proces je způsob, jakým fungují všechna rozhraní API založená na Flux. Následující příklad ukazuje asynchronní dlouhotrvající operaci:

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

V následujícím příkladu získáte přerušované aktualizace stavu u dlouhotrvající operace. Tyto aktualizace můžete použít k určení, jestli dlouhotrvající operace stále funguje očekávaným způsobem. Tento příklad vytiskne stav do konzoly, ale lepší implementace by na základě tohoto stavu udělala relevantní rozhodnutí o zpracování chyb.

Pokud nemáte zájem o průběžné aktualizace stavu a chcete dostávat oznámení o konečném výsledku, až přijde, použijte kód podobný následujícímu příkladu:

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

V tomto kódu načtete konečný výsledek dlouhotrvající operace voláním last(). Toto volání informuje PollerFlux, že chcete počkat, až se dokončí veškeré dotazování. V tomto okamžiku dlouhotrvající operace dosáhne stavu terminálu a můžete zkontrolovat její stav a určit výsledek. Pokud poller indikuje, že dlouho běžící operace byla úspěšně dokončena, můžete načíst konečný výsledek a předat jej konzumentovi ve volání subscribe.

Další kroky

Teď když znáte dlouho běžící rozhraní API v sadě Azure SDK pro Javu, podívejte se na Konfigurace proxy serverů v sadě Azure SDK pro Javu, kde se dozvíte, jak dále přizpůsobit klienta HTTP.

  • Last updated on