Panoramica delle funzioni definite dall'utente

Una funzione definita dall'utente (UDF) JavaScript è un tipo di trasformazione di un singolo messaggio (SMT). Le UDF forniscono 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 del processo.

Le 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 UDF trasformano un messaggio

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

  • La funzione definita dall'utente trasforma un messaggio.

  • La funzione definita dall'utente restituisce null.

    • SMT dell'argomento: Pub/Sub restituisce l'esito positivo al publisher e include un ID messaggio nella risposta per i messaggi filtrati. Pub/Sub non archivia il messaggio né lo invia ad alcun sottoscrittore.

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

  • La funzione definita dall'utente genera un errore.

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

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

Limitazioni

Pub/Sub applica limiti di risorse alle UDF per garantire operazioni di trasformazione efficienti. Le limitazioni includono:

  • Un massimo di 20 kB di codice per UDF
  • Un massimo di 500 ms di tempo di esecuzione per messaggio
  • Supporto solo per le funzioni integrate standard ECMAScript
  • Nessuna chiamata ad API esterne
  • Nessuna importazione di librerie esterne

Funzioni definite dall'utente di esempio

Ecco alcune UDF di esempio per la pubblicazione e la sottoscrizione.

Funzione: converte un numero intero che rappresenta un giorno della settimana nella stringa corrispondente

Quando aggiungi la seguente UDF a un argomento o a un abbonamento, durante la pubblicazione o la distribuzione del messaggio 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 funzione definita dall'utente cerca un campo denominato dayOfWeek e, se il valore di questo campo è un numero compreso tra 0 e 6, lo converte nel 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 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 codice fiscale

Quando aggiungi la seguente UDF a un argomento o a un abbonamento, durante la pubblicazione o la distribuzione del messaggio 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 funzione definita dall'utente rimuove il campo ssn dal payload del messaggio (se esiste).

  3. La UDF serializza 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: filtrare e confermare automaticamente la ricezione di messaggi specifici

Quando aggiungi la seguente UDF a un argomento o a un abbonamento, durante la pubblicazione o la distribuzione del messaggio 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 funzione definita dall'utente controlla se il payload contiene un campo denominato region.

  3. Se il valore del campo region non è US, la funzione restituisce null, facendo in modo 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: valida il contenuto del messaggio per assicurarsi che l'importo non sia superiore a 100

Quando aggiungi la seguente UDF a un argomento o a un abbonamento, durante la pubblicazione o la distribuzione del messaggio 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 funzione definita dall'utente 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 il messaggio come non riuscito oppure lo passa 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