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:

• Code:Der JavaScript-Code, der die Transformationslogik definiert.

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

JavaScript-Funktion erstellen

Der UDF-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

Die Funktion akzeptiert folgende 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 Zuordnung von Schlüssel-Wert-Paaren, die Nachrichtenattribute darstellen.

• metadata-Argument:Ein JavaScript-Objekt, das unveränderliche Metadaten zur Pub/Sub-Nachricht enthält:

  • 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

Die Funktion muss einen der folgenden Werte zurückgeben:

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

Anforderungen an Eingabe / Ausgabe

• Wenn die UDF die Nutzlast der Nachricht transformiert, müssen die Nutzlast-Ein- und -Ausgabe UTF-8-codierte Strings sein.
• Wenn die UDF die Nutzlast der Nachricht nicht transformiert, kann die Nutzlast eine beliebige Codierung verwenden.
• Attribut-Schlüssel/Wert-Paare müssen UTF-8-codierte Strings sein.

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 Nachrichtenzustellung, ohne die Nachricht 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.

UDF-SMT erstellen

SMTs können für Pub/Sub-Themen oder ‑Abos konfiguriert werden.

• SMTs für Themen werden ausgeführt, bevor Pub/Sub die Nachricht speichert. Die Ergebnisse sind für alle Abonnenten verfügbar.

• SMTs für Abos werden vor der Zustellung der Nachricht ausgeführt und die Ergebnisse sind nur für dieses Abo verfügbar.

- javascriptUdf:
    code: { FUNCTION_CODE }
    functionName: FUNCTION_NAME

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

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

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

Optional können Sie das SMT validieren und testen, bevor Sie es erstellen. Weitere Informationen finden Sie auf den folgenden Seiten:

• Thema mit SMTs erstellen
• Abo mit SMTs erstellen

Beschränkungen

In Pub/Sub gelten Ressourcenlimits für UDFs, 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. Weitere Beispiele finden Sie in der UDF-Bibliothek.

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 umgewandelt. 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 ursprüngliche Nachricht 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

• Zwischen Themen- und Abo-SMTs wählen

• Thema mit SMTs erstellen

• Abo mit SMTs erstellen

• Weitere Beispiele finden Sie in der UDF-Bibliothek.