Långvariga åtgärder 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 långvariga å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 skiljer sig returtypen från åtgärden också från vanligt, för att aktivera hela utbudet av tidskrävande åtgärdsfunktioner. 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

Anropar alla API:er som returnerar ett SyncPoller startar omedelbart den tidskrävande åtgärden. API:et SyncPoller returnerar omedelbart så att du kan övervaka förloppet för den långvariga åtgärden 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 poll() här exemplet används metoden på SyncPoller för att hämta information om förloppet för 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 långvariga Azure-åtgärder returnerar avsökningsfördröjningen som en del av deras HTTP-svar (det vill:s, det vanliga retry-after huvudet). 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 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 tills den långvariga åtgärden har slutförts under 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 den angivna långvariga åtgärdsstatusen har tagits emot eller tills den angivna tidsgränsen upphör att gälla.

Asynkrona tidskrävande åtgärder

Exemplet nedan visar hur PollerFlux du kan observera en tidskrävande å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 åtgärden. 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 alla avsökningar har slutförts, då den långvariga åtgärden har nått ett terminaltillstånd, och du kan kontrollera dess status för att fastställa 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.