Referensi queue.yaml

ID wilayah

REGION_ID adalah kode singkat yang ditetapkan Google berdasarkan region yang Anda pilih saat membuat aplikasi. Kode ini tidak sesuai dengan negara atau provinsi, meskipun beberapa ID region mungkin tampak mirip dengan kode negara dan provinsi yang umum digunakan. Untuk aplikasi yang dibuat setelah Februari 2020, REGION_ID.r disertakan dalam URL App Engine. Untuk aplikasi lama yang dibuat sebelum tanggal tersebut, ID region bersifat opsional dalam URL.

Pelajari ID region lebih lanjut.

File konfigurasi queue.yaml digunakan untuk membuat dan mengonfigurasi hampir semua task queue (push atau pull) yang digunakan aplikasi Anda. Semua aplikasi App Engine dilengkapi dengan push queue yang telah dikonfigurasi secara otomatis bernama default. Meskipun Anda tidak membuat queue default sendiri, Anda dapat menambahkan queue lain atau mengubah konfigurasi queuedefault menggunakan file queue.yaml.

Untuk aplikasi Java, file ini disimpan di mana saja dalam direktori kode sumber.

Untuk mengonfigurasi push queue, Anda dapat menggunakan metode queue.yaml atau Pengelolaan Queue dari Cloud Tasks, tetapi tidak keduanya secara bersamaan. Mencampur metode upload queue.yaml dengan metode Pengelolaan Queue dapat memberikan hasil yang tidak terduga dan tidak direkomendasikan.

Untuk mengonfigurasi pull queue, Anda harus menggunakan file queue.yaml.

Contoh

Berikut contoh dasar yang menentukan antrean bernama dan mengganti kecepatan pemrosesan default:

queue:
- name: my-push-queue
  rate: 1/s

Berikut adalah contoh yang lebih kompleks dari konfigurasi queue.yaml yang menunjukkan penyiapan jumlah percobaan tugas dan mengubah kecepatan pemrosesan default.

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

Sintaks

File queue.yaml adalah file YAML yang perintah root-nya adalah queue. Perintah ini berisi nol atau beberapa antrean yang diberi nama. Setiap definisi antrean dapat menentukan elemen berikut:

Elemen Deskripsi
<bucket-size> (push queue)

Opsional. Task queue menggunakan algoritma token bucket untuk mengontrol laju eksekusi tugas. Setiap antrean bernama memiliki token bucket yang menyimpan token, hingga jumlah maksimum yang ditentukan oleh nilai bucket_size. Setiap kali aplikasi Anda menjalankan suatu tugas, satu token akan dihapus dari bucket. Anda akan terus memproses tugas dalam antrean sampai bucket antrean kehabisan token. App Engine mengisi ulang bucket dengan token baru secara terus-menerus berdasarkan laju yang Anda tentukan untuk antrean tersebut.

Ukuran bucket membatasi seberapa cepat antrean diproses saat banyak tugas dalam antrean dan kapasitasnya tinggi. Nilai maksimum untuk ukuran bucket adalah 500. Hal ini memungkinkan Anda memperoleh kecepatan yang tinggi sehingga pemrosesan dimulai sesaat setelah tugas diantrekan, tetapi tetap membatasi penggunaan resource saat banyak tugas diantrekan dalam waktu singkat.

Jika Anda tidak menentukan bucket_size untuk antrean, nilai defaultnya adalah 5. Sebaiknya tetapkan ke nilai yang lebih besar karena ukuran defaultnya mungkin terlalu kecil untuk banyak kasus penggunaan. Misalnya, Anda dapat menentukan ukuran bucket berdasarkan kecepatan pemrosesan.

Untuk informasi selengkapnya tentang elemen ini, lihat deskripsi komparatif max_burst_size

dalam referensi Cloud Tasks API.
<max-concurrent-requests> (push queue)

