Mengonfigurasi perutean, batas, dan percobaan ulang antrean

Dengan Cloud Tasks, Anda dapat mengelola eksekusi tugas dengan menentukan pemilihan rute tingkat antrean , batas frekuensi pengiriman, dan perilaku percobaan ulang. Anda dapat mengonfigurasi setelan ini saat membuat antrean atau memperbarui antrean yang ada. Flag konfigurasi yang digunakan oleh gcloud tasks queues create atau gcloud tasks queues update sama.

Mengonfigurasi autentikasi di tingkat antrean akan menggantikan autentikasi tingkat tugas. Untuk mengetahui informasi selengkapnya, lihat Menggunakan tugas target HTTP dengan token autentikasi.

Mengonfigurasi pemilihan rute tingkat antrean

Mengonfigurasi pemilihan rute di tingkat antrean akan menggantikan pemilihan rute yang ditetapkan di tingkat tugas. Hal ini berguna jika Anda ingin menggunakan Cloud Tasks sebagai buffer di depan layanan target, atau jika Anda perlu mengubah pemilihan rute untuk semua tugas dalam antrean.

Pemilihan rute tingkat antrean berlaku untuk:

• Tugas yang ada dalam antrean
• Tugas yang ditambahkan ke antrean setelah pemilihan rute tingkat antrean ditetapkan

Batasan

Pemilihan rute tingkat antrean tidak kompatibel dengan kunci enkripsi yang dikelola pelanggan (CMEK) Cloud Key Management Service (Cloud KMS). Jika CMEK diaktifkan, Anda tidak dapat melakukan hal berikut:

• Membuat tugas di antrean yang memiliki pemilihan rute tingkat antrean
• Menerapkan pemilihan rute tingkat antrean

Mengonfigurasi pemilihan rute tingkat antrean untuk tugas HTTP

Anda dapat mengonfigurasi antrean untuk menggantikan pemilihan rute tingkat tugas saat membuat antrean atau saat memperbarui antrean. Untuk mengonfigurasi pemilihan rute tingkat antrean, tetapkan parameter antrean uriOverride ke rute pilihan Anda.

Jika Anda menerapkan pemilihan rute tingkat antrean sebagai pembaruan ke antrean yang ada, jeda antrean sebelum menerapkan perubahan dan tunggu satu menit setelah menerapkan perubahan untuk melanjutkan antrean.

1. Jeda antrean dengan menjalankan perintah berikut:

     gcloud tasks queues pause QUEUE_ID
     

   Ganti QUEUE_ID dengan ID antrean Anda.

2. Perbarui atau hapus pemilihan rute tingkat antrean.

   • Untuk memperbarui pemilihan rute tingkat antrean, tetapkan uriOverride parameter ke rute yang diperbarui.

   • Untuk menghapus pemilihan rute tingkat antrean menggunakan REST atau RPC API:

     • REST API: Kirim permintaan patch untuk antrean dengan payload kosong dan parameter updateMask ditetapkan ke httpTarget.

     • RPC API: Kirim updateQueueRequest untuk antrean dengan payload kosong dan parameter update_mask ditetapkan ke http_target.

   Contoh berikut menggunakan REST API untuk memperbarui host yang dirutekan ke tugas:

   curl -X PATCH -d @- -i \
     -H "Authorization: Bearer ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID?updateMask=httpTarget.uriOverride" << EOF
   {
     "httpTarget": {"uriOverride":{"host":"NEW_HOST"}}
   }
   EOF
   

   Ganti kode berikut:

   • ACCESS_TOKEN: token akses Anda. Anda bisa mendapatkannya dengan menjalankan perintah berikut di terminal:

     gcloud auth application-default login
     gcloud auth application-default print-access-token

   • PROJECT_ID: ID project Google Cloud Anda. Anda bisa mendapatkannya dengan menjalankan perintah berikut di terminal:

     gcloud config get-value project

   • LOCATION: lokasi antrean Anda.

   • NEW_HOST: host baru yang ingin Anda gunakan untuk merutekan antrean.

3. Tunggu satu menit.

   Konfigurasi baru dapat memerlukan waktu hingga satu menit untuk diterapkan. Menunggu untuk melanjutkan antrean akan membantu mencegah tugas dikirim dengan konfigurasi lama.

