Membuat Pengendali Tugas

Halaman ini menjelaskan cara membuat pengendali tugas, kode yang menangani tugas push. Anda harus menyediakan pengendali permintaan untuk memproses tugas. Pemetaan dari URL permintaan ke pengendali yang sesuai dideklarasikan dalam app.yaml layanan Anda, seperti pengendali permintaan lainnya. Karena Anda yang mengontrol cara memetakan permintaan tugas ke pengendali, Anda bebas mengatur pengendali tugas. Jika aplikasi memproses berbagai jenis tugas, Anda dapat menambahkan semua pengendali ke satu layanan, atau mendistribusikannya di antara beberapa layanan.

Menulis pengendali permintaan tugas push

Dalam antrean, layanan Task Queue membuat header HTTP dan mengirimkannya ke instance layanan pekerja yang ditentukan oleh target tugas. Permintaan Task Queue dikirim dari alamat IP 0.1.0.2.

Pengendali tidak perlu ditulis dalam bahasa yang sama dengan yang membuat dan mengantrekan tugas jika pengendali berada dalam layanan terpisah.

Saat Anda menulis pengendali, ikuti panduan ini:

  • Kode tersebut harus menampilkan kode status HTTP dalam rentang 200–299 untuk menunjukkan keberhasilan. Kode lainnya menunjukkan bahwa tugas gagal.

  • Tugas push memiliki batas waktu penyelesaian tetap yang bergantung pada jenis penskalaan layanan yang menjalankannya. Layanan penskalaan otomatis harus selesai sebelum 10 menit berlalu. Layanan penskalaan manual dan dasar dapat berjalan hingga 24 jam. Jika pengendali Anda melewatkan batas waktu, layanan Task Queue akan menganggap tugas tersebut gagal dan akan mencobanya lagi.

    Saat waktu eksekusi tugas mendekati batas waktu, App Engine akan memunculkan DeadlineExceededError (dari modul google.appengine.runtime) sebelum batas waktu tercapai, sehingga Anda dapat menyimpan pekerjaan atau mencatat log progres yang telah tercapai.

  • Pengendali harus bersifat idempoten. Task Queue API App Engine dirancang untuk memberikan pengiriman "setidaknya sekali"; yaitu, jika tugas berhasil ditambahkan, App Engine akan mengirimkannya ke pengendali setidaknya satu kali. Perhatikan bahwa dalam beberapa situasi yang jarang terjadi, beberapa eksekusi tugas dapat dilakukan, sehingga kode Anda harus memastikan tidak ada efek samping yang berbahaya dari eksekusi berulang.

Contoh berikut menunjukkan pengambilan nilai bilangan bulat dari permintaan dan penambahan nilai ke penghitung yang disimpan di Cloud Datastore:


from google.appengine.ext import ndb
import webapp2


COUNTER_KEY = 'default counter'


class Counter(ndb.Model):
    count = ndb.IntegerProperty(indexed=False)


class UpdateCounterHandler(webapp2.RequestHandler):
    def post(self):
        amount = int(self.request.get('amount'))

        # This task should run at most once per second because of the datastore
        # transaction write throughput.
        @ndb.transactional
        def update_counter():
            counter = Counter.get_or_insert(COUNTER_KEY, count=0)
            counter.count += amount
            counter.put()

        update_counter()


app = webapp2.WSGIApplication([
    ('/update_counter', UpdateCounterHandler)
], debug=True)

Pemetaan dari URL tugas /update-counter ke class UpdateCounterHandler dilakukan di dalam WSGIApplication.

File worker.yaml membuat layanan bernama "pekerja" dan menambahkan kode pekerja ke dalamnya. Perlu diperhatikan bahwa URL pengendali aman karena menentukan login:admin:

runtime: python27
api_version: 1
threadsafe: true
service: worker

handlers:
- url: /.*
  script: worker.app
  login: admin

