次の方法で共有

Azure SDK for Java での改ページとイテレーション

この記事では、Azure SDK for Java の改ページ位置付けと反復機能を使用して、大規模なデータ セットを効率的かつ生産的に動作させる方法の概要について説明します。

Azure Java SDK 内のクライアント ライブラリによって提供される多くの操作では、複数の結果が返されます。 Azure Java SDK では、このような場合に許容される一連の戻り値の型を定義して、一貫性によって開発者エクスペリエンスが最大化されるようにします。 使用される戻り値の型は、同期 API と非同期 API のPagedFluxにPagedIterableされます。 API はユース ケースによって若干異なりますが、概念的には同じ要件があります。

  • 手動による改ページや継続トークンの追跡の必要性を無視して、コレクション内の各要素を個別に簡単に反復処理できるようにします。 PagedIterableとPagedFluxの両方で、特定の型Tに逆シリアル化されたページ分割された応答を反復処理することで、このタスクを容易にします。 PagedIterable は Iterable インターフェイスを実装し、 Streamを受け取る API を提供しますが、 PagedFlux は Fluxを提供します。 いずれの場合も、改ページ位置の動作は透過的であり、反復処理は続行されますが、結果は反復処理されます。

  • ページごとに明示的に反復処理できるようにします。 そうすることで、要求がいつ行われるかをより明確に理解し、ページごとの応答情報にアクセスできます。 PagedIterableとPagedFluxの両方に、個々の要素ではなく、ページごとに反復処理する適切な型を返すメソッドがあります。

この記事は、Java Azure SDK の同期 API と非同期 API の間で分割されています。 同期クライアントを操作する場合は同期イテレーション API、非同期クライアントを使用する場合は非同期反復 API が表示されます。

同期改ページとイテレーション

このセクションでは、同期 API について説明します。

個々の要素を反復処理する

説明したように、最も一般的なユース ケースは、ページごとにではなく、各要素を個別に反復処理する方法です。 次のコード例は、 PagedIterable API を使用して、この機能を実装する反復スタイルを使用する方法を示しています。

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

反復子を使用する

PagedIterableはIterableを実装するため、次の例に示すように、Java 反復子プログラミング スタイルを許可するiterator() メソッドもあります。

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

ページを反復処理する

個々のページを操作する場合は、HTTP 応答情報が必要な場合や、反復履歴を保持するために継続トークンが重要な場合など、ページごとに反復処理できます。 ページまたは各項目を反復処理しても、パフォーマンスやサービスに対する呼び出しの数に違いはありません。 基になる実装では、次のページが必要に応じて読み込まれます。また、いつでも PagedFlux のサブスクライブを解除した場合、サービスへの呼び出しはそれ以上ありません。

for-each ループを使用する

listSecrets()を呼び出すと、iterableByPage() API を持つPagedIterableが取得されます。 この API は、Iterable<Secret>ではなくIterable<PagedResponse<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()を呼び出すメイン スレッドとは異なるスレッドで発生します。 これは、結果が使用可能になる前にメイン スレッドが終了する可能性があることを意味します。 非同期操作が完了するまでにアプリケーションが終了しないようにする必要があります。

個々の要素を観察する

次の例は、 PagedFlux API を使用して個々の要素を非同期的に観察する方法を示しています。 Flux 型をサブスクライブするには、さまざまな方法があります。 詳細については、「Reactor 3 リファレンス ガイド」の「Flux または Mono を作成してサブスクライブする簡単な方法」を参照してください。 この例は、3 つのラムダ式があり、それぞれコンシューマー、エラー コンシューマー、および完全なコンシューマーがある 1 つの種類です。 3 つすべてを用意することをお勧めしますが、場合によってはコンシューマーと、場合によってはエラー コンシューマーを用意するだけで済みます。

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

ページを観察する

次の例では、 PagedFlux API を使用して、 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"));

次のステップ

Azure SDK for Java での改ページとイテレーションについて理解したら、 Azure SDK for Java で実行時間の長い操作を確認することを検討してください。 実行時間の長い操作は、通常の HTTP 要求よりも長い期間実行される操作です。通常は、サーバー側で何らかの作業が必要になるためです。