Operasi berjalan lama di Azure SDK untuk Java
Artikel ini memberikan ringkasan tentang penggunaan operasi berjalan lama dengan Azure SDK untuk Java.
Operasi tertentu di Azure membutuhkan waktu yang lama untuk diselesaikan. Operasi ini berada di luar gaya HTTP standar dari alur permintaan / respons cepat. Misalnya, menyalin data dari URL sumber ke blob Storage, atau melatih model untuk mengenali formulir, adalah operasi yang memakan waktu beberapa detik hingga beberapa menit. Operasi semacam itu disebut sebagai Long-Running Operations, dan sering disingkat sebagai 'LRO'. LRO memakan waktu beberapa detik, menit, jam, hari, atau lebih lama untuk diselesaikan, tergantung pada operasi yang diminta dan proses yang harus dilakukan di sisi server.
Di pustaka klien Java untuk Azure, ada konvensi bahwa semua operasi berjalan lama dimulai dengan prefiks begin
. Prefiks ini menunjukkan bahwa operasi ini berjalan lama, dan cara interaksi dengan operasi ini sedikit berbeda dari alur permintaan / respons biasa. Seiring dengan prefiks begin
, jenis pengembalian dari operasi juga berbeda dari biasanya, untuk mengaktifkan berbagai fungsi operasi berjalan lama. Seperti kebanyakan di Azure SDK untuk Java, ada API sinkron dan asinkron untuk operasi berjalan lama:
- Dalam klien sinkron, operasi berjalan lama akan mengembalikan instans
SyncPoller
. - Dalam klien asinkron, operasi berjalan lama akan mengembalikan instans
PollerFlux
.
Baik SyncPoller
dan PollerFlux
merupakan abstraksi sisi klien yang dimaksudkan untuk menyederhanakan interaksi dengan operasi sisi server yang berjalan lama. Sisa artikel ini menguraikan praktik terbaik saat bekerja dengan jenis ini.
Memanggil API yang mengembalikan SyncPoller
akan segera memulai operasi berjalan lama. API akan segera mengembalikan SyncPoller
, memungkinkan Anda memantau kemajuan operasi berjalan lama dan mengambil hasil akhir. Contoh berikut menunjukkan cara memantau kemajuan operasi berjalan lama menggunakan SyncPoller
.
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());
Contoh ini menggunakan metode poll()
di SyncPoller
untuk mengambil informasi tentang kemajuan operasi berjalan lama. Kode ini mencetak status ke konsol, tetapi implementasi yang lebih baik akan membuat keputusan yang relevan berdasarkan status ini.
Metode getRetryAfter()
mengembalikan informasi tentang lama menunggu sebelum jajak pendapat berikutnya. Sebagian besar operasi Azure yang berjalan lama mengembalikan penundaan polling sebagai bagian dari respons HTTP mereka (yaitu, header retry-after
yang umum digunakan). Jika respons tidak berisi penundaan polling, maka metode getRetryAfter()
mengembalikan durasi yang diberikan pada saat memanggil operasi berjalan lama.
Contoh di atas menggunakan perulangan do..while
untuk melakukan polling secara berulang sampai operasi berjalan lama selesai. Jika tidak tertarik dengan hasil perantara ini, Anda dapat menelepon waitForCompletion()
. Panggilan akan memblokir utas saat ini hingga operasi berjalan lama selesai dan mengembalikan respons polling terakhir:
PollResponse<UploadBlobProgress> response = poller.waitForCompletion();
Jika respons polling terakhir menunjukkan bahwa operasi berjalan lama telah berhasil diselesaikan, Anda dapat mengambil hasil akhir menggunakan getFinalResult()
:
if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
UploadedBlobProperties result = poller.getFinalResult();
}
API lain yang berguna di SyncPoller
meliputi:
waitForCompletion(Duration)
: tunggu hingga operasi berjalan lama selesai, untuk durasi batas waktu yang diberikan.waitUntil(LongRunningOperationStatus)
: tunggu sampai status operasi berjalan lama yang diberikan diterima.waitUntil(LongRunningOperationStatus, Duration)
: tunggu sampai status operasi berjalan lama yang diberikan diterima, atau sampai durasi batas waktu yang diberikan kedaluwarsa.
Contoh di bawah ini menunjukkan bagaimana PollerFlux
memungkinkan Anda mengamati operasi berjalan lama. 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.
API asinkron segera mengembalikan PollerFlux
, tetapi operasi berjalan lama tidak akan dimulai sampai Anda berlangganan PollerFlux
. Proses ini merupakan cara seluruh API berbasis Flux
beroperasi. Contoh berikut menunjukkan operasi berjalan lama asinkron:
asyncClient.beginUploadFromUri(...)
.subscribe(response -> System.out.println("Status of long running upload operation: " + response.getStatus()));
Dalam contoh berikut, Anda akan mendapatkan pembaruan status terputus-putus pada operasi berjalan lama. Anda dapat menggunakan pembaruan ini untuk menentukan apakah operasi berjalan lama masih beroperasi dengan cara yang diharapkan. Contoh ini mencetak status ke konsol, tetapi implementasi yang lebih baik akan membuat keputusan penanganan kesalahan yang relevan berdasarkan status ini.
Jika Anda tidak tertarik dengan pembaruan status menengah dan ingin mendapatkan pemberitahuan tentang hasil akhir nanti, Anda dapat menggunakan kode yang mirip dengan contoh berikut:
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());
Dalam kode ini, Anda mengambil hasil akhir dari operasi berjalan lama dengan memanggil last()
. Panggilan ini memberi tahu PollerFlux
bahwa Anda ingin menunggu semua polling selesai, di mana operasi berjalan lama telah mencapai keadaan terminal, dan dapat memeriksa status untuk menentukan hasilnya. Jika pengisi polling menunjukkan bahwa operasi berjalan lama telah berhasil diselesaikan, Anda dapat mengambil hasil akhir dan meneruskannya ke konsumen dalam panggilan berlangganan.
Sekarang setelah mengenali API berjalan lama di Azure SDK untuk Java, lihat Mengonfigurasikan proksi di Azure SDK untuk Java untuk mempelajari lebih lanjut cara menyesuaikan klien HTTP.