Paginierung und Iteration im Azure SDK für Java

Dieser Artikel enthält eine Übersicht über die Verwendung des Azure SDK für Java-Paginierungs- und Iterationsfunktionen, um effizient und produktiv mit großen Datasets zu arbeiten.

Viele Vorgänge, die von den Clientbibliotheken im Azure Java SDK bereitgestellt werden, geben mehr als ein Ergebnis zurück. Das Azure Java SDK definiert eine Reihe akzeptabler Rückgabetypen in diesen Fällen, um sicherzustellen, dass die Entwicklererfahrung durch Konsistenz maximiert wird. Die verwendeten Rückgabetypen sind PagedIterable für synchrone APIs und PagedFlux für asynchrone APIs. Die APIs unterscheiden sich geringfügig unter Berücksichtigung ihrer unterschiedlichen Anwendungsfälle, aber konzeptionell weisen sie die gleichen Anforderungen auf:

• Ermöglichen der einfachen Iteration über jedes einzelne Element in der Sammlung, wobei jegliche Erfordernis von manueller Paginierung oder Nachverfolgung von Fortsetzungstoken ignoriert wird. Sowohl PagedIterable als auch PagedFlux erleichtern diese Aufgabe, indem die Iteration über eine paginierte Antwort erfolgt, die in den angegebenen Typ T deserialisiert wurde. PagedIterable implementiert die Iterable Schnittstelle und stellt eine API bereit, um eine Stream zu empfangen, während PagedFlux eine Flux bereitstellt. In allen Fällen ist der Vorgang der Paginierung transparent, und die Iteration wird fortgesetzt, während noch Ergebnisse vorhanden sind, die noch iteriert werden müssen.

• Ermöglichen der explizit seitenweisen Iteration. Auf diese Weise können Sie besser verstehen, wenn Anforderungen gestellt werden, und Sie können auf Seitenantwortinformationen zugreifen. Sowohl PagedIterable als auch PagedFlux besitzen Methoden, die Typen zurückgeben, die für die seitenweise Iteration geeignet sind, anstatt über einzelne Elemente.

Dieser Artikel wird zwischen synchronen und asynchronen Java Azure SDK-APIs aufgeteilt. Sie sehen die synchronen Iterations-APIs, wenn Sie mit synchronen Clients arbeiten, und asynchrone Iterations-APIs, wenn Sie mit asynchronen Clients arbeiten.

Synchrone Paginierung und Iteration

In diesem Abschnitt werden die synchronen APIs behandelt.

Über einzelne Elemente iterieren

Wie bereits erwähnt, besteht der am häufigsten verwendete Anwendungsfall darin, jedes Element einzeln und nicht pro Seite zu durchlaufen. Die folgenden Codebeispiele zeigen, wie Sie mit der PagedIterable API den Iterationsstil verwenden können, den Sie bevorzugen, um diese Funktionalität zu implementieren.

Verwenden einer „For Each“-Schleife

Da PagedIterableIterable implementiert, können Sie die Elemente durchlaufen, wie im folgenden Beispiel gezeigt wird:

PagedIterable<Secret> secrets = client.listSecrets();
for (Secret secret : secrets) {
   System.out.println("Secret is: " + secret);
}

Stream verwenden

Da auf PagedIterable eine stream() Methode definiert ist, können Sie diese aufrufen, um die Standard-Java-Stream-APIs zu verwenden, wie im folgenden Beispiel gezeigt wird:

client.listSecrets()
      .stream()
      .forEach(secret -> System.out.println("Secret is: " + secret));

Iterator verwenden

Da PagedIterableIterable implementiert, verfügt es auch über eine iterator() Methode, die den Java-Iterator-Programmierstil zulässt, im folgenden Beispiel gezeigt:

Iterator<Secret> secrets = client.listSecrets().iterator();
while (it.hasNext()) {
   System.out.println("Secret is: " + it.next());
}

Iterieren über Seiten

Wenn Sie mit einzelnen Seiten arbeiten, können Sie pro Seite iterieren, z. B. wenn Sie HTTP-Antwortinformationen benötigen oder wenn Fortsetzungstoken wichtig sind, um den Iterationsverlauf beizubehalten. Unabhängig davon, ob Sie seitenweise oder pro Element iterieren, gibt es keinen Unterschied in der Leistung oder der Anzahl der Aufrufe, die an den Dienst getätigt werden. Die zugrunde liegende Implementierung lädt die nächste Seite bei Bedarf, und wenn Sie sich jederzeit von PagedFlux abmelden, gibt es keine weiteren Aufrufe an den Dienst.

