Ringkasan Fungsi yang Ditentukan Pengguna (UDF)

Fungsi yang Ditentukan Pengguna (UDF) JavaScript adalah jenis Transformasi Pesan Tunggal (SMT). UDF menyediakan cara yang fleksibel untuk menerapkan logika transformasi kustom dalam Pub/Sub, mirip dengan UDF JavaScript BigQuery.

UDF menerima satu pesan sebagai input, melakukan tindakan yang ditentukan pada input, dan menampilkan hasil proses.

UDF memiliki properti utama berikut:

  • Kode: Kode JavaScript yang menentukan logika transformasi.

  • Nama fungsi: Nama fungsi JavaScript dalam kode yang disediakan yang diterapkan Pub/Sub ke pesan.

Buat fungsi JavaScript

Kode UDF harus berisi fungsi dengan tanda tangan berikut:

  /**
  * Transforms a Pub/Sub message.
  * @return {(Object<string, (string | Object<string, string>)>|* null)} - To
  * filter a message, return `null`. To transform a message, return a map with
  * the following keys:
  *   - (required) 'data' : {string}
  *   - (optional) 'attributes' : {Object<string, string>}
  * Returning empty `attributes` will remove all attributes from the message.
  *
  * @param  {(Object<string, (string | Object<string, string>)>} - Pub/Sub
  * message. Keys:
  *   - (required) 'data' : {string}
  *   - (required) 'attributes' : {Object<string, string>}
  *
  * @param  {Object<string, any>} metadata - Pub/Sub message metadata.
  * Keys:
  *   - (optional) 'message_id'  : {string}
  *   - (optional) 'publish_time': {string} YYYY-MM-DDTHH:MM:SSZ format
  *   - (optional) 'ordering_key': {string}
  */
  function <function_name>(message, metadata) {
    // Perform custom transformation logic
    return message; // to filter a message instead, return `null`
  }

Input

Fungsi ini mengambil input berikut:

  • Argumen message: Objek JavaScript yang merepresentasikan pesan Pub/Sub. Objek ini berisi properti berikut:

    • data: (String, wajib) Payload pesan.

    • attributes: (Object<String, String>, opsional) Peta pasangan nilai kunci yang merepresentasikan atribut pesan.

  • Argumen metadata: Objek JavaScript yang berisi metadata tetap tentang pesan Pub/Sub:

    • message_id: (String, opsional) ID unik pesan.

    • publish_time: (String, opsional) Waktu publikasi pesan dalam format RFC 3339 (YYYY-MM-DDTHH:mm:ssZ).

    • ordering_key: (String, opsional) Kunci pengurutan pesan, jika berlaku.

Output

Fungsi harus menampilkan salah satu dari berikut ini:

  • Untuk mengubah pesan, edit konten message.data dan message.attributes, lalu tampilkan objek message yang telah diubah.

  • Untuk memfilter pesan, kembalikan null.

Persyaratan Input / Output

  • Jika UDF mengubah payload pesan, input dan output payload harus berupa string berenkode UTF-8.
  • Jika UDF tidak mengubah payload pesan, payload dapat menggunakan encoding apa pun.
  • Pasangan nilai kunci atribut harus berupa string berenkode UTF-8.

Cara UDF mengubah pesan

Hasil menjalankan UDF pada pesan dapat berupa salah satu dari berikut:

  • UDF mengubah pesan.

  • UDF menampilkan null.

    • SMT Topik: Pub/Sub menampilkan keberhasilan kepada penerbit dan menyertakan ID pesan dalam respons untuk pesan yang difilter. Pub/Sub tidak menyimpan pesan atau mengirimkannya ke pelanggan mana pun.

    • SMT Langganan: Pub/Sub mengonfirmasi pengiriman pesan tanpa mengirim pesan ke pelanggan.

  • UDF menampilkan error.

    • SMT Topik: Pub/Sub menampilkan error ke penerbit dan tidak memublikasikan pesan apa pun.

    • SMT Langganan: Pub/Sub mengonfirmasi pesan secara negatif.

Membuat SMT UDF

