Operasi yang berlangsung lama di SDK Azure untuk Java

Artikel ini menjelaskan operasi jangka panjang di Azure SDK untuk Java dan menunjukkan cara melacak kemajuan dan mengambil hasil akhir dengan logika polling manual yang lebih sedikit.

Operasi tertentu pada Azure membutuhkan waktu lama untuk diselesaikan. Operasi ini tidak mengikuti gaya HTTP standar permintaan cepat dan 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 ini adalah operasi jangka panjang, 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 server.

Di pustaka klien Java untuk Azure, semua operasi yang berjalan lama dimulai dengan awalanbegin. Awalan ini menunjukkan bahwa operasi berjalan lama, dan bahwa cara interaksi dengan operasi ini sedikit berbeda dari permintaan dan alur 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 dalam Azure SDK untuk Java, operasi jangka panjang memiliki API sinkron dan asinkron:

  • Pada klien sinkron, operasi yang berjalan lama mengembalikan instance SyncPoller.
  • Dalam klien asinkron, operasi yang berjalan lama mengembalikan sebuah instans PollerFlux.

Keduanya SyncPoller dan PollerFlux merupakan abstraksi sisi klien yang 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

Saat Anda memanggil API yang mengembalikan SyncPoller, operasi jangka panjang segera dimulai. API segera mengembalikan SyncPoller , sehingga Anda dapat memantau kemajuan operasi jangka panjang dan mendapatkan hasil akhir. Contoh berikut menunjukkan cara memantau kemajuan operasi yang berjalan lama dengan 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 memperoleh informasi tentang kemajuan operasi yang berjalan dalam waktu lama. Kode ini mencetak status ke konsol, tetapi implementasi yang lebih baik 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 polling, getRetryAfter() metode mengembalikan durasi yang diberikan saat memanggil operasi yang berjalan lama.

Contoh sebelumnya menggunakan perulangan do..while untuk berulang kali melakukan polling hingga operasi yang berjalan lama selesai. Jika Anda tidak tertarik dengan hasil menengah ini, Anda dapat memanggil waitForCompletion(). Panggilan ini menangguhkan utas saat ini hingga operasi yang berjalan lama selesai dan mengembalikan respons polling terakhir:

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

Jika respons polling terakhir menunjukkan bahwa operasi jangka panjang berhasil diselesaikan, Anda bisa mendapatkan hasil akhir dengan menggunakan getFinalResult():

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

API berguna lainnya termasuk SyncPoller :

  • waitForCompletion(Duration): tunggu hingga operasi yang berjalan lama selesai, dalam durasi batas waktu yang diberikan.
  • waitUntil(LongRunningOperationStatus): tunggu hingga status operasi jangka panjang yang diberikan diterima.
  • 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 berikut menunjukkan bagaimana PollerFlux memungkinkan Anda mengamati operasi yang berlangsung lama. Dalam API asinkron, panggilan jaringan terjadi di utas yang berbeda dari utas utama yang memanggil subscribe(). Arsitektur ini berarti bahwa utas utama mungkin berakhir sebelum hasilnya tersedia. Anda perlu memastikan bahwa aplikasi tidak keluar sebelum operasi asinkron selesai.

API asinkron segera mengembalikan PollerFlux , tetapi operasi jangka panjang itu sendiri tidak 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 menerima pembaruan status secara berkala pada operasi berdurasi 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, gunakan 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 menunjukkan kepada PollerFlux bahwa Anda ingin menunggu hingga semua proses polling selesai. Pada titik ini, operasi jangka panjang mencapai status terminal, dan Anda dapat memeriksa statusnya untuk menentukan hasilnya. Jika poller menunjukkan bahwa operasi jangka panjang 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