Verwenden einer „For Each“-Schleife

Wenn Sie listSecrets() aufrufen, erhalten Sie eine PagedIterable, die über eine iterableByPage() API verfügt. Diese API erzeugt ein Iterable<PagedResponse<Secret>> anstelle von einem Iterable<Secret>. Die PagedResponse stellt die Antwortmetadaten und den Zugriff auf das Fortsetzungstoken bereit, wie im folgenden Beispiel gezeigt:

Iterable<PagedResponse<Secret>> secretPages = client.listSecrets().iterableByPage();
for (PagedResponse<Secret> page : secretPages) {
   System.out.println("Response code: " + page.getStatusCode());
   System.out.println("Continuation Token: " + page.getContinuationToken());
   page.getElements().forEach(secret -> System.out.println("Secret value: " + secret))
}

Außerdem gibt es eine iterableByPage-Überladung, die ein Fortsetzungstoken akzeptiert. Sie können diese Überladung aufrufen, wenn Sie zu einem späteren Zeitpunkt zum gleichen Iterationspunkt zurückkehren möchten.

Stream verwenden

Das folgende Beispiel zeigt, wie die streamByPage() Methode denselben Vorgang wie oben gezeigt ausführt. Diese API verfügt auch über eine Fortsetzungstokenüberladung, um zu einem späteren Zeitpunkt an den gleichen Iterationspunkt zurückzukehren.

client.listSecrets()
      .streamByPage()
      .forEach(page -> {
          System.out.println("Response code: " + page.getStatusCode());
          System.out.println("Continuation Token: " + page.getContinuationToken());
          page.getElements().forEach(secret -> System.out.println("Secret value: " + secret))
      });

Asynchrones Beobachten von Seiten und einzelnen Elementen

In diesem Abschnitt werden die asynchronen APIs behandelt. In asynchronen APIs erfolgen die Netzwerkaufrufe in einem anderen Thread als im Hauptthread, der subscribe() aufruft. Dies bedeutet, dass der Hauptthread beendet werden kann, bevor das Ergebnis verfügbar ist. Es liegt an Ihnen, sicherzustellen, dass die Anwendung nicht beendet wird, bevor der asynchrone Vorgang abgeschlossen wurde.

Beobachten einzelner Elemente

Das folgende Beispiel zeigt, wie Sie mit der PagedFlux API einzelne Elemente asynchron beobachten können. Es gibt verschiedene Möglichkeiten, einen Flux-Typ zu abonnieren. Weitere Informationen finden Sie unter Einfache Möglichkeiten, einen Flux oder ein Mono zu erstellen und zu abonnieren im Referenzhandbuch zu Reaktor 3. Dieses Beispiel ist eine Art, bei der es drei Lambda-Ausdrücke gibt, jeweils einen für den Verbraucher, den Fehlerverbraucher und den vollständigen Verbraucher. Es ist bewährte Praxis, alle drei zu verwenden, doch in manchen Fällen ist es nur notwendig, den Consumer und vielleicht noch den Fehlerconsumer zu verwenden.

asyncClient.listSecrets()
   .subscribe(secret -> System.out.println("Secret value: " + secret),
       ex -> System.out.println("Error listing secrets: " + ex.getMessage()),
       () -> System.out.println("Successfully listed all secrets"));

Seiten beobachten

Das folgende Beispiel zeigt, wie Sie mit der PagedFlux-API jede Seite asynchron beobachten können, wiederum durch Verwendung einer byPage()-API und durch Bereitstellen eines Consumers, Fehlerconsumers und Abschlussconsumers.

asyncClient.listSecrets().byPage()
  .subscribe(page -> {
          System.out.println("Response code: " + page.getStatusCode());
          System.out.println("Continuation Token: " + page.getContinuationToken());
          page.getElements().forEach(secret -> System.out.println("Secret value: " + secret))
      },
      ex -> System.out.println("Error listing pages with secret: " + ex.getMessage()),
      () -> System.out.println("Successfully listed all pages with secret"));

Nächste Schritte

Nachdem Sie nun mit Paginierung und Iteration im Azure SDK für Java vertraut sind, sollten Sie die Überprüfung von Vorgängen mit langer Ausführung im Azure SDK für Java in Betracht ziehen. Vorgänge mit langer Ausführung sind Vorgänge, die länger als die meisten normalen HTTP-Anforderungen ausgeführt werden, in der Regel, da sie auf der Serverseite einige Anstrengungen erfordern.