SMT dapat dikonfigurasi pada topik atau langganan Pub/Sub.

  • SMT topik dijalankan sebelum Pub/Sub menyimpan pesan, dan hasilnya tersedia untuk semua pelanggan.

  • SMT langganan dijalankan sebelum pesan dikirim, dan hasilnya hanya tersedia untuk langganan tersebut.

Konsol

  1. Di konsol Google Cloud , buka halaman Topics Pub/Sub.

    Buka Topik

  2. Buat topik atau langganan.

    • Untuk membuat topik, klik Buat topik. Halaman Create topic akan terbuka.

    • Untuk membuat langganan:

      1. Klik nama topik tempat Anda menginginkan langganan.

      2. Klik Buat langganan. Halaman Add subscription to topic akan terbuka.

  3. Di bagian Transformasi, klik Tambahkan transformasi.

  4. Untuk Transform type, pilih JavaScript UDF.

  5. Opsional: Anda dapat menggunakan Gemini Enterprise untuk membuat kode bagi UDF, sebagai berikut:

    1. Klik Buat dengan AI.

    2. Di kolom teks, masukkan deskripsi tentang fungsi yang harus dilakukan. Misalnya, "Tambahkan atribut processed_at dengan waktu saat ini".

    3. Klik Kirim. Kode yang dibuat akan muncul di panel Buat dengan AI, beserta penjelasan kode.

    4. Periksa kebenaran kode. Anda mungkin perlu menyempurnakan deskripsi dan membuat ulang kode.

    5. Untuk menggunakan kode yang dihasilkan, klik Impor.

  6. Di kolom Nama fungsi, masukkan nama fungsi JavaScript yang dipanggil SMT. Contoh: redactSSN.

    Jika Anda menggunakan Gemini Enterprise untuk membuat kode, kolom ini sudah diisi.

  7. Di area teks, masukkan kode untuk UDF. Contoh:

    function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}

    Kode harus berisi fungsi yang namanya cocok dengan kolom Nama fungsi.

    Jika Anda menggunakan Gemini Enterprise untuk membuat kode, kolom ini sudah diisi.

  8. Jika Anda tidak ingin SMT aktif segera, pilih Nonaktifkan transformasi. Jika opsi ini dipilih, SMT akan dibuat dengan topik, tetapi tidak dijalankan pada pesan masuk. Setelah topik dibuat, Anda dapat mengedit topik untuk mengaktifkan SMT.

  9. Untuk membuat topik atau langganan, klik Buat.

gcloud

Membuat file definisi

Buat file YAML atau JSON yang menentukan SMT UDF.

YAML 

- javascriptUdf:
    code: { FUNCTION_CODE }
    functionName: FUNCTION_NAME

JSON 

{
  "javascriptUdf": {
    "code": {
      FUNCTION_CODE
    }
    "functionName": FUNCTION_NAME
  }
}

Ganti kode berikut:

  • FUNCTION_CODE: Kode JavaScript untuk UDF. Kode harus berisi fungsi yang namanya cocok dengan kolom functionName. Contoh:

    function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}

  • FUNCTION_NAME: Nama fungsi JavaScript yang dipanggil SMT. Contoh: redactSSN.

Membuat topik atau langganan

Untuk membuat topik, jalankan perintah gcloud pubsub topics create.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Ganti kode berikut:

  • TOPIC_ID: ID atau nama topik yang ingin Anda buat.
  • TRANSFORMS_FILE: Jalur ke file definisi.

Untuk membuat langganan, jalankan perintah gcloud pubsub subscriptions create.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Ganti kode berikut:

  • SUBSCRIPTION_ID: ID atau nama langganan yang akan dibuat.

  • PROJECT_ID: ID project yang berisi topik.

  • TOPIC_ID: ID topik yang akan dijadikan langganan.

  • TRANSFORMS_FILE: Jalur ke file definisi.

Secara opsional, Anda dapat memvalidasi dan menguji SMT sebelum membuatnya. Untuk informasi selengkapnya, lihat halaman berikut:

Batasan

Pub/Sub menerapkan batas resource pada UDF untuk memastikan operasi transformasi yang efisien. Batasan ini mencakup:

  • Maksimum 20 KB kode per UDF
  • Waktu eksekusi maksimum 500 md per pesan
  • Dukungan untuk built-in standar ECMAScript saja
  • Tidak ada panggilan ke API eksternal
  • Tidak ada impor library eksternal

