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 merepresentasikan pesan Pub/Sub. Objek ini berisi properti berikut:

    • data: (String, wajib) Payload pesan.

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

  • Argumen metadata: Objek JavaScript yang berisi metadata 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 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 ini:

  • UDF mentransformasi 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 secara negatif mengonfirmasi pesan.

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 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 menserialisasi 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: Menghapus 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 menserialisasi 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 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 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: 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 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