Task Queue menggunakan kode HTTP dalam respons pengendali untuk menentukan apakah tugas berhasil. Respons dari pengendali hanya terlihat oleh layanan Task Queue dan hanya untuk menentukan apakah tugas berhasil. Antrean mengabaikan semua kolom lain dalam respons. Kemudian, layanan akan menghapus respons. Aplikasi asal tidak pernah menerima data apa pun. Jika tugas gagal, layanan Task Queue akan mencoba kembali tugas tersebut dengan mengirim permintaan lain.

Data yang disediakan pengguna dapat dikirim ke pengendali dalam permintaan sebagai string kueri atau sebagai payload dalam isi permintaan. Memasukkan data pengguna dijelaskan dalam Membuat Tugas. Jika permintaan menyertakan data, pengendali harus mengetahui cara permintaan tersebut dimasukkan ke dalam permintaan. Kode yang sama persis dengan yang Anda gunakan untuk mengambil data dari permintaan bergantung pada framework web tertentu yang Anda gunakan.

Untuk menguji pengendali tugas, login sebagai administrator dan buka URL pengendali di browser Anda.

Membaca header permintaan

Permintaan HTTP tugas push memiliki header khusus yang ditetapkan oleh App Engine, yang berisi informasi khusus tugas yang dapat digunakan pengendali.

Jika ada header ini dalam permintaan pengguna eksternal ke aplikasi Anda, header tersebut akan dihapus dan diganti. Satu-satunya pengecualian adalah untuk permintaan dari administrator aplikasi yang login, yang diizinkan menyetel header untuk tujuan pengujian. Di sisi lain, header tidak akan dihapus saat aplikasi Anda berjalan di server pengembangan.

Permintaan dari Task Queue akan selalu berisi header berikut:

Header Deskripsi
X-Appengine-QueueName Nama antrean (mungkin "default" untuk push queue default).
X-Appengine-TaskName Nama tugas, atau ID unik yang dihasilkan sistem jika tidak ada nama yang ditentukan.
X-Appengine-TaskRetryCount Frekuensi tugas ini dicoba lagi. Untuk upaya pertama, nilainya adalah 0. Jumlah ini mencakup upaya saat tugas gagal karena kurangnya instance yang tersedia dan tidak pernah mencapai fase eksekusi.
X-Appengine-TaskExecutionCount Frekuensi kegagalan sebelumnya dari tugas ini selama fase eksekusi. Jumlah ini tidak mencakup kegagalan karena kurangnya instance yang tersedia.
X-Appengine-TaskETA Target waktu eksekusi tugas, ditentukan dalam detik sejak 1 Januari 1970.

Jika pengendali permintaan Anda menemukan salah satu header yang tercantum di atas, pengendali dapat memercayai bahwa permintaan tersebut adalah permintaan Task Queue.

Selain itu, permintaan dari Task Queue dapat berisi header berikut:

Header Deskripsi
X-Appengine-TaskPreviousResponse Kode respons HTTP dari percobaan ulang sebelumnya.
X-Appengine-TaskRetryReason Alasan percobaan ulang tugas.
X-Appengine-FailFast Menunjukkan bahwa tugas yang berjalan akan langsung gagal jika instance yang ada tidak tersedia.

Mengamankan URL pengendali tugas

Jika tugas menjalankan operasi yang sensitif (seperti mengubah data), Anda mungkin perlu mengamankan URL pengendali untuk mencegah pengguna eksternal yang berbahaya memanggilnya secara langsung. Anda dapat mencegah pengguna mengakses URL tugas dengan membatasi akses ke administrator App Engine. Permintaan tugas itu sendiri dikeluarkan oleh App Engine dan selalu dapat menargetkan URL terbatas.

Anda dapat membatasi URL dengan menambahkan elemen login: admin ke konfigurasi pengendali di file app.yaml.

Contoh:

handlers:
- url: /your-task
  script: worker.app
  login: admin

Langkah berikutnya