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:

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.

Crea la funzione JavaScript

Il codice della 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, quest'ultimo 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 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.

Crea un SMT UDF

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

Le trasformazioni SMT degli argomenti vengono eseguite prima che Pub/Sub memorizzi il messaggio e i risultati sono disponibili per tutti i sottoscrittori.
I test SMT delle sottoscrizioni vengono eseguiti prima del recapito del messaggio e i risultati sono disponibili solo per quella sottoscrizione.

Console

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

Vai ad Argomenti
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 a cui vuoi abbonarti.
  2. Fai clic su Crea sottoscrizione. Si apre la pagina Aggiungi sottoscrizione all'argomento.
In Trasformazioni, fai clic su Aggiungi una trasformazione.
In Tipo di trasformazione, seleziona Funzione JavaScript definita dall'utente.
Nel campo Nome funzione, inserisci il nome della funzione JavaScript chiamata da SMT. Esempio: redactSSN.

Nell'area di testo, inserisci il codice per la funzione definita dall'utente. 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 corrisponda al campo Nome funzione.

Se non vuoi che la SMT sia attiva immediatamente, seleziona Disattiva trasformazione. Se questa opzione è selezionata, la regola SMT viene creata con l'argomento, ma non viene eseguita sui messaggi in arrivo. Dopo aver creato l'argomento, puoi modificarlo per attivare la SMT.
Per creare l'argomento o l'abbonamento, fai clic su Crea.

gcloud

Crea 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 funzione definita dall'utente. Il codice deve contenere una funzione il cui nome corrisponda 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 da SMT. Esempio: redactSSN.

Crea un argomento o una sottoscrizione

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

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 un abbonamento, esegui il comando gcloud pubsub subscriptions create.

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 dell'abbonamento da creare.
PROJECT_ID: l'ID del progetto che contiene l'argomento.
TOPIC_ID: l'ID dell'argomento a cui iscriversi.
TRANSFORMS_FILE: il percorso del file di definizione.

(Facoltativo) Puoi convalidare e testare l'SMT prima di crearlo. Per saperne di più, consulta le pagine seguenti:

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. Puoi trovare altri esempi nella raccolta di UDF.

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, vengono apportate le seguenti modifiche durante la pubblicazione o la distribuzione del messaggio:

Pub/Sub applica la funzione al messaggio. Se il messaggio non ha un payload JSON, la UDF genera un errore.
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.
La UDF serializza il payload modificato nel messaggio.
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, vengono apportate le seguenti modifiche durante la pubblicazione o la distribuzione del messaggio:

Pub/Sub applica la funzione al messaggio. Se il messaggio non ha un payload JSON, la UDF genera un errore.
La funzione definita dall'utente rimuove il campo ssn dal payload del messaggio (se esiste).
La UDF serializza il payload modificato nel messaggio.
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, vengono apportate le seguenti modifiche durante la pubblicazione o la distribuzione del messaggio:

Pub/Sub applica la funzione al messaggio. Se il messaggio non ha un payload JSON, la UDF genera un errore.
La funzione definita dall'utente controlla se il payload contiene un campo denominato region.
Se il valore del campo region non è US, la funzione restituisce null, facendo in modo che Pub/Sub filtri il messaggio.
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 il contenuto del messaggio per assicurarti che l'importo non sia superiore a 100

Quando aggiungi la seguente UDF a un argomento o a un abbonamento, vengono apportate le seguenti modifiche durante la pubblicazione o la distribuzione del messaggio:

Pub/Sub applica la funzione al messaggio. Se il messaggio non ha un payload JSON, la UDF genera un errore.
La funzione definita dall'utente controlla se il messaggio contiene un campo denominato amount.
Se il valore del campo amount è maggiore di 100, la funzione genera un errore.
Se il valore del campo amount non è maggiore di 100, la funzione restituisce il messaggio originale.
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

Scegliere tra SMT per argomenti e abbonamenti
Creare un argomento con le SMT
Creare un abbonamento con SMT
Esplora altri esempi nella libreria UDF

Panoramica delle funzioni definite dall'utente Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Crea la funzione JavaScript

Input

Output

Requisiti di input / output

In che modo le UDF trasformano un messaggio

Crea un SMT UDF

Console

gcloud

Crea un file di definizione

YAML

JSON

Crea un argomento o una sottoscrizione

Limitazioni

Funzioni definite dall'utente di esempio

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

Funzione: oscurare un codice fiscale

Funzione: filtrare e confermare automaticamente la ricezione di messaggi specifici

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

Passaggi successivi

Panoramica delle funzioni definite dall'utente