Opsional. Menetapkan jumlah tugas maksimum yang dapat dijalankan secara bersamaan dari antrean yang ditentukan. Nilainya berupa bilangan bulat. Secara default, batasnya adalah 1.000 tugas per antrean. Batas atas yang direkomendasikan adalah 5.000 tugas per antrean. Perhatikan bahwa antrean mungkin meningkat perlahan saat pertama kali dibuat atau jika tidak ada aktivitas selama beberapa waktu.

Membatasi jumlah tugas serentak akan memberi Anda lebih banyak kontrol atas tingkat eksekusi antrean dan dapat mencegah terlalu banyak tugas dijalankan sekaligus. Hal ini juga dapat mencegah pertentangan datastore dan membuat resource tersedia untuk antrean lain atau pemrosesan online.

Untuk informasi selengkapnya tentang elemen ini, lihat deskripsi komparatif max_concurrent_dispatches dalam referensi Cloud Tasks API.

<mode>

Opsional. Mengidentifikasi mode antrean. Setelan ini ditetapkan secara default ke push, yang mengidentifikasi antrean sebagai push queue. Jika Anda ingin menggunakan pull queue, setel mode ke pull.

<name>

Wajib. Nama antrean. Ini adalah nama yang Anda tentukan saat memanggil QueueFactory.getQueue().

Nama antrean dapat berisi huruf besar dan kecil, angka, serta tanda hubung. Panjang maksimum nama antrean adalah 100 karakter.

Semua aplikasi memiliki push queue dengan nama default. Antrean ini memiliki kecepatan yang telah ditetapkan sebelumnya, yaitu 5 tugas per detik. Perlu diperhatikan bahwa antrean default ini tidak ditampilkan di konsol Google Cloud hingga pertama kali digunakan atau dikonfigurasi. Anda dapat mengonfigurasi antrean default, termasuk mengubah tarif default, dengan menentukan antrean bernama `default` di file queue.yaml Anda.

<rate> (push queue)

Wajib. Seberapa sering tugas diproses di antrean ini. Nilainya berupa angka yang diikuti garis miring dan unit waktu, dengan unitnya adalah s untuk detik, m untuk menit, h untuk jam, atau d untuk hari. Misalnya, nilai 5/m menyatakan bahwa tugas akan diproses dengan kecepatan 5 kali per menit. Nilai maksimum untuk rate adalah 500/s.

Jika jumlahnya 0 (seperti 0/s), antrean dianggap "dijeda" dan tidak ada tugas yang diproses.

Untuk mengetahui informasi selengkapnya tentang elemen ini, lihat deskripsi komparatif max_dispatches_per_second dalam referensi Cloud Tasks API.

<retry-parameters>

Opsional. Mengonfigurasi upaya percobaan ulang untuk tugas yang gagal dalam push queue. Penambahan ini memungkinkan Anda menentukan jumlah maksimum untuk mencoba kembali tugas yang gagal dalam antrean tertentu. Anda juga dapat menetapkan batas waktu untuk percobaan ulang dan mengontrol interval antar-percobaan.

Parameter percobaan ulang dapat berisi subelemen berikut:

