Template dataflow

Dengan template Dataflow, Anda dapat mengemas pipeline Dataflow untuk deployment. Siapa pun yang memiliki izin yang benar dapat menggunakan template untuk men-deploy pipeline yang dipaketkan. Anda dapat membuat template Dataflow kustom sendiri, dan Google menyediakan template bawaan untuk skenario umum.

Manfaat

Template memiliki beberapa keunggulan dibandingkan men-deploy pipeline langsung ke Dataflow:

• Template memisahkan desain pipeline dari deployment. Misalnya, developer dapat membuat template, dan data scientist dapat men-deploy template tersebut di lain waktu.
• Template dapat memiliki parameter yang memungkinkan Anda menyesuaikan pipeline saat men-deploy template.
• Anda dapat men-deploy template menggunakan konsol Google Cloud , Google Cloud CLI, atau panggilan REST API. Anda tidak memerlukan lingkungan pengembangan atau dependensi pipeline apa pun yang diinstal di komputer lokal Anda.
• Template adalah artefak kode yang dapat disimpan di repositori kontrol sumber dan digunakan dalam pipeline continuous integration (CI/CD).

Template yang disediakan Google

Google menyediakan berbagai template Dataflow open source bawaan yang dapat Anda gunakan untuk skenario umum. Untuk mengetahui informasi selengkapnya tentang template yang tersedia, lihat Template yang disediakan Google.

Mulai 4 Agustus 2025, tugas template yang dikelola Google akan berjalan di Dataflow Prime secara default. Untuk menjalankan tugas di Dataflow standar, Anda harus menonaktifkan Dataflow Prime. Untuk menonaktifkan Dataflow Prime untuk tugas template yang dikelola Google, tetapkan opsi layanan Dataflow enable_prime ke false (enable_prime=false) saat Anda menjalankan template. Untuk mengetahui detail selengkapnya, lihat Menonaktifkan Dataflow Prime.

Membandingkan template Flex dan template klasik

Dataflow mendukung dua jenis template: template Flex, yang lebih baru, dan template klasik. Jika Anda membuat template Dataflow baru, sebaiknya buat sebagai template Flex.

Dengan template Flex, pipeline dipaketkan sebagai image Docker di Artifact Registry, bersama dengan file spesifikasi template di Cloud Storage. Spesifikasi template berisi pointer ke image Docker. Saat Anda menjalankan template, layanan Dataflow akan memulai VM peluncur, mengambil image Docker, dan menjalankan pipeline. Grafik eksekusi dibuat secara dinamis berdasarkan parameter runtime yang disediakan oleh pengguna. Untuk menggunakan API guna meluncurkan tugas yang menggunakan template Flex, gunakan metode projects.locations.flexTemplates.launch.

Template klasik berisi serialisasi JSON dari grafik tugas Dataflow. Kode untuk pipeline harus menggabungkan parameter runtime apa pun dalam antarmuka ValueProvider. Antarmuka ini memungkinkan pengguna menentukan parameter value saat men-deploy template. Untuk menggunakan API dengan template klasik, lihat projects.locations.templates dokumentasi referensi API.

Template Flex memiliki keunggulan berikut dibandingkan template klasik:

• Tidak seperti template klasik, template Flex tidak memerlukan antarmuka ValueProvider untuk parameter input. Tidak semua sumber dan sink Dataflow mendukung ValueProvider.
• Meskipun template klasik memiliki grafik tugas statis, template Flex dapat membuat grafik tugas secara dinamis. Misalnya, template mungkin memilih konektor I/O yang berbeda berdasarkan parameter input.
• Template Flex dapat melakukan pra-pemrosesan pada virtual machine (VM) selama konstruksi pipeline. Misalnya, fungsi ini mungkin memvalidasi nilai parameter input.

Alur kerja template

Penggunaan template Dataflow melibatkan langkah-langkah tingkat tinggi berikut:

1. Developer menyiapkan lingkungan pengembangan dan mengembangkan pipeline mereka. Lingkungan ini mencakup Apache Beam SDK dan dependensi lainnya.
2. Bergantung pada jenis template (Flex atau klasik):
   • Untuk template Flex, developer mengemas pipeline ke dalam image Docker, mengirim image ke Artifact Registry, dan mengupload file spesifikasi template ke Cloud Storage.
   • Untuk template klasik, developer menjalankan pipeline, membuat file template, dan melakukan staging template ke Cloud Storage.
3. Pengguna lain mengirimkan permintaan ke layanan Dataflow untuk menjalankan template.
4. Dataflow membuat pipeline dari template. Pipeline dapat memerlukan waktu hingga lima hingga tujuh menit untuk mulai berjalan.

Memeriksa dan mengaudit tugas template

Saat Anda mengaudit tugas template Dataflow yang sedang berjalan atau historis secara terprogram menggunakan REST API atau Google Cloud CLI, tampilan defaultnya adalah tampilan ringkasan (JOB_VIEW_SUMMARY). Tampilan ringkasan menghilangkan detail eksekusi pipeline, metadata template, dan opsi pipeline SDK. Untuk mengambil detail template dan opsi lingkungan, Anda harus secara eksplisit meminta tampilan tugas lengkap.

Untuk memeriksa detail template untuk tugas, gunakan salah satu metode berikut:

gcloud CLI

Untuk mengambil deskripsi tugas lengkap, termasuk detail template, jalankan perintah gcloud dataflow jobs describe dengan flag --full:

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

• REGION: region Dataflow tempat tugas berjalan.
• JOB_ID: ID tugas Dataflow.

Jalankan perintah berikut:

Linux, macOS, atau Cloud Shell

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI dengan autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

