Bagikan melalui

Operasi yang berlangsung lama di SDK Azure untuk Java

Artikel ini menyediakan gambaran umum penggunaan operasi jangka panjang dengan Azure SDK untuk Java.

Operasi tertentu di Azure mungkin memerlukan waktu yang lama untuk diselesaikan. Operasi ini berada di luar gaya HTTP standar permintaan cepat/alur respons. Misalnya, menyalin data dari URL sumber ke blob Storage, atau melatih model untuk mengenali formulir, adalah operasi yang mungkin memakan waktu beberapa detik hingga beberapa menit. Operasi tersebut disebut sebagai Operasi Long-Running, dan sering disingkat sebagai 'LRO'. LRO mungkin membutuhkan waktu detik, menit, jam, hari, atau lebih lama untuk diselesaikan, tergantung pada operasi yang diminta dan proses yang harus dilakukan di sisi server.

Di perpustakaan klien Java untuk Azure, ada konvensi bahwa semua operasi jangka panjang dimulai dengan awalan begin. Awalan ini menunjukkan bahwa operasi ini berjalan lama, dan bahwa sarana interaksi dengan operasi ini sedikit berbeda dengan alur permintaan / respons biasa. Seiring dengan awalan begin, tipe pengembalian dari operasi juga berbeda dengan biasanya, untuk memungkinkan cakupan penuh dari fungsi operasi yang berlangsung lama. Seperti kebanyakan hal di Azure SDK untuk Java, ada API sinkron dan asinkron untuk operasi jangka panjang:

  • Pada klien sinkron, operasi jangka panjang akan menghasilkan instans SyncPoller.
  • Pada klien asinkron, operasi jangka panjang akan mengembalikan sebuah objek PollerFlux.

Keduanya 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.

Operasi jangka panjang yang sinkron

Memanggil API apa pun yang mengembalikan SyncPoller akan segera memulai operasi jangka panjang. API akan segera mengembalikan SyncPoller , memungkinkan Anda memantau kemajuan operasi yang berjalan lama dan mengambil hasil akhir. Contoh berikut menunjukkan cara memantau kemajuan operasi yang 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() pada SyncPoller untuk mengambil informasi tentang kemajuan operasi yang memakan waktu 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 berapa lama harus menunggu sebelum melakukan polling berikutnya. Sebagian besar operasi jangka panjang Azure mengembalikan penundaan polling sebagai bagian dari respons HTTP mereka (yaitu, header yang umum digunakan retry-after ). Jika respons tidak berisi penundaan jajak pendapat, maka metode getRetryAfter() mengembalikan durasi yang diberikan pada saat memanggil operasi yang berjalan lama.

Contoh di atas menggunakan perulangan do..while untuk melakukan polling berulang kali hingga operasi jangka panjang selesai. Jika Anda tidak tertarik dengan hasil menengah ini, Anda dapat memanggil waitForCompletion(). Panggilan ini akan memblokir utas yang sedang berjalan hingga operasi jangka panjang selesai dan mengembalikan respons survei terakhir.

PollResponse<UploadBlobProgress> response = poller.waitForCompletion();

Jika respons polling terakhir menunjukkan bahwa operasi jangka panjang telah berhasil diselesaikan, Anda dapat mengambil hasil akhir menggunakan getFinalResult():

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    UploadedBlobProperties result = poller.getFinalResult();
}

API berguna lainnya termasuk SyncPoller :

  1. waitForCompletion(Duration): tunggu hingga operasi jangka panjang selesai, selama durasi batas waktu yang diberikan.
  2. waitUntil(LongRunningOperationStatus): tunggu hingga status operasi jangka panjang yang diberikan diterima.
  3. waitUntil(LongRunningOperationStatus, Duration): tunggu hingga status operasi jangka panjang yang diberikan diterima, atau hingga durasi batas waktu yang diberikan kedaluwarsa.

Operasi jangka panjang asinkron

Contoh di bawah ini menunjukkan bagaimana PollerFlux memungkinkan Anda mengamati operasi yang 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. Terserah Anda untuk memastikan bahwa aplikasi tidak keluar sebelum operasi asinkron memiliki waktu untuk diselesaikan.

API asinkron segera mengembalikan PollerFlux , tetapi operasi jangka panjang itu sendiri tidak akan dimulai sampai Anda berlangganan ke PollerFlux. Proses ini adalah cara semua API berbasis Flux beroperasi. Contoh berikut menunjukkan operasi asinkron yang berjalan lama:

asyncClient.beginUploadFromUri(...)
    .subscribe(response -> System.out.println("Status of long running upload operation: " + response.getStatus()));

Dalam contoh berikut, Anda akan mendapatkan pembaruan status terputus-terputus pada operasi yang berjalan lama. Anda dapat menggunakan pembaruan ini untuk menentukan apakah operasi jangka panjang 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 hanya ingin mendapatkan pemberitahuan tentang hasil akhir saat tiba, 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 yang berjalan lama dengan memanggil last(). Panggilan ini memberi tahu PollerFlux bahwa Anda ingin menunggu hingga semua proses polling selesai, saat mana operasi yang berlangsung lama telah mencapai status akhir, dan Anda dapat memeriksa statusnya untuk menentukan hasilnya. Jika poller menunjukkan bahwa operasi jangka panjang telah berhasil diselesaikan, Anda dapat mengambil hasil akhir dan meneruskannya ke konsumen dalam panggilan berlangganan.

Langkah selanjutnya

Sekarang setelah Anda terbiasa dengan API yang berjalan lama di Azure SDK untuk Java, lihat Mengonfigurasi proksi di Azure SDK for Java untuk mempelajari cara menyesuaikan klien HTTP lebih lanjut.

  • Last updated on