Créer un analyseur

Ce guide explique comment créer un analyseur. Les analyseurs effectuent la transformation et le mappage des données. Les étapes de transformation exactes sont définies dans la documentation du script whistle pour Manufacturing Data Engine (MDE).

Créer un analyseur

Les analyseurs effectuent des mappages source-cible à l'aide d'un script Whistle. Lorsque vous créez un analyseur, vous devez définir trois éléments de base :

1. La classe de message à laquelle un analyseur s'abonne (entrée).
2. Version du type du flux d'enregistrements proto émis par l'analyseur (sortie).
3. Script Whistle permettant de transformer les messages sources de la classe de message spécifiée (entrée) en enregistrements proto du type de version défini (sortie).

Le script Whistle est appliqué à chaque message du flux de classe de messages source et génère des enregistrements proto d'une version de type spécifique. Nous vous recommandons de prendre le temps de modéliser vos classes de messages sources afin qu'elles partagent une structure sémantique et schématique commune. Des classes de messages sources bien définies permettent de minimiser la logique conditionnelle complexe dans les analyseurs. Pour en savoir plus, consultez la section sur la modélisation des classes de messages sources.

Important : Depuis la version 1.4.1 de Manufacturing Data Engine (MDE), les en-têtes des messages Pub/Sub sont désormais stockés dans un attribut réservé appelé mdeHeaders. Si vos messages d'entrée contiennent cet attribut, une expression telle que embeddedMetadata: $root[where ($.field !=...)] écrasera l'attribut réservé et entraînera la perte des données d'en-tête Pub/Sub fournies avec le message Edge. Veillez à utiliser l'expression de filtre Whistle générique avec précaution pour éviter toute perte de données.

Vous pouvez créer un analyseur à l'aide de l'API Configuration ou de la console :

REST

POST /configuration/v1/parsers

{
  "name": "PARSER_NAME",
  "messageClassName": "SOURCE_MESSAGE_CLASS_NAME",
  "typeReference": {
    "name": "TYPE_NAME",
    "version": TYPE_VERSION
  },
  "script": "WHISTLE_SCRIPT"
}

Remplacez les éléments suivants :

• PARSER_NAME : nom de l'analyseur.
• SOURCE_MESSAGE_CLASS_NAME : nom de la classe de message source à laquelle ce parseur est abonné pour le flux de messages.
• TYPE_NAME : nom de type partagé par les enregistrements proto émis par cet analyseur.
• TYPE_VERSION : version de type partagée par les enregistrements proto émis par cet analyseur.
• WHISTLE_SCRIPT : script Whistle qui définit la transformation.

Console

1. Pour créer un analyseur à l'aide de la console, sélectionnez la section ANALYSERS dans le menu du haut. Une liste des analyseurs disponibles s'affiche :

   

2. Pour chaque analyseur disponible, les informations suivantes sont affichées dans la liste :

   • Name : nom de l'analyseur.
   • Message Class Name : nom de la classe de message à partir de laquelle le parseur est alimenté.
   • Type : type de destination émis par l'analyseur.
   • Type Version : version du type de destination émise par l'analyseur.
   • Enabled : état de l'analyseur (activé ou désactivé).
   • Actions : actions disponibles pour l'analyseur :
     • Afficher/Modifier : ouvre le menu d'édition d'un analyseur donné.
     • Désactiver/Activer : permet de désactiver un analyseur activé ou d'activer un analyseur désactivé.
     • Tester l'analyseur : ouvre une interface dédiée pour tester l'analyseur à l'aide d'un fichier JSON donné.
     • Supprimer : supprime l'analyseur de MDE.

3. Pour créer un analyseur, cliquez sur ADD NEW PARSER (AJOUTER UN ANALYSEUR).

4. Pour ouvrir la section de modification d'un analyseur, cliquez sur Afficher/Modifier dans l'icône Actions. Le menu latéral qui présente tous les paramètres requis pour créer un analyseur s'affiche sur le côté droit de l'écran :

   

5. Pour définir le nouveau parseur, les paramètres suivants doivent être fournis :

   • Name : nom de l'analyseur. Une fois créé, il ne peut plus être modifié.
   • Message Class : nom de la classe de message à partir de laquelle le parseur est alimenté. Ce paramètre ne peut pas être modifié une fois l'analyseur créé. Sélectionnez la classe de message dans la liste des classes de message disponibles.
   • Parser Code : fichier Whistle qui définit le mappage associé à l'analyseur. Vous pourrez le modifier à tout moment. La modification du code Whistle ne générera pas de nouvelle version des analyseurs. En effet, les analyseurs ne sont pas versionnés.
   • Type : Type de sortie émis par l'analyseur. Vous ne pourrez plus le modifier une fois l'analyseur créé. Sélectionnez le type dans la liste des types disponibles. Pour les nouveaux analyseurs, la dernière version du type est sélectionnée par défaut.