Catatan: Pastikan Anda telah menginisialisasi Google Cloud CLI melalui autentikasi dan sebuah project dengan menjalankan gcloud init; atau gcloud auth login dan gcloud config set project.

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Anda akan melihat respons seperti berikut:

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

Untuk mengambil resource tugas lengkap termasuk detail template, kirim permintaan GET HTTP ke metode projects.locations.jobs.get dengan parameter kueri view=JOB_VIEW_ALL:

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

• PROJECT_ID: Project ID Google Cloud Anda.
• REGION: region Dataflow tempat tugas berjalan.
• JOB_ID: ID tugas Dataflow.

Metode HTTP dan URL:

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

Untuk mengirim permintaan Anda, pilih salah satu opsi berikut:

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

Anda akan melihat respons JSON seperti berikut:

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

Mengidentifikasi jenis template

Payload respons berbeda-beda, bergantung pada apakah tugas dibuat dari template yang disediakan Google atau template kustom:

• Template yang disediakan Google: Dataflow otomatis melampirkan label yang telah ditetapkan ke resource tugas:
  • goog-dataflow-provided-template-name: nama template.
  • goog-dataflow-provided-template-type: jenis template, baik flex atau legacy (klasik).
  • goog-dataflow-provided-template-version: versi rilis template.
• Template kustom: Tugas template kustom tidak memiliki label goog-dataflow-provided-*. Tugas template Flex dan template klasik mengisi opsi templateLocation di environment.sdkPipelineOptions. Untuk menentukan jenis template untuk tugas kustom saat label tidak ada, periksa kolom berikut dalam respons tugas lengkap (JOB_VIEW_ALL):
  • Template klasik: Kolom templateLocation mengarah langsung ke file JSON template yang di-stage di Cloud Storage. Misalnya, jalur tersebut menyerupai gs://BUCKET_NAME/templates/TEMPLATE_NAME. Tugas template klasik tidak memiliki konfigurasi image peluncur container.
  • Template Flex: Tugas template Flex dijalankan dari image container peluncur. Di bagian objek environment, tugas template Flex berisi spesifikasi dan parameter container peluncur (seperti flexResourceLimits). Selain itu, jalur Cloud Storage templateLocation yang di-stage dan dibuat selama peluncuran berisi ID pekerjaan.

Praktik terbaik: melampirkan label pengguna selama peluncuran

Karena membedakan jenis template kustom secara terprogram memerlukan pengambilan dan penguraian opsi lingkungan JOB_VIEW_ALL lengkap, sebaiknya Anda melampirkan label pengguna deskriptif saat meluncurkan tugas template. Misalnya, lampirkan label seperti template-type: flex atau template-type: classic.

Label pengguna ditampilkan dalam tampilan ringkasan default (JOB_VIEW_SUMMARY) dan dalam operasi daftar tugas. Label pengguna memungkinkan Anda memfilter, menelusuri, dan mengaudit tugas template secara efisien di seluruh project tanpa mengambil payload eksekusi lengkap untuk setiap tugas.

Untuk melampirkan label saat meluncurkan template, gunakan metode berikut:

• Untuk template Flex di gcloud CLI, gunakan flag --additional-user-labels dalam perintah gcloud dataflow flex-template run.
• Untuk template klasik di gcloud CLI, gunakan flag --labels dalam perintah gcloud dataflow jobs run.
• Saat menggunakan REST API, sertakan key-value map labels dalam isi permintaan peluncuran.

Menetapkan izin IAM

Tugas Dataflow, termasuk tugas yang dijalankan dari template, menggunakan dua akun layanan IAM:

• Layanan Dataflow menggunakan akun layanan Dataflow untuk memanipulasi resource Google Cloud , seperti membuat VM.
• Worker VM Dataflow menggunakan akun layanan worker untuk mengakses file pipeline dan resource lainnya. Akun layanan ini memerlukan akses ke resource apa pun yang dirujuk oleh tugas pipeline, termasuk sumber dan sink yang digunakan template. Untuk mengetahui informasi selengkapnya, lihat Mengakses Google Cloud resource.

Pastikan kedua akun layanan ini memiliki peran yang sesuai. Untuk mengetahui informasi selengkapnya, lihat Keamanan dan izin Dataflow.

Jika organisasi Anda menggunakan kebijakan principal access boundary (PAB), principal (seperti pengguna atau akun layanan) mungkin diblokir agar tidak dapat melihat dan menjalankan template yang disediakan Google. Untuk mengetahui informasi dan solusi selengkapnya, lihat Mengakses template yang disediakan Google dengan kebijakan batas akses akun utama.

Persyaratan versi Apache Beam SDK

Untuk membuat template Anda sendiri, pastikan versi Apache Beam SDK Anda mendukung pembuatan template.

Java

Untuk membuat template dengan Apache Beam SDK 2.x untuk Java, Anda harus memiliki versi 2.0.0-beta3 atau yang lebih tinggi.

Python

Untuk membuat template dengan Apache Beam SDK 2.x untuk Python, Anda harus memiliki versi 2.0.0 atau yang lebih tinggi.

Untuk menjalankan template dengan Google Cloud CLI, Anda harus memiliki Google Cloud CLI versi 138.0.0 atau yang lebih tinggi.

Memperluas template

Anda dapat membuat template sendiri dengan memperluas template Dataflow open source. Misalnya, untuk template yang menggunakan durasi jendela tetap, data yang tiba di luar jendela mungkin akan dihapus. Untuk menghindari perilaku ini, gunakan kode template sebagai dasar, dan ubah kode untuk memanggil operasi .withAllowedLateness.

Langkah berikutnya

• Template yang disediakan Google
• Menggunakan Template Flex untuk memaketkan pipeline
• Membangun dan menjalankan contoh Template Flex
• Membuat template klasik
• Menjalankan template klasik
• Memecahkan Masalah Template Flex