適用於 Java 的 Azure SDK 中的分頁和反覆專案

本文概述如何使用適用於 Java 的 Azure SDK 分頁和反覆專案功能，在大型數據集上有效率且具生產力地運作。

Azure Java SDK 內用戶端連結庫所提供的許多作業都會傳回多個結果。 Azure Java SDK 在這些情況下會定義一組可接受的傳回類型，以確保開發人員體驗透過一致性最大化。 用於 PagedIterable 同步 API 和 PagedFlux 異步 API 的傳回型別。 API 因不同使用案例而稍有不同，但在概念上，它們具有相同的需求：

• 讓您可以輕鬆地逐一查看集合中的每個元素，忽略手動分頁或追蹤接續令牌的任何需求。 透過PagedIterable逐一查看已還原串行化為指定類型的T分頁回應，讓PagedFlux這項工作變得簡單。 PagedIterable 會實作 Iterable 介面，並提供 API 來接收 Stream，同時 PagedFlux 提供 Flux。 在所有情況下，分頁的動作都是透明的，而反覆專案仍會繼續執行，同時仍會逐一查看結果。

• 逐頁逐一查看。 這麼做可讓您更清楚地瞭解何時提出要求，並可讓您存取每頁回應資訊。 PagedIterable和 PagedFlux 都有方法，這些方法會傳回適當的類型逐頁逐一查看，而不是個別專案。

本文會在 Java Azure SDK 同步和異步 API 之間分割。 當您使用同步用戶端時，您會看到同步反覆運算 API，以及使用異步用戶端時的異步反覆運算 API。

同步分頁和反覆專案

本節涵蓋同步 API。

逐一查看個別元素

如前所述，最常見的使用案例是個別逐一查看每個元素，而不是逐頁逐一查看。 下列程式代碼範例示範 API 如何 PagedIterable 讓您使用您想要實作這項功能的反覆項目樣式。

使用 for-each 迴圈

因為 PagedIterable 實作 Iterable，所以您可以逐一查看 元素，如下列範例所示：

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

使用 Stream

因為 PagedIterable 有定義 stream() 的方法，所以您可以呼叫它以使用標準 Java Stream API，如下列範例所示：

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

使用 Iterator

由於 PagedIterable 會實作 Iterable，因此它也具有 iterator() 允許 Java 反覆運算器程式設計樣式的方法，如下列範例所示：

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

逐一查看頁面

當您使用個別頁面時，您可以逐一查看每頁，例如當您需要 HTTP 回應資訊，或當接續令牌對於保留反覆專案歷程記錄很重要時。 無論您逐頁逐一查看或逐一查看每個專案，效能還是服務呼叫次數都沒有任何差異。 基礎實作會視需要載入下一頁，如果您隨時取消訂閱 PagedFlux ，則不會再呼叫服務。

使用 for-each 迴圈

當您呼叫 listSecrets()時，您會取得具有 PagedIterableAPI 的 iterableByPage() 。 此 API 會產生 Iterable<PagedResponse<Secret>> ，而不是 Iterable<Secret>。 PagedResponse提供回應元數據和接續令牌的存取權，如下列範例所示：

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))
}

另外還有一個 iterableByPage 接受接續令牌的多載。 當您想要稍後回到相同的反覆項目點時，您可以呼叫此多載。

使用 Stream

下列範例示範 方法如何 streamByPage() 執行與上述相同的作業。 此 API 也有接續令牌多載，稍後會傳回相同的反覆項目點。

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

以異步方式觀察頁面和個別元素

本節涵蓋異步 API。 在異步 API 中，網路呼叫發生在與呼叫 subscribe()的主要線程不同的線程中。 這表示主線程可能會在結果可用之前終止。 您必須確定應用程式在異步操作有時間完成之前不會結束。

觀察個別元素

下列範例示範 API 如何 PagedFlux 讓您以異步方式觀察個別元素。 有各種方式可以訂閱 Flux 類型。 如需詳細資訊，請參閱《反應器 3 參考指南》中的簡單建立 Flux 或 Mono 和訂閱它的方法。 此範例有一種不同，其中有三個 Lambda 運算式，一個用於取用者、錯誤取用者，以及完整的取用者。 擁有這三者都是很好的作法，但在某些情況下，只有擁有取用者，而且可能是錯誤的取用者。

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

觀察頁面

下列範例示範 API 如何 PagedFlux 讓您使用 byPage() API 和提供取用者、錯誤取用者和完成取用者，以異步方式觀察每個頁面。

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

下一步

現在您已熟悉適用於 Java 的 Azure SDK 中的分頁和反覆專案，請考慮在適用於 Java 的 Azure SDK 中檢閱長時間執行的作業。 長時間執行的作業是運行時間比大多數一般 HTTP 要求更長的作業，通常是因為它們需要伺服器端的一些工作。