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.

Membuat 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 menggunakan input berikut:

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

    • data: (String, wajib) Payload pesan.

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

  • Argumen metadata: Objek JavaScript yang berisi metadata yang tidak dapat diubah 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 ini harus menampilkan salah satu hal berikut:

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

  • Untuk memfilter pesan, tampilkan 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 hal berikut:

  • UDF mengubah pesan.

  • UDF menampilkan null.

    • SMT Topik: Pub/Sub menampilkan keberhasilan kepada penayang 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 mengirimkan pesan ke pelanggan.

  • UDF menampilkan error.

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

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

Membuat SMT UDF

SMT dapat dikonfigurasi di 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 Google Cloud konsol, buka halaman Topics Pub/Sub.

    Buka Topics

  2. Buat topik atau langganan.

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

    • Untuk membuat langganan:

      1. Klik nama topik tempat Anda ingin membuat langganan.

      2. Klik Create subscription. Halaman Add subscription to topic akan terbuka.

  3. Di bagian Transforms, klik Add a transform.

  4. Untuk Transform type, pilih JavaScript UDF.

  5. Di kolom Function name, masukkan nama fungsi JavaScript yang dipanggil SMT. Contoh: redactSSN.

  6. 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 Function name.

  7. Jika Anda tidak ingin SMT segera aktif, pilih Disable transform. 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.

  8. Untuk membuat topik atau langganan, klik Create.

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 gcloud pubsub topics create perintah.

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 gcloud pubsub subscriptions create perintah.

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 dilanggan.

  • TRANSFORMS_FILE: Jalur ke file definisi.

Jika ingin, Anda dapat memvalidasi dan menguji SMT sebelum membuatnya. Untuk mengetahui informasi selengkapnya, lihat halaman berikut:

Batasan

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

  • Maksimum 20 KB kode per UDF
  • Maksimum 500 md waktu eksekusi per pesan
  • Hanya mendukung bawaan standar ECMAScript
  • 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 library 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 publikasi 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 melakukan serialisasi payload yang diubah 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: Mengedit nomor jaminan sosial

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama publikasi 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 melakukan serialisasi payload yang diubah 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 pesan tertentu secara otomatis

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama publikasi 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 akan 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: Memvalidasi konten pesan untuk memastikan jumlahnya tidak lebih besar dari 100

Saat Anda menambahkan UDF berikut ke topik atau langganan, perubahan berikut akan terjadi selama publikasi 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. Pub/Sub kemudian 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