Écrire des scripts dans Whistle

Ce guide fournit des conseils généraux sur la rédaction d'un script Whistle pour un analyseur. Pour en savoir plus sur la syntaxe Whistle et les fonctions disponibles, consultez la documentation de référence sur Whistle.

Écrire un script Whistle

Avant de commencer à écrire un script Whistle, il est recommandé de :

  1. Comprendre le schéma des messages dans la classe de messages source à laquelle l'analyseur s'abonne Pour éviter les échecs de mappage et, par conséquent, que les messages n'atterrissent dans la file d'attente de lettres mortes, le script Whistle doit être en mesure de mapper tous les messages entrants. Si les schémas de message diffèrent d'un message à l'autre, votre script Whistle doit gérer ces différences.

    Connaître le schéma des messages sources vous aide à comprendre quels champs existent dans les messages sources et quels sont leurs types de données. Vous pouvez ainsi décider comment mapper les champs des messages sources au schéma de type cible. Il est également important de comprendre la sémantique des données pour pouvoir décider efficacement quelles parties du message source doivent être mappées aux attributs du schéma cible.

    Par exemple, connaître la fréquence de modification de la valeur d'un attribut vous aide à déterminer quelles données doivent être mappées en tant que métadonnées intégrées par rapport aux métadonnées cloud. Consultez les sections sur la modélisation des classes de messages sources et la modélisation des données.

  2. Comprendre le schéma de la version de type définie pour l'analyseur Le script Whistle du parser mappe les messages sources au schéma de version de type défini pour le parser. Pour savoir comment construire un enregistrement proto qui répond aux exigences de la version du type, vous devez consulter la spécification du type. En particulier, vous devez noter le schéma du champ data, ainsi que toutes les associations de buckets de métadonnées. Il est particulièrement important de noter si des associations de buckets de métadonnées sont marquées comme required: true. Si vous prévoyez de rechercher des instances de métadonnées par valeur, vous devez noter les schémas des buckets associés.

  3. Écrivez le script Whistle. Le script Whistle effectue la transformation source-cible. Le message source est chargé dans une entrée appelée $root. Consultez la documentation de référence de Whistle pour obtenir une présentation du langage et des fonctions disponibles. Consultez également les autres guides de cette section, comme Associer des enregistrements à des instances de métadonnées.

Bonnes pratiques

Cette section décrit les bonnes pratiques à suivre pour écrire des scripts Whistle.

Effectuer des vérifications nulles lors de l'accès aux propriétés du message

Il est recommandé de vérifier la valeur Null lorsque vous accédez à une propriété de message, chaque fois qu'il est possible que la propriété ne soit pas définie.

//Add metadata from source bucket if metadata.source attribute is present
if(isNotNil(input.metadata) and isNotNil(input.metadata.source)) then {
{
    var metadataArray[]: {
        bucketReference: {
            bucketName: "source";
            version: 1;
        };
            naturalKey: input.metadata.source;
        }
    }
}

Exemples

Les sections suivantes présentent quelques exemples d'opérations de base avec Whistle.

Mappage Whistle simple

Compte tenu du message source suivant…

{
  "sensor": "rotation-speed-sensor",
  "machine": "m-234",
  "timestamp": "1687973092857",
  "value": 1200
}

Et le script Whistle suivant :

package mde

[
    {
        tagName: $root.machine + " - " + $root.sensor;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
    }
]

L'analyseur génère le résultat d'enregistrement proto suivant :

[
  {
    "tagName": "m-234-rotation-speed-sensor",
    "data": {
      "numeric": 1200
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  }
]

Mappage Whistle simple à l'aide de fonctions

Compte tenu du message source suivant :

{
  "sensor": "rotation-speed-sensor",
  "machine": "m-234",
  "timestamp": "1687973092857",
  "value": 1200
}

Et le script Whistle suivant :

package mde

[
    {
        tagName: getTagName($root);
        data: getValue($root);
        timestamps: getTimestamp($root)
    }
]

def getTagName(input) {
    input.machine + "-" + input.sensor;
}

def getTimestamp(input) {
    eventTimestamp: input.timestamp;
}

def getValue(input) {
    numeric: input.value;
}

L'analyseur génère le résultat d'enregistrement proto suivant :

[
  {
    "tagName": "m-234-rotation-speed-sensor",
    "data": {
      "numeric": 1200
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  }
]

Émettre plusieurs enregistrements proto à partir d'un analyseur 1

Compte tenu du message source suivant :

{
  "tag": "plc-34",
  "machine": "controller",
  "timestamp": "1687973092857",
  "values": [200, 499]
}

Et le script Whistle suivant :

package mde

var valueLen: listLen($root.values);
var indexes: range(0, valueLen);

[
    getProtoRecords($root.values[], indexes[], $root)
]

def getProtoRecords(value, index, input) {
        tagName: input.machine + "-" + input.tag + "-" + index;
        data: {
            numeric: value;
        };
        timestamps: {
            eventTimestamp: input.timestamp;
        };
}

L'analyseur génère le résultat d'enregistrement proto suivant :

[
  {
    "tagName": "controller-plc-34-0",
    "data": {
      "value": 200.0
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  },
  {
    "tagName": "controller-plc-34-1",
    "data": {
      "value": 499.0
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  }
]

Émettre plusieurs enregistrements proto à partir d'un analyseur 2

Compte tenu du message source suivant :

{
  "machine": "controller",
  "timestamp": "1687973092857",
  "sensors": [
    {
      "tag": "plc-34",
      "value": 200
    },
    {
      "tag": "plc-35",
      "value": 499
    }
  ]
}

Et le script Whistle suivant :

package mde

[$$
    getProtoRecords($root.sensors[], $root)
]

def getProtoRecords(sensor, input) {
        tagName: input.machine + "-" + sensor.tag;
        data: {
            numeric: sensor.value;
        };
        timestamps: {
            eventTimestamp: input.timestamp;
        };
}

L'analyseur génère le résultat d'enregistrement proto suivant :

[
  {
    "tagName": "controller-plc-34",
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "data": {
      "numeric": 200
    }
  },
  {
    "tagName": "controller-plc-35",
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "data": {
      "numeric": 499
    }
  }
]