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.

Operasi berjalan lama sinkron

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:

1. waitForCompletion(Duration): tunggu hingga operasi berjalan lama selesai, untuk durasi batas waktu yang diberikan.
2. waitUntil(LongRunningOperationStatus): tunggu sampai status operasi berjalan lama yang diberikan diterima.
3. waitUntil(LongRunningOperationStatus, Duration): tunggu sampai status operasi berjalan lama yang diberikan diterima, atau sampai durasi batas waktu yang diberikan kedaluwarsa.

Operasi berjalan lama asinkron

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.

Langkah berikutnya

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.