<task-retry-limit>
Jumlah percobaan ulang. Misalnya, jika 0 ditetapkan dan tugas gagal, tugas tidak akan dicoba ulang sama sekali. Jika 1 ditentukan dan tugas gagal, tugas akan dicoba ulang sekali. Jika parameter ini tidak ditentukan, tugas akan dicoba ulang tanpa batas. Jika task_retry_limit ditetapkan dengan task_age_limit, tugas akan dicoba lagi hingga kedua batas tercapai.
<task-age-limit> (push queue)
Batas waktu untuk mencoba kembali tugas yang gagal, yang diukur dari saat tugas pertama kali dijalankan. Nilainya adalah angka yang diikuti oleh unit waktu, dengan unitnya adalah s untuk detik, m untuk menit, h untuk jam, atau d untuk hari. Misalnya, nilai 5d menentukan batas lima hari setelah upaya eksekusi pertama tugas. Jika parameter ini tidak ditentukan, tugas akan dicoba ulang tanpa batas. Jika ditentukan dengan task_retry_limit, App Engine akan mencoba kembali tugas hingga kedua batas tercapai.
<min-backoff-seconds> (push queue)
Jumlah detik minimum untuk menunggu sebelum mencoba kembali tugas setelah gagal. Nilai defaultnya adalah 0.1.
<max-backoff-seconds> (push queue)
Jumlah detik maksimum untuk menunggu sebelum mencoba kembali tugas setelah gagal. Nilai defaultnya adalah 3600.
<max-doublings> (push queue)
Frekuensi maksimum interval antara percobaan ulang tugas yang gagal akan dilipatgandakan sebelum peningkatan menjadi konstan. Konstanta tersebut adalah: 2**max_doublings * min_backoff_seconds. Nilai defaultnya adalah 16.
<target> (push queue)

Opsional. String yang menyebutkan layanan/versi, versi frontend, atau backend, untuk mengeksekusi semua tugas yang diantrekan ke antrean ini. Nilai defaultnya adalah string kosong.

String ini ditambahkan ke nama domain aplikasi Anda saat membuat permintaan HTTP untuk tugas. Misalnya, jika ID aplikasi adalah my-app dan Anda menetapkan target ke my-version-dot-my-service, nama host URL akan ditetapkan ke my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com.

Jika target tidak ditentukan, tugas akan dipanggil pada versi aplikasi yang sama tempat tugas tersebut diantrekan. Jadi, jika Anda mengantrekan tugas dari versi aplikasi default tanpa menentukan target di antrean, tugas tersebut akan dipanggil dalam versi aplikasi default. Perlu diperhatikan bahwa jika versi aplikasi default berubah antara waktu tugas diantrekan dan waktu eksekusinya, tugas akan berjalan dalam versi default yang baru.

Jika Anda menggunakan layanan bersama dengan file dispatch, permintaan HTTP tugas Anda mungkin ditangkap dan dialihkan ke layanan lain.

Elemen berikut dapat ditentukan untuk semua antrean dalam aplikasi:

Elemen Deskripsi
<total-storage-limit>

Opsional. String yang mengganti batas penyimpanan kuota default yang tersedia untuk penyimpanan taskqueue (100 M). Contoh:

<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

Kuota ini adalah bagian dari total kuota penyimpanan aplikasi (termasuk kuota datastore dan blobstore).

Jika akhiran tidak ditentukan, angka yang Anda tentukan akan ditafsirkan sebagai byte. Akhiran berikut didukung:

  • B (byte)
  • K (kilobyte)
  • M (megabyte)
  • G (gigabyte)
  • T (terabyte)

Jika <total-storage-limit> melebihi total penyimpanan disk yang tersedia untuk aplikasi, batas penyimpanan yang tersedia akan dibatasi.

Men-deploy file konfigurasi queue

File queue.yaml dapat berada di mana saja dalam direktori kode sumber Anda.

Untuk men-deploy file konfigurasi antrean tanpa mengubah versi yang saat ini aktif, gunakan salah satu perintah berikut di direktori yang berisi file antrean Anda, bergantung pada lingkungan Anda:

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

Jika menggunakan IntelliJ atau Eclipse, Anda memilih setiap file konfigurasi yang akan di-deploy menggunakan formulir deployment.

Menghapus queue

Untuk menghapus antrean:

  1. Hapus definisi antrean dari file queue.yaml Anda.

  2. Upload perubahan ke file queue.yaml Anda.

    Aplikasi gcloud men-deploy queue.yaml

  3. Hapus antrean di konsol Google Cloud, pilih antrean, lalu klik Delete queue:

    Buka halaman Task queue

Jika menghapus antrean dari konsol Google Cloud, Anda harus menunggu 7 hari sebelum membuat ulang dengan nama yang sama.