Långvariga operationer i Azure SDK för Java

Den här artikeln innehåller en översikt över hur du använder långvariga åtgärder med Azure SDK för Java.

Vissa åtgärder i Azure kan ta längre tid att slutföra. Dessa åtgärder ligger utanför http-standardformatet för snabbbegäran/svarsflöde. Till exempel är kopiering av data från en käll-URL till en lagringsblob, eller träning av en modell för att identifiera formulär, åtgärder som kan ta några sekunder till flera minuter. Sådana åtgärder kallas Long-Running åtgärder och förkortas ofta som "LRO". En LRO kan ta sekunder, minuter, timmar, dagar eller längre att slutföra, beroende på den begärda åtgärden och den process som måste utföras på serversidan.

I Java-klientbiblioteken för Azure finns en konvention om att alla tidskrävande åtgärder börjar med prefixet begin . Det här prefixet anger att den här åtgärden är tidskrävande och att interaktionssättet med den här åtgärden skiljer sig något från det vanliga flödet för begäran/svar. Tillsammans med prefixet begin är returtypen från åtgärden också annorlunda än vanligt, för att möjliggöra hela utbudet av funktionalitet för långvariga operationer. Precis som med det mesta i Azure SDK för Java finns det både synkrona och asynkrona API:er för långvariga åtgärder:

• I synkrona klienter returnerar långvariga åtgärder en SyncPoller instans.
• I asynkrona klienter returnerar långvariga åtgärder en PollerFlux instans.

Både SyncPoller och PollerFlux är abstraktionerna på klientsidan avsedda att förenkla interaktionen med långvariga åtgärder på serversidan. Resten av den här artikeln beskriver metodtips när du arbetar med dessa typer.

Synkrona tidskrävande åtgärder

Anrop av vilken som helst API som returnerar ett SyncPoller kommer att omedelbart starta den långvariga operationen. API:et returnerar omedelbart SyncPoller så att du kan övervaka förloppet genom att följa processen för den långvariga operationen och hämta slutresultatet. I följande exempel visas hur du övervakar förloppet för en tidskrävande åtgärd med hjälp av 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());

I det här exemplet används poll()-metoden på SyncPoller för att hämta information om förloppet av den långvariga åtgärden. Den här koden skriver ut statusen till konsolen, men en bättre implementering skulle fatta relevanta beslut baserat på den här statusen.

Metoden getRetryAfter() returnerar information om hur lång tid det tar att vänta före nästa omröstning. De flesta Azure-åtgärder som tar lång tid returnerar pollningsfördröjningen som en del av sitt HTTP-svar, det vill säga den vanliga retry-after headern. Om svaret inte innehåller avsökningsfördröjningen getRetryAfter() returnerar metoden varaktigheten som angavs när den långvariga åtgärden anropades.

Exemplet ovan använder en do..while loop för att upprepade gånger avsöka tills den långvariga åtgärden har slutförts. Om du inte är intresserad av dessa mellanliggande resultat kan du i stället anropa waitForCompletion(). Det här anropet blockerar den aktuella tråden tills den långvariga åtgärden har slutförts och returnerar det senaste avsökningssvaret:

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

Om det senaste avsökningssvaret anger att den långvariga åtgärden har slutförts framgångsrikt kan du hämta slutresultatet med hjälp av getFinalResult():

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

Andra användbara API:er i SyncPoller är:

1. waitForCompletion(Duration): vänta på att den långvariga åtgärden ska slutföras inom den angivna tidsgränsen.
2. waitUntil(LongRunningOperationStatus): vänta tills den angivna långvariga åtgärdsstatusen har tagits emot.
3. waitUntil(LongRunningOperationStatus, Duration): vänta tills status för den långvariga åtgärden har tagits emot eller tills den angivna tidsgränsen går ut.

Asynkrona långvariga operationer

Exemplet nedan visar hur PollerFlux låter dig observera en långvarig åtgärd. I asynkrona API:er sker nätverksanropen i en annan tråd än huvudtråden som anropar subscribe(). Det innebär att huvudtråden kan avslutas innan resultatet är tillgängligt. Det är upp till dig att se till att programmet inte avslutas innan asynkroniseringsåtgärden har haft tid att slutföras.

Api:et async returnerar en PollerFlux omedelbart, men den tidskrävande åtgärden startar inte förrän du prenumererar på PollerFlux. Den här processen är hur alla Flux-baserade API:er fungerar. I följande exempel visas en asynkron tidskrävande åtgärd:

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

I följande exempel får du tillfälliga statusuppdateringar om den långvariga processen. Du kan använda de här uppdateringarna för att avgöra om den långvariga åtgärden fortfarande fungerar på det förväntade sättet. Det här exemplet skriver ut statusen till konsolen, men en bättre implementering skulle göra relevanta felhanteringsbeslut baserat på den här statusen.

Om du inte är intresserad av mellanliggande statusuppdateringar och bara vill få ett meddelande om slutresultatet när det kommer kan du använda kod som liknar följande exempel:

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

I den här koden hämtar du slutresultatet av den långvariga åtgärden genom att anropa last(). Det här anropet PollerFlux anger att du vill vänta tills all pollning har slutförts, vid vilken tidpunkt den långvariga processen har nått ett terminaltillstånd, och du kan granska statusen för att avgöra resultatet. Om polleraren anger att den långvariga åtgärden har slutförts kan du hämta slutresultatet och skicka det vidare till konsumenten i prenumerationssamtalet.

Nästa steg

Nu när du är bekant med de långvariga API:erna i Azure SDK för Java kan du läsa Konfigurera proxyservrar i Azure SDK för Java för att lära dig hur du anpassar HTTP-klienten ytterligare.