Mengelola operasi yang berjalan lama

Google Cloud API menggunakan operasi yang berjalan lama (LRO) untuk panggilan yang diperkirakan memerlukan waktu yang cukup lama untuk diselesaikan (misalnya, menyediakan instance Compute Engine atau menginisialisasi pipeline Dataflow). API ini tidak mempertahankan koneksi aktif yang berjalan lama atau memblokir saat tugas berjalan. Untuk API LRO, Library Klien Cloud untuk Java menampilkan future agar Anda dapat memeriksanya nanti.

Menentukan apakah API adalah LRO

Ada dua cara utama untuk menentukan apakah API adalah LRO:

• API LRO memiliki akhiran Async (misalnya, createClusterAsync) atau OperationCallable (misalnya, createClusterOperationCallable).
• API LRO menampilkan OperationFuture atau OperationCallable.

Cuplikan berikut menunjukkan dua variasi, menggunakan Java-Dataproc sebagai contoh:

// Async suffix (#1) returns OperationFuture (#2)
public final OperationFuture<Cluster, ClusterOperationMetadata> createClusterAsync(CreateClusterRequest request)

// OperationCallable suffix (#1) returns OperationCallable (#2)
public final OperationCallable<CreateClusterRequest, Cluster, ClusterOperationMetadata> createClusterOperationCallable()

Ini adalah dua variasi untuk API yang sama, bukan dua API yang berbeda (kedua panggilan membuat cluster Dataproc). Varian Async direkomendasikan.

Alur umum LRO

API LRO pada dasarnya adalah panggilan permintaan awal yang diikuti dengan serangkaian panggilan polling kecil. Panggilan awal mengirimkan permintaan dan membuat "operasi" di server. Semua panggilan polling berikutnya ke server melacak status operasi. Jika operasi selesai, respons akan ditampilkan. Jika tidak, status tidak selesai akan ditampilkan dan library klien akan menentukan apakah akan melakukan polling lagi.

Secara default, klien menangani logika polling, dan Anda tidak perlu mengonfigurasi mekanisme polling kecuali jika Anda memiliki persyaratan tertentu.

Dari perspektif Anda, panggilan berjalan di latar belakang hingga respons diterima. Panggilan polling dan konfigurasi waktu tunggu memiliki nilai default yang telah dikonfigurasi sebelumnya oleh tim layanan berdasarkan perkiraan waktu untuk API mereka. Konfigurasi ini mengontrol banyak faktor, seperti seberapa sering melakukan polling dan berapa lama harus menunggu sebelum berhenti.

Library Klien Cloud untuk Java menyediakan antarmuka untuk berinteraksi dengan LRO menggunakan OperationFuture.

Cuplikan berikut menunjukkan cara memanggil operasi dan menunggu respons, menggunakan Java-Dataproc sebagai contoh:

try (ClusterControllerClient clusterControllerClient = ClusterControllerClient.create()) {
  CreateClusterRequest request =
      CreateClusterRequest.newBuilder().build();
  OperationFuture<Cluster, ClusterOperationMetadata> future =
      clusterControllerClient.createClusterAsync(request);
  // Blocks until there is a response
  Cluster response = future.get();
} catch (CancellationException e) {
  // Exceeded the timeout without the Operation completing.
  // Library is no longer polling for the Operation's status.
}

Nilai LRO default

Anda dapat menemukan nilai default dalam setiap kelas StubSettings klien. Metode initDefaults() menginisialisasi setelan LRO di dalam class Builder bertingkat.

Misalnya, di Java-Aiplatform v3.24.0, panggilan LRO deployModel memiliki parameter default berikut:

OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(5000L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(45000L))
    .setTotalTimeoutDuration(Duration.ofMillis(300000L))
    .setInitialRpcTimeoutDuration(Duration.ZERO) // not used
    .setRpcTimeoutMultiplier(1.0) // not used
    .setMaxRpcTimeoutDuration(Duration.ZERO) // not used
    .build()));

Catatan: LRO tidak menggunakan nilai Waktu Tunggu RPC dan memiliki nilai default (Duration.ZERO untuk waktu tunggu atau 1.0 untuk pengganda).

Pencobaan ulang dan LRO menggunakan class RetrySettings yang sama. Tabel berikut menunjukkan pemetaan antara kolom di dalam RetrySettings dan fungsi LRO:

RetrySettings	Deskripsi
InitialRetryDelay	Penundaan awal sebelum polling pertama.
MaxRetryDelay	Penundaan maksimum antara setiap polling.
RetryDelayMultiplier	Pengganda untuk penundaan percobaan ulang polling di antara polling.
TotalTimeoutDuration	Waktu maksimum yang diizinkan untuk operasi yang berjalan lama.

Kapan harus mengonfigurasi nilai LRO

Kasus penggunaan utama untuk mengonfigurasi nilai LRO secara manual adalah untuk mengubah frekuensi polling karena waktu tunggu LRO habis. Meskipun nilai default dikonfigurasi sebagai perkiraan oleh tim layanan, faktor tertentu dapat menyebabkan waktu tunggu sesekali.

Untuk mengurangi jumlah waktu tunggu, tingkatkan nilai total waktu tunggu. Meningkatkan nilai lainnya juga dapat membantu, dan Anda harus mengujinya untuk memastikan perilaku yang diharapkan.

Cara mengonfigurasi nilai LRO

Untuk mengonfigurasi nilai LRO, buat objek OperationTimedPollAlgorithm dan perbarui algoritma polling untuk LRO tertentu. Cuplikan berikut menggunakan Java-Dataproc sebagai contoh:

ClusterControllerSettings.Builder settingsBuilder = ClusterControllerSettings.newBuilder();
// Create a new OperationTimedPollAlgorithm object
TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(500L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(5000L))
    .setTotalTimeoutDuration(Duration.ofHours(24L))
    .build());
// Set the new polling settings for the specific LRO API 
settingsBuilder.createClusterOperationSettings().setPollingAlgorithm(timedRetryAlgorithm);
ClusterControllerClient clusterControllerClient = ClusterControllerClient.create(settingsBuilder.build());

Konfigurasi ini hanya mengubah nilai LRO untuk RPC createClusterOperation. RPC lainnya di Klien masih menggunakan nilai LRO yang telah dikonfigurasi sebelumnya untuk setiap RPC, kecuali jika juga diubah.

Waktu tunggu LRO

Library terus melakukan polling selama total waktu tunggu belum terlampaui. Jika total waktu tunggu telah terlampaui, library akan menampilkan java.util.concurrent.CancellationException dengan pesan "Task was cancelled".

CancellationException tidak berarti bahwa tugas backend Google Cloud dibatalkan. Pengecualian ini ditampilkan dari library klien saat panggilan telah melampaui total waktu tunggu dan belum menerima respons. Meskipun tugas selesai segera setelah waktu tunggu habis, respons tidak akan dilihat oleh library klien.