Benutzerdefinierte Funktionen (UDFs) – Übersicht

Eine benutzerdefinierte JavaScript-Funktion (UDF) ist eine Art von SMT (Single Message Transform). UDFs bieten eine flexible Möglichkeit, benutzerdefinierte Transformationslogik in Pub/Sub zu implementieren, ähnlich wie BigQuery-JavaScript-UDFs.

UDFs akzeptieren eine einzelne Nachricht als Eingabe, führen die definierten Aktionen auf der Eingabe aus und geben das Ergebnis des Prozesses zurück.

UDFs haben die folgenden Haupteigenschaften:

  • Funktionsname:Der Name der JavaScript-Funktion im bereitgestellten Code, die von Pub/Sub auf Nachrichten angewendet wird.

  • Code:Der JavaScript-Code, der die Transformationslogik definiert. Dieser Code muss eine Funktion mit der folgenden Signatur enthalten:

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

Eingaben

  • message argument:Ein JavaScript-Objekt, das die Pub/Sub-Nachricht darstellt. Sie enthält die folgenden Eigenschaften:

    • data: (String, erforderlich) Die Nachrichtennutzlast.

    • attributes: (Object<String, String>, optional) Eine Map mit Schlüssel/Wert-Paaren, die Nachrichtenattribute darstellen.

  • metadata-Argument:Ein JavaScript-Objekt mit unveränderlichen Metadaten zur Pub/Sub-Nachricht:

    • message_id: (String, optional) Die eindeutige ID der Nachricht.

    • publish_time: (String, optional) Die Veröffentlichungszeit der Nachricht im RFC 3339-Format (JJJJ-MM-TTTHH:mm:ssZ).

    • ordering_key: (String, optional) Der Sortierschlüssel der Nachricht, falls zutreffend.

Ausgaben

  • Wenn Sie eine Nachricht transformieren möchten, bearbeiten Sie den Inhalt von message.data und message.attributes und geben Sie das geänderte message-Objekt zurück.

  • Wenn Sie eine Nachricht filtern möchten, geben Sie null zurück.

So transformieren UDFs eine Nachricht

Das Ergebnis der Ausführung einer UDF auf einer Nachricht kann einer der folgenden Werte sein:

  • Die UDF transformiert eine Nachricht.

  • Die UDF gibt null zurück.

    • SMTs für Themen: Pub/Sub gibt dem Publisher den Status „Erfolg“ zurück und fügt in der Antwort für die gefilterten Nachrichten eine Nachrichten-ID ein. Pub/Sub speichert die Nachricht nicht und sendet sie auch nicht an Abonnenten.

    • SMTs für Abos: Pub/Sub bestätigt die Zustellung der Nachricht, ohne sie an einen Abonnenten zu senden.

  • Die UDF gibt einen Fehler aus.

    • SMTs für Themen: Pub/Sub gibt den Fehler an den Publisher zurück und veröffentlicht keine der Nachrichten.

    • SMTs für Abos: Pub/Sub bestätigt die Nachricht negativ.

Ressourcenlimits

Pub/Sub erzwingt Ressourcenlimits für UDFs, um effiziente Transformationsvorgänge zu ermöglichen. Zu den Einschränkungen gehören:

  • Maximal 20 KB Code pro UDF
  • Maximale Ausführungszeit pro Nachricht: 500 ms
  • Keine Aufrufe externer APIs
  • Keine Importe externer Bibliotheken

Beispiel-UDFs

Hier sind einige Beispiel-UDFs zum Veröffentlichen und Abonnieren.

Funktion: Ganzzahl für Wochentag in den entsprechenden String konvertieren

Wenn Sie einem Thema oder Abo die folgende UDF hinzufügen, werden bei der Veröffentlichung oder Zustellung von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast enthält, löst die UDF einen Fehler aus.

  2. Die UDF sucht nach einem Feld namens dayOfWeek und wandelt den Wert dieses Felds in einen entsprechenden Wochentag wie Monday um, wenn er eine Zahl zwischen 0 und 6 ist. Wenn das Feld nicht vorhanden ist oder die Zahl nicht zwischen 0 und 6 liegt, wird das Feld dayOfWeek durch den Code auf Unknown gesetzt.

  3. Die UDF serialisiert die geänderte Nutzlast wieder in die Nachricht.

  4. Pub/Sub leitet die aktualisierte Nachricht an den nächsten Schritt in Ihrer Pipeline weiter.

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

Funktion: Sozialversicherungsnummer schwärzen

Wenn Sie einem Thema oder Abo die folgende UDF hinzufügen, werden bei der Veröffentlichung oder Zustellung von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast enthält, gibt die UDF einen Fehler zurück.

  2. Das UDF entfernt das Feld ssn aus der Nachrichtennutzlast (falls vorhanden).

  3. Die UDF serialisiert die geänderte Nutzlast wieder in die Nachricht.

  4. Pub/Sub leitet die aktualisierte Nachricht an den nächsten Schritt in Ihrer Pipeline weiter.

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

Funktion: Bestimmte Nachrichten herausfiltern und automatisch bestätigen

Wenn Sie einem Thema oder Abo die folgende UDF hinzufügen, werden bei der Veröffentlichung oder Zustellung von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast enthält, löst die UDF einen Fehler aus.

  2. Die UDF prüft, ob die Nutzlast ein Feld namens region enthält.

  3. Wenn der Wert des Felds region nicht US ist, gibt die Funktion null zurück, wodurch die Nachricht von Pub/Sub herausgefiltert wird.

  4. Wenn der Wert des Felds region US ist, übergibt Pub/Sub die ursprüngliche Nachricht an den nächsten Schritt in der Pipeline.

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

Funktion: Prüfen, ob der Inhalt der Nachricht den Wert 100 nicht überschreitet

Wenn Sie einem Thema oder Abo die folgende UDF hinzufügen, werden bei der Veröffentlichung oder Zustellung von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast enthält, löst die UDF einen Fehler aus.

  2. Die UDF prüft, ob die Nachricht ein Feld namens amount enthält.

  3. Wenn der Wert des Felds amount größer als 100 ist, löst die Funktion einen Fehler aus.

  4. Wenn der Wert des Felds amount nicht größer als 100 ist, gibt die Funktion die ursprüngliche Nachricht zurück.

  5. Pub/Sub markiert die Nachricht dann entweder als fehlgeschlagen oder leitet die ursprüngliche Nachricht an den nächsten Schritt in der Pipeline weiter.

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

Nächste Schritte