Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

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 von Pub/Sub auf Nachrichten angewendet wird.

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 die folgenden Eingaben:

message-Argument:Ein JavaScript-Objekt, das die Pub/Sub-Nachricht darstellt. Sie enthält die folgenden Attribute:
- data: (String, erforderlich) Die Nutzlast der Nachricht.
- 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 Bestellschlü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.
Um eine Nachricht zu filtern, geben Sie null zurück.

Anforderungen an Ein- und 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.
Schlüssel/Wert-Paare für Attribute 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 eine Erfolgsmeldung an den Publisher zurück und enthält in der Antwort eine Nachrichten-ID 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.

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

Console

Rufen Sie in der Google Cloud Console die Pub/Sub-Seite Themen auf.

Themen aufrufen
Erstellen Sie entweder ein Thema oder ein Abo.
- Klicken Sie auf Thema erstellen, um ein Thema zu erstellen. Die Seite Thema erstellen wird geöffnet.
- So erstellen Sie ein Abo:
  1. Klicken Sie auf den Namen des Themas, für das Sie das Abo abschließen möchten.
  2. Klicken Sie auf Abo erstellen. Die Seite Abo zum Thema hinzufügen wird geöffnet.
Klicken Sie unter Transformationen auf Transformation hinzufügen.
Wählen Sie für Transformationstyp die Option JavaScript-UDF aus.
Optional: Sie können mit Gemini Enterprise den Code für die UDF generieren lassen:
1. Klicken Sie auf Mit KI generieren.
2. Geben Sie im Textfeld eine Beschreibung ein, was die Funktion tun soll, z. B. „Füge das Attribut ‚processed_at‘ mit der aktuellen Zeit hinzu“.
3. Klicken Sie auf Senden. Der generierte Code wird zusammen mit einer Erklärung des Codes im Bereich Mit KI generieren angezeigt.
4. Überprüfen Sie den Code auf Richtigkeit. Möglicherweise müssen Sie die Beschreibung anpassen und den Code neu generieren.
5. Klicken Sie auf Importieren, um den generierten Code zu verwenden.
Geben Sie im Feld Funktionsname den Namen der JavaScript-Funktion ein, die vom SMT aufgerufen wird. Beispiel: redactSSN.

Wenn Sie Gemini Enterprise zum Generieren des Codes verwendet haben, ist dieses Feld bereits ausgefüllt.
Geben Sie im Textbereich den Code für die benutzerdefinierte Funktion ein. Beispiel:
```
function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}
```
Der Code muss eine Funktion enthalten, deren Name mit dem Feld Funktionsname übereinstimmt.

Wenn Sie Gemini Enterprise zum Generieren des Codes verwendet haben, ist dieses Feld bereits ausgefüllt.
Wenn Sie nicht möchten, dass die SMT sofort aktiv ist, wählen Sie Transformation deaktivieren aus. Wenn diese Option ausgewählt ist, wird die SMT mit dem Thema erstellt, aber nicht für eingehende Nachrichten ausgeführt. Nachdem das Thema erstellt wurde, können Sie es bearbeiten, um die SMT zu aktivieren.
Klicken Sie auf Erstellen, um das Thema oder Abo zu erstellen.

gcloud

Definitionsdatei erstellen

Erstellen Sie eine YAML- oder JSON-Datei, in der die UDF-SMT definiert ist.

YAML

- javascriptUdf:
    code: { FUNCTION_CODE }
    functionName: FUNCTION_NAME

JSON

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

Ersetzen Sie Folgendes:

FUNCTION_CODE: Der JavaScript-Code für die UDF. Der Code muss eine Funktion enthalten, deren Name mit dem Feld functionName übereinstimmt. Beispiel:

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

FUNCTION_NAME: Der Name der JavaScript-Funktion, die vom SMT aufgerufen wird. Beispiel: redactSSN.

Thema oder Abo erstellen

Führen Sie den Befehl gcloud pubsub topics create aus, um ein Thema zu erstellen.

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

Ersetzen Sie Folgendes:

TOPIC_ID: Die ID oder der Name des Themas, das Sie erstellen möchten.
TRANSFORMS_FILE: Der Pfad zur Definitionsdatei.

Führen Sie den Befehl gcloud pubsub subscriptions create aus, um ein Abo zu erstellen.

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

Ersetzen Sie Folgendes:

SUBSCRIPTION_ID: Die ID oder der Name des Abos, das erstellt werden soll.
PROJECT_ID: Die ID des Projekts, das das Thema enthält.
TOPIC_ID: Die ID des Themas, das abonniert werden soll.
TRANSFORMS_FILE: Der Pfad zur Definitionsdatei.

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

Beschränkungen

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

Maximal 20 KB Code pro benutzerdefinierter Funktion
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 das Veröffentlichen und Abonnieren. Weitere Beispiele finden Sie in der UDF-Bibliothek.

Funktion: Ganzzahl für Wochentag in entsprechenden String konvertieren

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

Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.
Die benutzerdefinierte Funktion sucht nach einem Feld namens dayOfWeek und wandelt den Wert dieses Felds, sofern es sich um eine Zahl zwischen 0 und 6 handelt, in den entsprechenden Wochentag um, z. B. Monday. 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.
Die UDF serialisiert die geänderte Nutzlast zurück in die Nachricht.
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 einem Abo hinzufügen, treten beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen auf:

Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.
Die benutzerdefinierte Funktion entfernt das Feld ssn aus der Nutzlast der Nachricht (falls es vorhanden ist).
Die UDF serialisiert die geänderte Nutzlast zurück in die Nachricht.
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 einem Abo hinzufügen, treten beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen auf:

Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.
Die benutzerdefinierte Funktion prüft, ob die Nutzlast ein Feld mit dem Namen region enthält.
Wenn der Wert des Felds region nicht US ist, gibt die Funktion „null“ zurück, sodass Pub/Sub die Nachricht filtert.
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 einem Abo hinzufügen, treten beim Veröffentlichen oder Zustellen von Nachrichten die folgenden Änderungen auf:

Pub/Sub wendet die Funktion auf die Nachricht an. Wenn die Nachricht keine JSON-Nutzlast hat, gibt die UDF einen Fehler aus.
Die benutzerdefinierte Funktion prüft, ob die Nachricht ein Feld mit dem Namen amount enthält.
Wenn der Wert des Felds amount größer als 100 ist, gibt die Funktion einen Fehler aus.
Wenn der Wert des Felds amount nicht größer als 100 ist, gibt die Funktion die ursprüngliche Nachricht zurück.
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.

Benutzerdefinierte Funktionen (UDFs) – Übersicht Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

JavaScript-Funktion erstellen

Eingaben

Ausgaben

Anforderungen an Ein- und Ausgabe

Wie UDFs eine Nachricht transformieren

UDF-SMT erstellen

Console

gcloud

Definitionsdatei erstellen

YAML

JSON

Thema oder Abo erstellen

Beschränkungen

Beispiel-UDFs

Funktion: Ganzzahl für Wochentag in entsprechenden String konvertieren

Funktion: Sozialversicherungsnummer unkenntlich machen

Funktion: Bestimmte Nachrichten herausfiltern und automatisch bestätigen

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

Nächste Schritte

Benutzerdefinierte Funktionen (UDFs) – Übersicht