Langlopende bewerkingen in de Azure SDK voor Java

Dit artikel bevat een overzicht van het gebruik van langlopende bewerkingen met de Azure SDK voor Java.

Het kan lange tijd duren voordat bepaalde bewerkingen in Azure zijn voltooid. Deze bewerkingen vallen buiten de standaard HTTP-stijl van snelle aanvraag/antwoordstroom. Het kopiëren van gegevens van een bron-URL naar een Opslag-blob of het trainen van een model om formulieren te herkennen, zijn bijvoorbeeld bewerkingen die enkele seconden tot enkele minuten kunnen duren. Dergelijke bewerkingen worden Long-Running Bewerkingen genoemd en worden vaak afgekort als LRO. Een LRO kan seconden, minuten, uren, dagen of langer duren, afhankelijk van de aangevraagde bewerking en het proces dat aan de serverzijde moet worden uitgevoerd.

In de Java-clientbibliotheken voor Azure bestaat een conventie dat alle langlopende bewerkingen beginnen met het begin voorvoegsel. Dit voorvoegsel geeft aan dat deze bewerking lang wordt uitgevoerd en dat de manier van interactie met deze bewerking enigszins verschilt van de gebruikelijke aanvraag-/antwoordstroom. Naast het begin voorvoegsel is het retourtype van de bewerking ook anders dan gebruikelijk, om het volledige scala aan langlopende bewerkingsfunctionaliteit mogelijk te maken. Net als bij de meeste dingen in de Azure SDK voor Java zijn er zowel synchrone als asynchrone API's voor langdurige bewerkingen:

• In synchrone clients geven langlopende bewerkingen een SyncPoller instantie terug.
• In asynchrone clients retourneren langlopende bewerkingen een PollerFlux exemplaar.

Beide SyncPoller en PollerFlux zijn de abstracties aan de clientzijde die zijn bedoeld om de interactie met langlopende bewerkingen aan de serverzijde te vereenvoudigen. In de rest van dit artikel vindt u een overzicht van de aanbevolen procedures voor het werken met deze typen.

Synchrone langlopende bewerkingen

Als u een API aanroept die een SyncPoller retourneert, wordt de langdurige bewerking onmiddellijk gestart. De API retourneert de SyncPoller onmiddellijk, zodat u de voortgang van de langdurige bewerking kunt controleren en het uiteindelijke resultaat kunt ophalen. In het volgende voorbeeld ziet u hoe u de voortgang van een langdurige bewerking kunt bewaken met behulp van de 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());

In dit voorbeeld wordt de poll() methode op de SyncPoller gebruikt om informatie over de voortgang van de langdurige operatie op te halen. Met deze code wordt de status op de console afgedrukt, maar een betere implementatie zou relevante beslissingen op basis van deze status maken.

De getRetryAfter() methode retourneert informatie over hoe lang moet worden gewacht voor de volgende poll. De meeste langlopende Azure-bewerkingen retourneren de pollvertraging als onderdeel van hun HTTP-antwoord (dat wil gezegd de veelgebruikte retry-after header). Als het antwoord de poll-vertraging niet bevat, retourneert de getRetryAfter() methode de duur die is opgegeven op het moment dat de langdurige bewerking wordt aangeroepen.

In het bovenstaande voorbeeld wordt een do..while lus gebruikt om herhaaldelijk een poll uit te voeren totdat de langlopende bewerking is voltooid. Als u niet geïnteresseerd bent in deze tussenresultaten, kunt u in plaats daarvan waitForCompletion() aanroepen. Met deze aanroep wordt de huidige thread geblokkeerd totdat de langlopende bewerking is voltooid en het laatste poll-antwoord wordt geretourneerd:

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

Als het laatste poll-antwoord aangeeft dat de langlopende bewerking is voltooid, kunt u het uiteindelijke resultaat ophalen met behulp van getFinalResult():

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

Andere nuttige API's in SyncPoller zijn onder andere:

1. waitForCompletion(Duration): wacht tot de langlopende bewerking is voltooid, voor de opgegeven time-outduur.
2. waitUntil(LongRunningOperationStatus): wacht totdat de status van de langdurige operatie is ontvangen.
3. waitUntil(LongRunningOperationStatus, Duration): wacht totdat de opgegeven langlopende bewerkingsstatus is ontvangen of totdat de opgegeven time-outduur verloopt.

Asynchrone langlopende bewerkingen

Het onderstaande voorbeeld laat zien hoe de PollerFlux u in staat stelt een langdurige bewerking te observeren. In asynchrone API's vinden de netwerkoproepen plaats in een andere thread dan de hoofdthread die aanroept subscribe(). Dit betekent dat de hoofdthread kan worden beëindigd voordat het resultaat beschikbaar is. Het is aan u om ervoor te zorgen dat de toepassing niet wordt afgesloten voordat de asynchrone bewerking is voltooid.

De asynchrone API retourneert een PollerFlux onmiddellijk, maar de langdurige bewerking zelf wordt pas gestart als u zich abonneert op de PollerFlux. Zo werken alle Flux-gebaseerde API's. In het volgende voorbeeld ziet u een langlopende asynchrone bewerking:

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

In het volgende voorbeeld krijgt u intermitterende statusupdates over de langdurige bewerking. U kunt deze updates gebruiken om te bepalen of de langdurige bewerking nog steeds op de verwachte manier functioneert. In dit voorbeeld wordt de status weergegeven op de console, maar bij een betere implementatie zouden op basis van deze status relevante beslissingen voor foutafhandeling genomen worden.

Als u niet geïnteresseerd bent in de tussenliggende statusupdates en alleen op de hoogte wilt worden gesteld van het uiteindelijke resultaat wanneer het binnenkomt, kunt u code gebruiken die vergelijkbaar is met het volgende voorbeeld:

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

In deze code haalt u het uiteindelijke resultaat van de langdurige bewerking op door aan te roepen last(). Met deze aanroep wordt aangegeven PollerFlux dat u wilt wachten totdat alle polling is voltooid, waarna de langlopende bewerking een terminalstatus heeft bereikt en u de status ervan kunt controleren om het resultaat te bepalen. Als de poller aangeeft dat de langdurige bewerking succesvol is voltooid, kunt u het uiteindelijke resultaat ophalen en doorgeven aan de consument in de subscribe-oproep.

Volgende stappen

Nu u bekend bent met de langlopende API's in de Azure SDK voor Java, raadpleegt u Proxy's configureren in de Azure SDK voor Java voor meer informatie over het verder aanpassen van de HTTP-client.