Pour créer l'analyseur, modifiez ses paramètres, puis cliquez sur CRÉER en bas de l'écran. Un message de confirmation s'affiche si le nouveau parseur a été créé.

Tester un analyseur

Vous pouvez tester un analyseur en fournissant un script Whistle et un exemple de message d'entrée :

REST

POST /configuration/v1/parsers:test

{
  "script": "SCRIPT",
  "testMessage": TEST_MESSAGE
}

Remplacez les éléments suivants :

• SCRIPT : script Whistle à tester (au format chaîne).
• TEST_MESSAGE : message de test saisi (au format objet JSON).

Console

Vous pouvez tester l'analyseur directement depuis le menu Actions, ainsi que dans le menu Modifier l'analyseur.

1. Pour tester un analyseur, cliquez sur TEST. Un écran de test s'ouvre :

   

2. Fournissez un exemple de message JSON pour tester l'analyseur.

3. Saisissez le message dans la zone Input (Entrée), puis cliquez sur le bouton RUN TEST (EXÉCUTER LE TEST).

• Si la transformation réussit, le message de sortie s'affiche dans la zone Résultat.
• Si la transformation échoue, un message d'erreur s'affiche avec la cause probable de l'erreur.

1. Utilisez un fichier JSON valide comme message de test dont la structure peut être traitée par le fichier Whistle de l'analyseur. Voici un exemple de charge utile numérique générée par Manufacturing Connect Edge qui peut être testée dans l'analyseur default-numeric-value-to-default-numeric-records :

{
  "datatype": "int",
  "description": "",
  "deviceID": "0619E715-D1B8-438F-A1AB-E4D65D27EE83",
  "deviceName": "MicroLogix1100",
  "metadata": {
    "location": "ES-BCN-GRA",
    "manufacturer": "AllenBradley",
    "model": "MicroLogix1100",
    "os_revision": "Series B FRN 12.0",
    "source": "mce"
  },
  "registerId": "0997D2ED-B2AB-434C-9754-C1A3C2E9C165",
  "success": true,
  "tagName": "Manufactueing Connect edge_July_test_tag",
  "timestamp": 1691163012045,
  "value": 8004
}

Modifier un analyseur

Vous pouvez mettre à jour un analyseur existant, y compris le script Whistle :

REST

PATCH /configuration/v1/parsers/NAME

{
  "disabled": DISABLED,
  "script": "SCRIPT",
  "typeReference": {
    "name": "TYPE_NAME",
    "version": TYPE_VERSION
  },
  "script": "WHISTLE_SCRIPT"
}

Remplacez les éléments suivants :

• DISABLED : état de l'analyseur (true ou false).
• NAME : nom de l'analyseur.
• TYPE_NAME : nom de type partagé par les enregistrements proto émis par cet analyseur.
• TYPE_VERSION : version de type partagée par les enregistrements proto émis par cet analyseur.
• WHISTLE_SCRIPT : script Whistle qui définit la transformation.

Console

1. Pour ouvrir la section de modification d'un analyseur donné, cliquez sur Afficher/Modifier dans l'icône Actions :

   

2. Le menu latéral Modifier l'analyseur s'ouvre et affiche les paramètres requis pour configurer l'analyseur :

   

• Name : nom de l'analyseur. Une fois créé, il ne peut plus être modifié.
• Message Class : nom de la classe de message à partir de laquelle le parseur est alimenté. Ce paramètre ne peut pas être modifié une fois l'analyseur créé.
• Parser Code : fichier Whistle qui définit le mappage associé à l'analyseur. Vous pourrez le modifier à tout moment. La modification du code Whistle ne générera pas de nouvelle version des analyseurs. Les analyseurs ne sont pas versionnés.
• Type : Type de sortie émis par l'analyseur. Vous ne pourrez plus le modifier une fois l'analyseur créé.
• Version : version du type de sortie émise par l'analyseur. Peut être modifié à tout moment pour les versions supérieures.

1. Pour modifier un analyseur, modifiez ses paramètres, puis cliquez sur ENREGISTRER.
2. Un message de confirmation s'affiche si l'analyseur a été créé.