4. Lanjutkan antrean dengan menjalankan perintah berikut:

   gcloud tasks queues resume QUEUE_ID

Mengonfigurasi pemilihan rute tingkat antrean untuk tugas App Engine

Untuk mengonfigurasi pemilihan rute tingkat antrean untuk tugas App Engine, tetapkan parameter appEngineRoutingOverride antrean ke layanan dan versi App Engine pilihan Anda.

1. Siapkan pemilihan rute tingkat antrean dan ganti pemilihan rute tingkat tugas:

   gcloud tasks queues update QUEUE_ID \
       --routing-override=service:SERVICE,version:VERSION

   Ganti kode berikut:

   • QUEUE_ID: ID antrean (nama pendeknya).
   • SERVICE: layanan pekerja App Engine yang bertanggung jawab untuk penanganan tugas.
   • VERSION: versi aplikasi.

   Misalnya, jika Anda menyiapkan layanan pekerja untuk menangani semua tugas dalam antrean, Anda dapat merutekan ke layanan tersebut dan versi default:

   gcloud tasks queues update QUEUE_ID \
       --routing-override=service:SERVICE

2. Verifikasi bahwa antrean Anda berhasil dikonfigurasi dengan menjalankan perintah berikut:

   gcloud tasks queues describe QUEUE_ID --location=LOCATION

   Ganti LOCATION dengan lokasi antrean.

   Outputnya akan mirip dengan berikut ini:

   appEngineRoutingOverride:
     host: SERVICE.PROJECT_ID.appspot.com
     service: SERVICE
   name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
   rateLimits:
     maxBurstSize: 100
     maxConcurrentDispatches: 1000
     maxDispatchesPerSecond: 500.0
   retryConfig:
     maxAttempts: 100
     maxBackoff: 3600s
     maxDoublings: 16
     minBackoff: 0.100s
   state: RUNNING

3. Untuk menghapus pemilihan rute tingkat antrean, jalankan perintah berikut:

   gcloud tasks queues update QUEUE_ID \
       --clear-routing-override

   Saat pemilihan rute tingkat antrean dihapus, pemilihan rute tingkat tugas akan diterapkan ke tugas dalam antrean dan tugas yang ditambahkan ke antrean di masa mendatang.

Menentukan batas frekuensi

Batas frekuensi menentukan frekuensi maksimum tugas yang dapat dikirim oleh antrean, terlepas dari apakah pengiriman adalah upaya tugas pertama atau percobaan ulang.

1. Tetapkan frekuensi maksimum dan jumlah tugas serentak yang dapat dikirim oleh antrean dengan menjalankan perintah berikut:

   gcloud tasks queues update QUEUE_ID \
       --max-dispatches-per-second=DISPATCH_RATE \
       --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

   Ganti kode berikut:

   • QUEUE_ID: ID antrean (nama pendeknya).
   • DISPATCH_RATE: frekuensi pengiriman. Ini adalah frekuensi token dalam bucket diperbarui. Dalam kondisi ketika ada aliran tugas yang relatif stabil, hal ini setara dengan frekuensi tugas dikirim.
   • MAX_CONCURRENT_DISPATCHES: jumlah maksimum tugas dalam antrean yang dapat berjalan sekaligus.

   Misalnya, jika Anda membuat antrean tanpa menetapkan parameter apa pun, Anda dapat memperbarui jumlah maksimum tugas serentak dengan menjalankan perintah berikut:

   gcloud tasks queues update QUEUE_ID \
       --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

2. Verifikasi bahwa antrean Anda berhasil dikonfigurasi dengan menjalankan perintah berikut:

   gcloud tasks queues describe QUEUE_ID --location=LOCATION

   Ganti LOCATION dengan lokasi antrean.

   Outputnya akan mirip dengan berikut ini:

   name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
   rateLimits:
     maxBurstSize: 100
     maxConcurrentDispatches: MAX_CONCURRENT_DISPATCHES
     maxDispatchesPerSecond: 500.0
   retryConfig:
     maxAttempts: 100
     maxBackoff: 3600s
     maxDoublings: 16
     minBackoff: 0.100s
   state: RUNNING

Metode untuk menentukan frekuensi pemrosesan antrean

