Panoramica delle funzioni definite dall'utente

Una funzione definita dall'utente (UDF) JavaScript è un tipo di trasformazione singolo messaggio (SMT). Le UDF offrono un modo flessibile per implementare la logica di trasformazione personalizzata in Pub/Sub, in modo simile alle UDF JavaScript di BigQuery.

Le funzioni definite dall'utente accettano un singolo messaggio come input, eseguono le azioni definite sull'input e restituiscono il risultato della procedura.

Le funzioni UDF hanno le seguenti proprietà chiave:

  • Nome funzione:il nome della funzione JavaScript all'interno del codice fornito che Pub/Sub applica ai messaggi.

  • Codice:il codice JavaScript che definisce la logica di trasformazione. Questo codice deve contenere una funzione con la seguente firma:

    /**
* 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

  • Argomento message: un oggetto JavaScript che rappresenta il messaggio Pub/Sub. Contiene le seguenti proprietà:

    • data: (String, obbligatorio) il payload del messaggio.

    • attributes: (Object<String, String>, facoltativo) una mappa di coppie chiave-valore che rappresentano gli attributi del messaggio.

  • argomento metadata: un oggetto JavaScript contenente metadati immutabili sul messaggio Pub/Sub:

    • message_id: (String, facoltativo) l'ID univoco del messaggio.

    • publish_time: (String, facoltativo) L'ora di pubblicazione del messaggio nel formato RFC 3339 (AAAA-MM-GGTHH:mm:ssZ).

    • ordering_key: (String, facoltativo) la chiave di ordinamento del messaggio, se applicabile.

Output

  • Per trasformare un messaggio, modifica i contenuti di message.data e message.attributes e restituisci l'oggetto message modificato.

  • Per filtrare un messaggio, restituisci null.

In che modo le funzioni definite dall'utente trasformano un messaggio

Il risultato dell'esecuzione di una UDF su un messaggio può essere uno dei seguenti:

  • La UDF trasforma un messaggio.

  • La FDU restituisce null.

    • SMT di argomento: Pub/Sub restituisce un messaggio di esito positivo al publisher e include un ID messaggio nella risposta per i messaggi filtrati. Pub/Sub non memorizza il messaggio né lo invia a nessun sottoscrittore.

    • SMT di sottoscrizione: Pub/Sub conferma la consegna del messaggio senza inviarlo a un sottoscrittore.

  • La UDF genera un errore.

    • SMT di argomenti: Pub/Sub restituisce l'errore al publisher e non pubblica nessuno dei messaggi.

    • SMT di sottoscrizione: Pub/Sub conferma negativamente il messaggio.

Limiti di risorse

Pub/Sub applica limiti di risorse alle funzioni definite dall'utente per garantire operazioni di trasformazione efficienti. Le limitazioni includono:

  • Massimo 20 KB di codice per UDF
  • Massimo 500 ms di esecuzione per messaggio
  • Nessuna chiamata ad API esterne
  • Nessuna importazione di librerie esterne

Funzioni definite dall'utente di esempio

Di seguito sono riportati alcuni esempi di UDF per la pubblicazione e l'iscrizione.

Funzione: converti un numero intero del giorno della settimana nella stringa corrispondente

Quando aggiungi la seguente UDF a un argomento o a una sottoscrizione, durante la pubblicazione o l'invio dei messaggi vengono apportate le seguenti modifiche:

  1. Pub/Sub applica la funzione al messaggio. Se il messaggio non contiene un payload JSON, la UDF genera un errore.

  2. La UDF cerca un campo denominato dayOfWeek e, se il valore di questo campo è un numero compreso tra 0 e 6, lo converte in un giorno della settimana corrispondente, ad esempio Monday. Se il campo non esiste o il numero non rientra nell'intervallo da 0 a 6, il codice imposta il campo dayOfWeek su Unknown.

  3. La UDF serializza nuovamente il payload modificato nel messaggio.

  4. Pub/Sub passa il messaggio aggiornato al passaggio successivo della pipeline.

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;
}

Funzione: oscurare un numero di previdenza sociale

Quando aggiungi la seguente UDF a un argomento o a una sottoscrizione, durante la pubblicazione o l'invio dei messaggi vengono apportate le seguenti modifiche:

  1. Pub/Sub applica la funzione al messaggio. Se il messaggio non ha un payload JSON, la UDF genera un errore.

  2. La UDF rimuove il campo ssn dal payload del messaggio (se esistente).

  3. La UDF serializza nuovamente il payload modificato nel messaggio.

  4. Pub/Sub passa il messaggio aggiornato al passaggio successivo della pipeline.

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

Funzione: filtra e conferma automaticamente i messaggi specifici

Quando aggiungi la seguente UDF a un argomento o a una sottoscrizione, durante la pubblicazione o l'invio dei messaggi vengono apportate le seguenti modifiche:

  1. Pub/Sub applica la funzione al messaggio. Se il messaggio non contiene un payload JSON, la UDF genera un errore.

  2. La UDF controlla se il payload contiene un campo denominato region.

  3. Se il valore del campo region non è US, la funzione restituisce null, il che fa sì che Pub/Sub filtri il messaggio.

  4. Se il valore del campo region è US, Pub/Sub passa il messaggio originale al passaggio successivo della pipeline.

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

Funzione: convalida i contenuti del messaggio per assicurarti che l'importo non sia superiore a 100

Quando aggiungi la seguente UDF a un argomento o a una sottoscrizione, durante la pubblicazione o l'invio dei messaggi vengono apportate le seguenti modifiche:

  1. Pub/Sub applica la funzione al messaggio. Se il messaggio non contiene un payload JSON, la UDF genera un errore.

  2. La UDF controlla se il messaggio contiene un campo denominato amount.

  3. Se il valore del campo amount è maggiore di 100, la funzione genera un errore.

  4. Se il valore del campo amount non è maggiore di 100, la funzione restituisce il messaggio originale.

  5. Pub/Sub contrassegna quindi il messaggio come non riuscito o lo inoltra al passaggio successivo della pipeline.

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

Passaggi successivi