Paginasi dan iterasi di Azure SDK for Java

  • Artikel

Artikel ini memberikan gambaran umum tentang cara menggunakan fungsi paginasi dan iterasi Azure SDK for Java untuk bekerja secara efisien dan produktif dengan himpunan data yang besar.

Banyak operasi yang disediakan oleh pustaka klien dalam Azure Java SDK mengembalikan lebih dari satu hasil. Azure Java SDK mendefinisikan serangkaian jenis pengembalian yang dapat diterima dalam kasus ini untuk memastikan pengalaman pengembang dimaksimalkan melalui konsistensi. Jenis pengembalian yang digunakan adalah PagedIterable untuk API sinkronisasi dan PagedFlux untuk API asinkron. API sedikit berbeda karena kasus penggunaannya yang berbeda, tetapi secara konseptual API memiliki persyaratan yang sama:

  • Memungkinkan untuk melakukan iterasi dengan mudah atas setiap elemen dalam koleksi secara individual, mengabaikan kebutuhan untuk paginasi manual atau pelacakan token kelanjutan. PagedIterable dan PagedFlux mempermudah tugas dengan mengulangi respons yang dinomori dan dideserialisasi menjadi T jenis tertentu. PagedIterable mengimplementasikan antarmuka Iterable, dan menawarkan API untuk menerima Stream, sementara PagedFlux menyediakan Flux. Dalam semua kasus, tindakan paginasi bersifat transparan, dan iterasi berlanjut sementara masih ada hasil berulang.

  • Memungkinkan untuk melakukan iterasi secara eksplisit halaman demi halaman. Melakukan hal tersebut memungkinkan Anda memahami lebih jelas kapan permintaan dibuat, dan memungkinkan Anda mengakses informasi respons per halaman. PagedIterable dan PagedFlux memiliki metode yang akan mengembalikan jenis yang sesuai untuk iterasi berdasarkan halaman, bukan oleh elemen individu.

Artikel ini terbagi antara API sinkron dan asinkron Java Azure SDK. Anda akan melihat API iterasi sinkron saat bekerja dengan klien sinkron, dan API iterasi asinkron saat Anda bekerja dengan klien asinkron.

Paginasi dan iterasi sinkron

Bagian ini membahas API sinkron.

Iterasi atas elemen individu

Seperti yang telah diketahui, kasus penggunaan yang paling umum adalah untuk melakukan iterasi atas setiap elemen secara individual, bukan per halaman. Contoh kode berikut menunjukkan bagaimana API PagedIterable memungkinkan Anda menggunakan gaya iterasi yang Anda sukai untuk menerapkan fungsi ini.

Tambahkan pengulangan “for-each”

Karena PagedIterable mengimplementasikan Iterable, Anda dapat melakukan iterasi melalui elemen seperti yang ditunjukkan dalam contoh berikut:

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

Gunakan Stream

Karena PagedIterable memiliki metode stream() yang ditentukan di atasnya, Anda dapat memanggilnya untuk menggunakan API Java Stream standar, seperti yang ditunjukkan pada contoh berikut:

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

Gunakan Iterator

Karena PagedIterable mengimplementasikan Iterable, ia juga memiliki metode iterator() untuk memungkinkan gaya pemrograman iterator Java, seperti yang ditunjukkan dalam contoh berikut:

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

Lakukan iterasi di atas halaman

Ketika bekerja dengan halaman individual, Anda dapat melakukan iterasi per halaman, misalnya ketika Anda membutuhkan informasi respons HTTP, atau ketika token penerusan penting untuk mempertahankan riwayat iterasi. Terlepas dari apakah Anda melakukan iterasi berdasarkan halaman atau setiap item, tidak ada perbedaan dalam performa atau jumlah panggilan yang dilakukan ke layanan. Implementasi yang mendasari memuat halaman berikutnya sesuai permintaan, dan jika Anda berhenti berlangganan PagedFlux kapan saja, tidak akan ada panggilan lebih lanjut ke layanan.

Tambahkan pengulangan “for-each”

Ketika Anda memanggil listSecrets(), Anda akan mendapatkan PagedIterable, yang memiliki API iterableByPage(). API ini memproduksi Iterable<PagedResponse<Secret>>, bukan Iterable<Secret>. PagedResponse menyediakan metadata respons dan akses ke token penerusan, seperti yang ditunjukkan dalam contoh berikut:

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

Ada juga iterableByPage kelebihan muatan yang menerima token penerusan. Anda dapat memanggil kelebihan muatan ini ketika ingin kembali ke titik iterasi yang sama di lain waktu.

Gunakan Stream

Contoh berikut menunjukkan cara metode streamByPage() melakukan operasi yang sama seperti yang ditunjukkan di atas. API ini juga memiliki kelebihan muatan token penerusan untuk kembali ke titik iterasi yang sama di lain waktu.

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

Mengamati halaman dan elemen individual secara asinkron

Bagian ini membahas API asinkron. Dalam API asinkron, panggilan jaringan terjadi di utas yang berbeda dari utas utama yang memanggil subscribe(). Artinya, utas utama dapat berakhir sebelum hasilnya tersedia. Keputusan Anda untuk memastikan bahwa aplikasi tidak keluar sebelum operasi asinkron memiliki waktu untuk selesai.

Amati elemen individual

Contoh berikut menunjukkan cara API PagedFlux memungkinkan Anda mengamati elemen individual secara asinkron. Ada berbagai cara untuk berlangganan jenis Flux. Untuk informasi lebih lanjut, lihat Cara Sederhana untuk Membuat Flux atau Mono dan Berlangganan di dalam Panduan Referensi Reaktor 3. Contoh ini adalah satu variasi di mana ada tiga ekspresi lambda, masing-masing untuk konsumen, konsumen kesalahan, dan konsumen lengkap. Memiliki ketiganya merupakan hal yang bagus, tetapi dalam beberapa kasus, Anda hanya perlu memiliki konsumen, dan mungkin konsumen kesalahan.

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

Amati halaman

Contoh berikut menunjukkan cara API PagedFlux memungkinkan Anda mengamati setiap halaman secara asinkron, sekali lagi dengan menggunakan API byPage() dan dengan menyediakan konsumen, konsumen kesalahan, dan konsumen lengkap.

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

Langkah berikutnya

Sekarang setelah Anda terbiasa dengan paginasi dan iterasi di Azure SDK for Java, pertimbangkan untuk meninjau Operasi yang sudah berjalan lama di Azure SDK for Java. Operasi yang sudah berjalan lama adalah operasi yang berjalan untuk durasi yang lebih lama daripada kebanyakan permintaan HTTP normal, biasanya karena operasi tersebut memerlukan beberapa upaya di sisi server.