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 all'interno di Pub/Sub, in modo simile a BigQuery JavaScript UDFs.

Le UDF 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:

  • Codice: il codice JavaScript che definisce la logica di trasformazione.

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

Creare la funzione JavaScript

Il codice UDF 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

La funzione accetta i seguenti 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

La funzione deve restituire uno dei seguenti valori:

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

Requisiti di input / output

  • Se la UDF trasforma il payload del messaggio, l'input e l'output del payload devono essere stringhe con codifica UTF-8.
  • Se la UDF non trasforma il payload del messaggio, il payload può utilizzare qualsiasi codifica.
  • Le coppie chiave-valore degli attributi devono essere stringhe con codifica UTF-8.

In che modo le UDF trasformano un messaggio

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

  • La UDF trasforma un messaggio.

  • La UDF 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 della sottoscrizione: Pub/Sub riconosce la consegna del messaggio senza inviarlo a un sottoscrittore.

  • La UDF genera un errore.

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

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

Creare una SMT UDF

Le SMT possono essere configurate su argomenti o sottoscrizioni Pub/Sub.

  • Le SMT dell'argomento vengono eseguite prima che Pub/Sub memorizzi il messaggio e i risultati sono disponibili per tutti i sottoscrittori.

  • Le SMT della sottoscrizione vengono eseguite prima della consegna del messaggio e i risultati sono disponibili solo per quella sottoscrizione.

Console

  1. Nella Google Cloud console, vai alla pagina Argomenti Pub/Sub.

    Vai ad Argomenti

  2. Crea un argomento o una sottoscrizione.

    • Per creare un argomento, fai clic su Crea argomento. Si apre la pagina Crea argomento.

    • Per creare una sottoscrizione:

      1. Fai clic sul nome dell'argomento in cui vuoi la sottoscrizione.

      2. Fai clic su Crea sottoscrizione. Si apre la pagina Aggiungi sottoscrizione all'argomento.

  3. In Trasformazioni, fai clic su Aggiungi una trasformazione.

  4. In Tipo di trasformazione, seleziona UDF JavaScript.

  5. Nel campo Nome funzione, inserisci il nome della funzione JavaScript chiamata dalla SMT. Esempio: redactSSN.

  6. Nell'area di testo, inserisci il codice per la UDF. Esempio:

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

    Il codice deve contenere una funzione il cui nome corrisponde al campo Nome funzione.

  7. Se non vuoi che la SMT sia attiva immediatamente, seleziona Disattiva trasformazione. Quando questa opzione è selezionata, la SMT viene creata con l'argomento, ma non viene eseguita sui messaggi in entrata. Dopo aver creato l'argomento, puoi modificarlo per abilitare la SMT.

  8. Per creare l'argomento o la sottoscrizione, fai clic su Crea.

gcloud

Creare un file di definizione

Crea un file YAML o JSON che definisca la SMT UDF.

YAML 

- javascriptUdf:
    code: { FUNCTION_CODE }
    functionName: FUNCTION_NAME

JSON 

{
  "javascriptUdf": {
    "code": {
      FUNCTION_CODE
    }
    "functionName": FUNCTION_NAME
  }
}

Sostituisci quanto segue:

  • FUNCTION_CODE: il codice JavaScript per la UDF. Il codice deve contenere una funzione il cui nome corrisponde al campo functionName. Esempio:

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

  • FUNCTION_NAME: il nome della funzione JavaScript chiamata dalla SMT. Esempio: redactSSN.

Creare un argomento o una sottoscrizione

Per creare un argomento, esegui il gcloud pubsub topics create comando.

gcloud pubsub topics create TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Sostituisci quanto segue:

  • TOPIC_ID: l'ID o il nome dell'argomento che vuoi creare.
  • TRANSFORMS_FILE: il percorso del file di definizione.

Per creare una sottoscrizione, esegui il gcloud pubsub subscriptions create comando.

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=projects/PROJECT_ID/topics/TOPIC_ID \
  --message-transforms-file=TRANSFORMS_FILE

Sostituisci quanto segue:

  • SUBSCRIPTION_ID: l'ID o il nome della sottoscrizione da creare.

  • PROJECT_ID: l'ID del progetto che contiene l' argomento.

  • TOPIC_ID: l'ID dell'argomento a cui sottoscrivere.

  • TRANSFORMS_FILE: il percorso del file di definizione.

Facoltativamente, puoi convalidare e testare la SMT prima di crearla. Per ulteriori informazioni, consulta le seguenti pagine:

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 tempo di esecuzione massimo di 500 ms per messaggio
  • Supporto solo per le funzionalità integrate standard ECMAScript
  • Nessuna chiamata ad API esterne
  • Nessuna importazione di librerie esterne

UDF di esempio

Di seguito sono riportate alcune UDF di esempio per la pubblicazione e la sottoscrizione. Puoi trovare altri esempi nella libreria UDF.

Funzione: convertire 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 la consegna 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 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 è compreso tra 0 e 6, il codice imposta il campo dayOfWeek su Unknown.

  3. La UDF serializza di nuovo 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 una sottoscrizione, durante la pubblicazione o la consegna 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 UDF rimuove il campo ssn dal payload del messaggio (se esiste).

  3. La UDF serializza di nuovo 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 riconoscere automaticamente messaggi specifici

Quando aggiungi la seguente UDF a un argomento o a una sottoscrizione, durante la pubblicazione o la consegna 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 UDF verifica 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: convalidare i contenuti dei messaggi per assicurarsi che l'importo non sia superiore a 100

Quando aggiungi la seguente UDF a un argomento o a una sottoscrizione, durante la pubblicazione o la consegna 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 UDF verifica 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