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:

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

  • Kode: Kode JavaScript yang menentukan logika transformasi. Kode ini 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

  • Argumen message: Objek JavaScript yang mewakili pesan Pub/Sub. Isinya adalah 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

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

  • Untuk memfilter pesan, tampilkan null.

Cara UDF mengubah pesan

Hasil dari menjalankan UDF pada pesan dapat berupa salah satu dari 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 mengirim 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.

Batas Resource

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

  • Kode maksimum 20 KB per UDF
  • Eksekusi maksimum 500 md per pesan
  • Tidak ada panggilan ke API eksternal
  • Tidak ada impor library eksternal

Contoh UDF

Berikut adalah beberapa contoh UDF untuk memublikasikan dan berlangganan.

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 yang disebut dayOfWeek dan jika nilai kolom ini adalah angka antara 0 dan 6, konversikan ke hari yang sesuai dalam seminggu 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 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: Menyamarkan 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 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 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 yang disebut region.

  3. Jika nilai kolom region bukan US, fungsi akan menampilkan null, sehingga menyebabkan 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: Memvalidasi konten pesan untuk memastikan jumlahnya tidak lebih 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 yang disebut amount.

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

  4. Jika nilai kolom amount tidak lebih besar dari 100, fungsi ini 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