Anda dapat menentukan frekuensi pemrosesan antrean menggunakan Cloud Tasks API atau dengan mengupload file queue.yaml. Kedua metode tersebut menghasilkan antrean yang menggunakan mekanisme dasar yang sama.

Perhatian: Meskipun kedua metode dapat digunakan untuk membuat antrean, sebaiknya gunakan file queue.yaml atau Cloud Tasks API untuk mengonfigurasi antrean Anda, tetapi tidak keduanya. Untuk mengetahui informasi selengkapnya, lihat Menggunakan Pengelolaan Antrean atau queue.yaml.

Dalam kedua kasus tersebut, antrean menggunakan algoritma token bucket untuk mengontrol frekuensi eksekusi tugas. Setiap antrean bernama memiliki bucket yang menyimpan tokennya.

Setiap kali aplikasi Anda menjalankan sebuah tugas, token akan dihapus dari bucket. Antrean akan terus memproses tugas hingga bucketnya kehabisan token. Sistem akan mengisi ulang bucket dengan token baru secara terus-menerus berdasarkan frekuensi max_dispatches_per_second yang Anda tentukan untuk antrean tersebut. Jika antrean Anda berisi tugas yang akan diproses, dan bucket antrean berisi token, sistem akan memproses tugas sebanyak token yang ada secara bersamaan, hingga nilai max_concurrent_dispatches yang telah Anda tetapkan.

Beban yang tidak merata dapat memungkinkan jumlah token dalam bucket bertambah secara signifikan, yang dapat menyebabkan burst pemrosesan saat terjadi burst permintaan. Dalam hal ini, antrean Anda mungkin mengalami frekuensi pengiriman aktual yang melebihi frekuensi max_dispatches_per_second, yang menghabiskan resource sistem dan bersaing dengan permintaan layanan pengguna. Jika Anda menggunakan antrean untuk mengelola frekuensi pengiriman berdasarkan SLA yang relatif lambat untuk layanan hilir, hal ini dapat menyebabkan error seperti HTTP 429 (Terlalu Banyak Permintaan) atau HTTP 503 (Layanan Tidak Tersedia).

• Saat menggunakan metode Cloud Tasks API, Anda memiliki dua kolom untuk menentukan frekuensi pengiriman antrean:

  • max_dispatches_per_second
  • max_concurrent_dispatches

  Kolom ketiga, max_burst_size, dihitung oleh sistem berdasarkan nilai yang Anda tetapkan untuk max_dispatches_per_second. Untuk mengetahui informasi selengkapnya, lihat pesan RateLimits.

• Saat menggunakan metode queue.yaml, Anda dapat menetapkan ketiga elemen:

  • max_concurrent_requests, yang setara dengan max_concurrent_dispatches
  • rate, yang setara dengan max_dispatches_per_second
  • bucket_size, yang setara dengan max_burst_size

Dalam sebagian besar kasus, penggunaan metode Cloud Tasks API dan membiarkan sistem menetapkan max_burst_size akan menghasilkan frekuensi yang sangat efisien untuk mengelola burst permintaan. Namun, dalam beberapa kasus, terutama saat frekuensi yang diperlukan relatif lambat, menggunakan metode queue.yaml untuk menetapkan bucket_size secara manual ke nilai kecil, atau menetapkan max_concurrent_dispatches ke nilai kecil menggunakan Cloud Tasks API, dapat memberi Anda lebih banyak kontrol.

Menetapkan parameter percobaan ulang

Jika tugas tidak berhasil diselesaikan, Cloud Tasks akan mencoba ulang tugas dengan backoff eksponensial sesuai dengan parameter yang telah Anda tetapkan. Setelah tugas berhasil dieksekusi, tugas akan dihapus dari antrean. Dalam semua kasus, batas retensi tugas maksimum juga berlaku.

Secara opsional, Anda dapat menentukan konfigurasi percobaan ulang tingkat tugas yang akan menggantikan konfigurasi percobaan ulang tingkat antrean untuk tugas tersebut. Untuk mengetahui informasi selengkapnya, lihat Menetapkan parameter percobaan ulang untuk tugas.

Tips: Untuk men-debug parameter percobaan ulang, Anda dapat mencatat kode status untuk setiap pemanggilan tugas menggunakan Cloud Logging dengan antrean dan dengan menetapkan rasio sampling log untuk menentukan bagian operasi yang akan ditulis ke Cloud Logging.

