Benutzerdefinierte Funktionen (UDFs) – Übersicht

Eine benutzerdefinierte JavaScript-Funktion (UDF) ist eine Art von Single Message Transform (SMT). 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 für die Eingabe aus und geben das Ergebnis des Prozesses zurück.

UDFs haben die folgenden wichtigen Eigenschaften:

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

  • 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 Attribute:

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

Wie UDFs eine Nachricht transformieren

Das Ergebnis der Ausführung einer UDF für eine Nachricht kann eines der folgenden sein:

  • Die UDF transformiert eine Nachricht.

  • Die UDF gibt null zurück.

    • SMTs für Themen: Pub/Sub gibt „success“ an den Publisher zurück und enthält eine Nachrichten-ID in der Antwort für die gefilterten Nachrichten. Pub/Sub speichert die Nachricht nicht und sendet sie 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.

    • Themen-SMTs: 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.

Beschränkungen

In Pub/Sub werden Ressourcenlimits für UDFs erzwungen, um effiziente Transformationsvorgänge zu gewährleisten. Dazu gehören:

  • Maximal 20 KB Code pro UDF
  • Maximale Ausführungszeit von 500 ms pro Nachricht
  • Unterstützung nur für integrierte ECMAScript-Standards
  • Keine Aufrufe externer APIs
  • Keine Importe externer Bibliotheken

Beispiel-UDFs

Hier sind einige Beispiel-UDFs für die Veröffentlichung und das Abonnieren.

Funktion: Konvertiert eine Ganzzahl für einen Wochentag in den entsprechenden String.

Wenn Sie die folgende UDF einem Thema oder Abo hinzufügen, werden beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.

  2. Die benutzerdefinierte Funktion sucht nach einem Feld namens dayOfWeek. Wenn der Wert dieses Felds eine Zahl zwischen 0 und 6 ist, wird er in den entsprechenden Wochentag wie Monday konvertiert. Wenn das Feld nicht vorhanden ist oder die Zahl nicht im Bereich von 0 bis 6 liegt, wird das Feld dayOfWeek im Code auf Unknown gesetzt.

  3. Die UDF serialisiert die geänderte Nutzlast zurück in die Nachricht.

  4. Pub/Sub übergibt die aktualisierte Nachricht an den nächsten Schritt in Ihrer 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;
}

Funktion: Sozialversicherungsnummer unkenntlich machen

Wenn Sie die folgende UDF einem Thema oder Abo hinzufügen, werden beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.

  2. Mit der benutzerdefinierten Funktion wird das Feld ssn aus der Nutzlast der Nachricht entfernt (falls es vorhanden ist).

  3. Die UDF serialisiert die geänderte Nutzlast zurück in die Nachricht.

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

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 die folgende UDF einem Thema oder Abo hinzufügen, werden beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.

  2. Die benutzerdefinierte Funktion 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. Dadurch wird die Nachricht von Pub/Sub gefiltert.

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

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

Funktion: Nachrichteninhalte validieren, um sicherzustellen, dass der Betrag nicht größer als 100 ist

Wenn Sie die folgende UDF einem Thema oder Abo hinzufügen, werden beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen vorgenommen:

  1. Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt 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, gibt 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 übergibt die Originalnachricht an den nächsten Schritt in Ihrer Pipeline.

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