Lang andauernde Vorgänge im Azure SDK für Java

In diesem Artikel werden lang andauernde Vorgänge im Azure SDK für Java erläutert. Außerdem wird gezeigt, wie Sie den Fortschritt nachverfolgen und die Endergebnisse mit weniger manueller Abfragelogik abrufen können.

Bestimmte Vorgänge für Azure dauern längere Zeit bis zum Abschluss. Diese Vorgänge folgen nicht dem standardmäßigen HTTP-Stil des Schnellanforderungs- und Antwortflusses. Beispielsweise sind das Kopieren von Daten aus einer Quell-URL in ein Speicher-Blob oder das Trainieren eines Modells zum Erkennen von Formularen Vorgänge, die einige Sekunden bis zu mehreren Minuten dauern können. Bei diesen Vorgängen handelt es sich um langwierige Vorgänge, die häufig als LRO abgekürzt werden. Ein LRO kann abhängig von dem angeforderten Vorgang und dem Prozess, den der Server ausführen muss, Sekunden, Minuten, Stunden, Tage oder länger dauern.

In den Java-Clientbibliotheken für Azure beginnen alle länger andauernden Vorgänge mit dem Präfix begin. Dieses Präfix gibt an, dass der Vorgang lang ausgeführt wird und dass sich die Interaktionsmöglichkeiten mit diesem Vorgang geringfügig vom üblichen Anforderungs- und Antwortfluss unterscheiden. Zusammen mit dem begin Präfix unterscheidet sich der Rückgabetyp des Vorgangs ebenfalls von den üblichen, um die gesamte Palette von Funktionen für lang andauernde Vorgänge zu aktivieren. Wie bei den meisten Dingen in der Azure SDK für Java verfügen lang ausgeführte Vorgänge sowohl über synchrone als auch über asynchrone APIs:

  • In synchronen Clients geben lang andauernde Vorgänge eine Instanz von SyncPoller zurück.
  • Bei asynchronen Clients geben lang andauernde Vorgänge eine PollerFlux-Instanz zurück.

Sowohl SyncPoller als auch PollerFlux sind clientseitige Abstraktionen, die die Interaktion mit länger laufenden serverseitigen Operationen vereinfachen. Im restlichen Artikel werden bewährte Methoden beim Arbeiten mit diesen Typen beschrieben.

Synchrone zeitintensive Vorgänge

Wenn Sie eine API aufrufen, die ein SyncPoller zurückgibt, wird der lang andauernde Vorgang sofort gestartet. Die API gibt SyncPoller sofort zurück, sodass Sie den Fortschritt des lang andauernden Vorgangs überwachen und das endgültige Ergebnis erhalten können. Das folgende Beispiel zeigt, wie der Fortschritt eines lang andauernden Vorgangs mithilfe von SyncPoller überwacht wird.

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 diesem Beispiel wird die Methode poll() für das SyncPoller verwendet, um Informationen über den Fortschritt des länger andauernden Vorgangs abzurufen. Dieser Code druckt den Status in der Konsole, aber eine bessere Implementierung trifft relevante Entscheidungen basierend auf diesem Status.

Die getRetryAfter() Methode gibt Informationen dazu zurück, wie lange vor der nächsten Abfrage gewartet werden soll. Die meisten lang ausgeführten Azure-Vorgänge geben die Abfrageverzögerung als Teil ihrer HTTP-Antwort zurück (d. h. den häufig verwendeten retry-after Header). Wenn die Antwort die Abfrageverzögerung nicht enthält, gibt die Methode getRetryAfter() die Dauer zurück, die beim Aufruf des lang laufenden Vorgangs angegeben wurde.

Im vorherigen Beispiel wird eine do..while-Schleife verwendet, um wiederholt abzufragen, bis der länger andauernde Vorgang abgeschlossen ist. Wenn Sie nicht an diesen Zwischenergebnissen interessiert sind, können Sie stattdessen anrufen waitForCompletion(). Dieser Aufruf blockiert den aktuellen Thread, bis der lange ausgeführte Vorgang abgeschlossen ist, und gibt die letzte Umfrageantwort zurück:

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

Wenn die letzte Abfrageantwort angibt, dass der lang andauernde Vorgang erfolgreich abgeschlossen wurde, können Sie das Endergebnis mit getFinalResult() abrufen:

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

In SyncPoller finden sich weitere nützliche APIs:

  • waitForCompletion(Duration): Warten Sie für die angegebene Zeitüberschreitungsdauer, bis der lang andauernde Vorgang abgeschlossen ist.
  • waitUntil(LongRunningOperationStatus): Wartet, bis der angegebene Status des zeitintensiven Vorgangs empfangen wurde.
  • waitUntil(LongRunningOperationStatus, Duration): Wartet, bis der angegebene Status des zeitintensiven Vorgangs empfangen wurde, oder bis die angegebene Timeoutdauer abgelaufen ist.

Asynchrone zeitintensive Vorgänge

Das folgende Beispiel zeigt, wie PollerFlux Ihnen ermöglicht, einen lang andauernden Vorgang zu beobachten. In asynchronen APIs erfolgen Netzwerkaufrufe in einem anderen Thread als im Hauptthread, der subscribe() aufruft. Diese Architektur bedeutet, dass der Hauptthread möglicherweise beendet wird, bevor das Ergebnis verfügbar ist. Sie müssen sicherstellen, dass die Anwendung nicht beendet wird, bevor der asynchrone Vorgang abgeschlossen ist.

Die asynchrone API gibt sofort ein PollerFlux zurück, aber die lang andauernde Operation selbst beginnt erst, wenn Sie das PollerFlux abonnieren. Dieser Prozess ist die Funktionsweise aller Flux-basierten APIs. Das folgende Beispiel zeigt einen asynchronen lang andauernden Vorgang.

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

Im folgenden Beispiel erhalten Sie während des lang andauernden Vorgangs regelmäßige Statusaktualisierungen. Sie können diese Updates verwenden, um zu bestimmen, ob der lange ausgeführte Vorgang weiterhin erwartungsgemäß funktioniert. Mit diesem Beispiel wird der Status in der Konsole ausgegeben, aber eine bessere Implementierung würde relevante Entscheidungen zur Fehlerbehandlung auf Grundlage dieses Status treffen.

Wenn Sie nicht an den Zwischenstatusaktualisierungen interessiert sind und nur benachrichtigt werden möchten, wann das Endergebnis eingeht, verwenden Sie Code ähnlich dem folgenden Beispiel:

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 diesem Code erhalten Sie das Endergebnis des lange ausgeführten Vorgangs durch das Aufrufen von last(). Dieser Aufruf teilt dem PollerFlux mit, dass Sie warten wollen, bis das gesamte Polling abgeschlossen ist. An diesem Punkt erreicht der lange ausgeführte Vorgang einen Terminalzustand, und Sie können den Status überprüfen, um das Ergebnis zu ermitteln. Wenn der Poller anzeigt, dass der lang andauernde Vorgang erfolgreich abgeschlossen wurde, können Sie das Endergebnis abrufen und es im Abonnementaufruf an den Verbraucher weiterleiten.

Nächste Schritte

Nachdem Sie nun mit den langfristig ausgeführten APIs im Azure SDK für Java vertraut sind, lesen Sie "Konfigurieren von Proxies im Azure SDK für Java", um zu erfahren, wie Sie den HTTP-Client weiter anpassen können.

  • Last updated on