1. Tentukan jumlah maksimum percobaan ulang tugas yang gagal dalam antrean, tetapkan batas waktu untuk upaya percobaan ulang, dan kontrol interval antar-upaya dengan menjalankan perintah berikut:

   gcloud tasks queues update QUEUE_ID \
       --max-attempts=MAX_ATTEMPTS \
       --max-retry-duration=MAX_RETRY_DURATION \
       --min-backoff=MIN_INTERVAL \
       --max-backoff=MAX_INTERVAL \
       --max-doublings=MAX_DOUBLINGS

   Ganti kode berikut:

   • QUEUE_ID: ID antrean (nama pendeknya).
   • MAX_ATTEMPTS: jumlah maksimum upaya untuk tugas, termasuk yang pertama. Untuk mengizinkan percobaan ulang tanpa batas, tetapkan nilai ini ke -1. MAX_RETRY_DURATION tetap berlaku meskipun MAX_ATTEMPTS tercapai atau ditetapkan ke -1.
   • MAX_RETRY_DURATION: jumlah waktu maksimum untuk mencoba ulang tugas yang gagal, yang diukur dari saat tugas pertama kali dicoba. Nilai harus berupa string yang diakhiri dengan "s", seperti 5s. Untuk menentukan durasi tanpa batas, tetapkan nilai ini ke 0s. MAX_ATTEMPTS tetap berlaku meskipun MAX_RETRY_DURATION tercapai atau ditetapkan ke 0s.
   Catatan: Jika Anda menentukan upaya tanpa batas (MAX_ATTEMPTS adalah -1) dan durasi tanpa batas (MAX_RETRY_DURATION adalah 0s), tugas akan dicoba ulang hingga mencapai batas retensi tugas maksimum. Jika tidak, Cloud Tasks akan berhenti mencoba ulang hanya setelah kedua kondisi terpenuhi atau tugas berhasil. Jika tugas telah dicoba MAX_ATTEMPTS kali dan waktu MAX_RETRY_DURATION telah berlalu, tidak ada upaya lebih lanjut yang dilakukan, dan tugas akan dihapus.
   • MIN_INTERVAL: jumlah waktu minimum untuk menunggu di antara upaya percobaan ulang. Nilai harus berupa string yang diakhiri dengan "s", seperti 5s.
   • MAX_INTERVAL: jumlah waktu maksimum untuk menunggu di antara upaya percobaan ulang. Nilai harus berupa string yang diakhiri dengan "s", seperti 5s.

   • MAX_DOUBLINGS: jumlah maksimum interval antara percobaan ulang tugas yang gagal akan digandakan sebelum peningkatan menjadi konstan. Interval percobaan ulang tugas dimulai dari MIN_INTERVAL, lalu digandakan MAX_DOUBLINGS kali, lalu meningkat secara linear, dan akhirnya dicoba ulang pada interval MAX_INTERVAL hingga MAX_ATTEMPTS kali.

     Misalnya, jika MIN_INTERVAL adalah 10s, MAX_INTERVAL adalah 300s, dan MAX_DOUBLINGS adalah 3, interval percobaan ulang akan digandakan 3 kali, meningkat secara linear sebesar 2^3 * 10 detik, lalu dicoba ulang pada interval MAX_INTERVAL hingga tugas telah dicoba MAX_ATTEMPTS kali: 10 detik, 20 detik, 40 detik, 80 detik, 160 detik, 240 detik, 300 detik, 300 detik, dan seterusnya.

Untuk mengetahui detail parameter selengkapnya, lihat RetryConfig setelan untuk resource Queue.

1. Verifikasi bahwa antrean Anda berhasil dikonfigurasi dengan menjalankan perintah berikut:

   gcloud tasks queues describe QUEUE_ID --location=LOCATION

   Ganti LOCATION dengan lokasi antrean.

   Output harus berisi parameter percobaan ulang yang Anda tetapkan.

Langkah berikutnya

• Pelajari cara membuat tugas target HTTP.
• Pelajari cara membuat tugas App Engine.
• Pelajari pengelolaan antrean lebih lanjut di referensi RPC API.
• Pelajari pengelolaan antrean lebih lanjut di referensi REST API.