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 principaux :

1. La classe de message à laquelle un analyseur est abonné (entrée).
2. La version de type du flux d'enregistrement proto émis par l'analyseur (sortie).
3. Le script Whistle permettant de transformer les messages sources de la classe de message spécifiée (entrée) en enregistrements proto de la version de type définie (sortie).

Le script Whistle est appliqué à chaque message du flux de classe de message 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 Modéliser des classes de messages sources.

Important : À partir de la version 1.4.1 de Manufacturing Data Engine (MDE), les en-têtes de message 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 de périphérie. Veillez à utiliser l'expression de filtre Whistle générique avec précaution afin d'éviter toute perte de données.

Vous pouvez créer un analyseur à l'aide de l'API de 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 cet analyseur est abonné.
• TYPE_NAME: nom du type partagé par les enregistrements proto émis par cet analyseur.
• TYPE_VERSION: version du type partagé 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 ANALYSEURS dans le menu supérieur. La liste des analyseurs disponibles s'affiche :

   

2. Pour chaque analyseur disponible, les informations suivantes s'affichent dans la liste :

   • Name: nom de l'analyseur.
   • Message Class Name: nom de la classe de message à partir de laquelle l'analyseur 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 de modification 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 AJOUTER UN ANALYSEUR.

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

   

5. Pour définir le nouvel analyseur, vous devez fournir les paramètres suivants :

   • Name: nom de l'analyseur. Ne peut pas être modifié une fois créé.
   • Message Class: nom de la classe de message à partir de laquelle l'analyseur est alimenté. Ne peut pas être modifié une fois l'analyseur créé. Sélectionnez la classe de message dans la liste des classes de messages disponibles.
   • Parser Code: fichier Whistle qui définit le mappage associé à l'analyseur. Peut être modifié à tout moment. La modification du code Whistle ne génère pas de nouvelle version des analyseurs. En effet, les analyseurs ne sont pas versionnés.
   • Type: type de sortie émis par l'analyseur. Ne peut pas être modifié 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 la page. Un message de confirmation s'affiche si le nouvel analyseur 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 d'entrée (au format objet JSON).

Console

Vous pouvez tester l'analyseur directement à partir du menu Actions et du menu Modifier l'analyseur.

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

   

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

3. Saisissez le message dans la zone Entrée , puis cliquez sur le bouton 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 Manufactueing 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 du type partagé par les enregistrements proto émis par cet analyseur.
• TYPE_VERSION: version du type partagé 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 présente les paramètres requis pour configurer l'analyseur :

   

• Name: nom de l'analyseur. Ne peut pas être modifié une fois créé.
• Message Class: nom de la classe de message à partir de laquelle l'analyseur est alimenté. Ne peut pas être modifié une fois l'analyseur créé.
• Parser Code: fichier Whistle qui définit le mappage associé à l'analyseur. Peut être modifié à tout moment. La modification du code Whistle ne génère pas de nouvelle version des analyseurs. Les analyseurs ne sont pas versionnés.
• Type: type de sortie émis par l'analyseur. Ne peut pas être modifié une fois l'analyseur créé.
• Version: version du type de résultat émis 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éé.