Présentation des fonctions définies par l'utilisateur (UDF)

Une fonction définie par l'utilisateur (UDF) JavaScript est un type de transformation de message unique (SMT). Les fonctions définies par l'utilisateur permettent d'implémenter de manière flexible une logique de transformation personnalisée dans Pub/Sub, comme les fonctions définies par l'utilisateur JavaScript BigQuery.

Les fonctions UDF acceptent un seul message en entrée, effectuent les actions définies sur l'entrée et renvoient le résultat du processus.

Les fonctions définies par l'utilisateur présentent les propriétés clés suivantes:

  • Nom de la fonction:nom de la fonction JavaScript dans le code fourni que Pub/Sub applique aux messages.

  • Code:code JavaScript qui définit la logique de transformation. Ce code doit contenir une fonction avec la signature suivante:

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

Entrées

  • Argument message:objet JavaScript représentant le message Pub/Sub. Il contient les propriétés suivantes:

    • data: (String, obligatoire) Charge utile du message.

    • attributes: (Object<String, String>, facultatif) Mappage de paires clé-valeur représentant les attributs de message.

  • Argument metadata:objet JavaScript contenant des métadonnées immuables sur le message Pub/Sub:

    • message_id: (String, facultatif) ID unique du message.

    • publish_time: (String, facultatif) Heure de publication du message au format RFC 3339 (AAAA-MM-JJHH:mm:ssZ).

    • ordering_key: (String, facultatif) Clé de tri du message, le cas échéant.

Sorties

  • Pour transformer un message, modifiez le contenu de message.data et message.attributes, puis renvoyez l'objet message modifié.

  • Pour filtrer un message, renvoyez null.

Comment les fonctions définies par l'utilisateur transforment un message

Le résultat de l'exécution d'une fonction définie par l'UDF sur un message peut être l'un des éléments suivants:

  • La fonction définie par l'utilisateur transforme un message.

  • La fonction définie par l'utilisateur renvoie null.

    • SMT de sujet: Pub/Sub renvoie un code d'état "success" à l'éditeur et inclut un ID de message dans la réponse pour les messages filtrés. Pub/Sub ne stocke pas le message ni ne l'envoie à aucun abonné.

    • SMT d'abonnement: Pub/Sub confirme la distribution du message sans l'envoyer à un abonné.

  • La fonction définie par l'utilisateur génère une erreur.

    • SMT de sujet: Pub/Sub renvoie l'erreur à l'éditeur et ne publie aucun des messages.

    • SMT d'abonnement: Pub/Sub confirme négativement le message.

Limites de ressources

Pub/Sub applique des limites de ressources aux fonctions définies par l'utilisateur pour garantir des opérations de transformation efficaces. Voici quelques limites:

  • 20 Ko de code maximum par fonction définie par l'utilisateur
  • 500 ms d'exécution maximum par message
  • Aucun appel d'API externes
  • Aucune importation de bibliothèques externes

Exemples de fonctions définies par l'utilisateur

Voici quelques exemples de fonctions définies par l'utilisateur pour la publication et l'abonnement.

Fonction: Convertir un entier de jour de la semaine en chaîne correspondante

Lorsque vous ajoutez la UDF suivante à un sujet ou à un abonnement, les modifications suivantes se produisent lors de la publication ou de la diffusion des messages:

  1. Pub/Sub applique la fonction au message. Si le message ne comporte pas de charge utile JSON, la UDF génère une erreur.

  2. La fonction définie par l'utilisateur recherche un champ appelé dayOfWeek et, si la valeur de ce champ est un nombre compris entre 0 et 6, la convertit en jour de la semaine correspondant, tel que Monday. Si le champ n'existe pas ou si le nombre n'est pas compris entre 0 et 6, le code définit le champ dayOfWeek sur Unknown.

  3. La fonction définie par l'utilisateur sérialise à nouveau la charge utile modifiée dans le message.

  4. Pub/Sub transmet le message mis à jour à l'étape suivante de votre 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;
}

Fonction: Masquer un numéro de sécurité sociale

Lorsque vous ajoutez la UDF suivante à un sujet ou à un abonnement, les modifications suivantes se produisent lors de la publication ou de la diffusion des messages:

  1. Pub/Sub applique la fonction au message. Si le message ne comporte pas de charge utile JSON, la UDF génère une erreur.

  2. La fonction définie par l'utilisateur supprime le champ ssn de la charge utile du message (s'il existe).

  3. La fonction définie par l'utilisateur sérialise à nouveau la charge utile modifiée dans le message.

  4. Pub/Sub transmet le message mis à jour à l'étape suivante de votre pipeline.

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

Fonction: Filtrer et confirmer automatiquement des messages spécifiques

Lorsque vous ajoutez la UDF suivante à un sujet ou à un abonnement, les modifications suivantes se produisent lors de la publication ou de la diffusion des messages:

  1. Pub/Sub applique la fonction au message. Si le message ne comporte pas de charge utile JSON, la UDF génère une erreur.

  2. La fonction définie par l'utilisateur vérifie si la charge utile contient un champ appelé region.

  3. Si la valeur du champ region n'est pas US, la fonction renvoie la valeur nulle, ce qui entraîne le filtrage du message par Pub/Sub.

  4. Si la valeur du champ region est US, Pub/Sub transmet le message d'origine à l'étape suivante de votre pipeline.

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

Fonction: Valider le contenu du message pour s'assurer que le montant n'est pas supérieur à 100

Lorsque vous ajoutez la UDF suivante à un sujet ou à un abonnement, les modifications suivantes se produisent lors de la publication ou de la diffusion des messages:

  1. Pub/Sub applique la fonction au message. Si le message ne comporte pas de charge utile JSON, la UDF génère une erreur.

  2. La fonction définie par l'utilisateur vérifie si le message contient un champ appelé amount.

  3. Si la valeur du champ amount est supérieure à 100, la fonction génère une erreur.

  4. Si la valeur du champ amount n'est pas supérieure à 100, la fonction renvoie le message d'origine.

  5. Pub/Sub marque ensuite le message comme ayant échoué ou transmet le message d'origine à l'étape suivante de votre pipeline.

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

Étape suivante