Contoh UDF

Berikut beberapa contoh UDF untuk memublikasikan dan berlangganan. Anda dapat menemukan contoh tambahan di pustaka UDF.

Fungsi: Mengonversi bilangan bulat hari dalam seminggu menjadi string yang sesuai

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama penerbitan atau pengiriman pesan:

  1. Pub/Sub menerapkan fungsi ke pesan. Jika pesan tidak memiliki payload JSON, UDF akan menampilkan error.

  2. UDF mencari kolom bernama dayOfWeek dan jika nilai kolom ini adalah angka antara 0 dan 6, UDF akan mengonversinya menjadi hari dalam seminggu yang sesuai, seperti Monday. Jika kolom tidak ada atau angka tidak berada dalam rentang 0 hingga 6, kode akan menetapkan kolom dayOfWeek ke Unknown.

  3. UDF menserialisasi payload yang dimodifikasi kembali ke dalam pesan.

  4. Pub/Sub meneruskan pesan yang diperbarui ke langkah berikutnya dalam pipeline Anda.

function intToString(message, metadata) {
  const data = JSON.parse(message.data);
  switch(`data["dayOfWeek"]`) {
    case 0:
      data["dayOfWeek"] = "Sunday";
      break;
    case 1:
      data["dayOfWeek"] = "Monday";
      break;
    case 2:
      data["dayOfWeek"] = "Tuesday";
      break;
    case 3:
      data["dayOfWeek"] = "Wednesday";
      break;
    case 4:
      data["dayOfWeek"] = "Thursday";
      break;
    case 5:
      data["dayOfWeek"] = "Friday";
      break;
    case 6:
      data["dayOfWeek"] = "Saturday";
      break;
    default:
      data["dayOfWeek"] = "Unknown";
  }
  message.data = JSON.stringify(data);
  return message;
}

Fungsi: Menghapus nomor jaminan sosial

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama penerbitan atau pengiriman pesan:

  1. Pub/Sub menerapkan fungsi ke pesan. Jika pesan tidak memiliki payload JSON, UDF akan menampilkan error.

  2. UDF menghapus kolom ssn dari payload pesan (jika ada).

  3. UDF menserialisasi payload yang dimodifikasi kembali ke dalam pesan.

  4. Pub/Sub meneruskan pesan yang diperbarui ke langkah berikutnya dalam pipeline Anda.

function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}

Fungsi: Memfilter dan mengonfirmasi otomatis pesan tertentu

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama penerbitan atau pengiriman pesan:

  1. Pub/Sub menerapkan fungsi ke pesan. Jika pesan tidak memiliki payload JSON, UDF akan menampilkan error.

  2. UDF memeriksa apakah payload berisi kolom bernama region.

  3. Jika nilai kolom region bukan US, fungsi akan menampilkan null, sehingga Pub/Sub memfilter pesan.

  4. Jika nilai kolom region adalah US, Pub/Sub akan meneruskan pesan asli ke langkah berikutnya dalam pipeline Anda.

function filterForUSRegion(message, metadata) {
  const data = JSON.parse(message.data);
  if (data["region"] !== "US") {
    return null;
  }
  return message;
}

Fungsi: Validasi konten pesan untuk memastikan jumlahnya tidak lebih besar dari 100

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama penerbitan atau pengiriman pesan:

  1. Pub/Sub menerapkan fungsi ke pesan. Jika pesan tidak memiliki payload JSON, UDF akan menampilkan error.

  2. UDF memeriksa apakah pesan berisi kolom bernama amount.

  3. Jika nilai kolom amount lebih besar dari 100, fungsi akan menampilkan error.

  4. Jika nilai kolom amount tidak lebih besar dari 100, fungsi akan menampilkan pesan asli.

  5. Kemudian, Pub/Sub menandai pesan sebagai gagal, atau meneruskan pesan asli ke langkah berikutnya dalam pipeline Anda.

function validateAmount(message, metadata) {
  const data = JSON.parse(message.data);
  if (data["amount"] > 100) {
    throw new Error("Amount is invalid");
  }
  return message;
}

Langkah berikutnya