Crea un parser

Questa guida spiega come creare un parser. I parser eseguono la trasformazione e la mappatura dei dati. I passaggi esatti di trasformazione sono definiti nella documentazione dello script whistle per Manufacturing Data Engine (MDE).

Crea un parser

I parser eseguono mappature origine-destinazione tramite uno script Whistle. Quando crei un parser, devi definire tre elementi principali:

1. La classe di messaggi al cui flusso di messaggi si iscrive un parser (input).
2. Versione del tipo del flusso di record proto emesso (output) dal parser.
3. Lo script Whistle per trasformare i messaggi di origine dalla classe di messaggi (input) specificata in record proto della versione del tipo (output) definita.

Lo script Whistle viene applicato a ogni messaggio nel flusso della classe di messaggi di origine e genera record proto di una versione di tipo specifica. Ti consigliamo di dedicare del tempo alla modellazione delle classi di messaggi di origine in modo che condividano una struttura semantica e schematica comune. Classi di messaggi di origine ben definite aiutano a ridurre al minimo la logica condizionale complessa nei parser. Per ulteriori indicazioni, consulta la sezione Classi di messaggi di origine della modellazione.

Importante: a partire dalla release 1.4.1 di Manufacturing Data Engine (MDE), le intestazioni dei messaggi Pub/Sub vengono ora archiviate in un attributo riservato denominato mdeHeaders. Se i messaggi di input contengono questo attributo, un'espressione come embeddedMetadata: $root[where ($.field !=...)] sovrascriverà l'attributo riservato e comporterà la perdita dei dati dell'intestazione Pub/Sub forniti con il messaggio edge. Assicurati di utilizzare l'espressione di filtro generica Whistle con cautela per evitare la perdita di dati.

Puoi creare un parser utilizzando l'API di configurazione o 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"
}

Sostituisci quanto segue:

• PARSER_NAME: il nome del parser.
• SOURCE_MESSAGE_CLASS_NAME: il nome della classe di messaggi di origine al cui flusso di messaggi è iscritto questo parser.
• TYPE_NAME: il nome del tipo condiviso dai record proto emessi da questo parser.
• TYPE_VERSION: la versione del tipo condivisa dai record proto emessi da questo parser.
• WHISTLE_SCRIPT: lo script Whistle che definisce la trasformazione.

Console

1. Per creare un nuovo parser utilizzando la console, seleziona la sezione PARSER nel menu in alto. Viene visualizzato un elenco dei parser disponibili:

   

2. Per ogni parser disponibile, nell'elenco vengono visualizzate le seguenti informazioni:

   • Name:il nome del parser.
   • Message Class Name: il nome della classe di messaggi da cui il parser recupera i dati.
   • Type: tipo di destinazione emesso dal parser.
   • Type Version: versione del tipo di destinazione emessa dal parser.
   • Enabled: stato del parser (abilitato o disabilitato).
   • Actions: Azioni disponibili per il parser:
     • "Visualizza/Modifica": apre il menu di modifica per un determinato parser.
     • Disattiva/Attiva: consente di disattivare un parser attivato o di attivare un parser disattivato.
     • "Test parser": apre un'interfaccia dedicata per testare il parser utilizzando un file JSON specifico.
     • Elimina: elimina il parser da MDE.

3. Per creare un nuovo parser, fai clic su AGGIUNGI NUOVO PARSER.

4. Per aprire la sezione di modifica di un determinato parser, fai clic su Visualizza/Modifica nell'icona Azioni. Il menu laterale che mostra tutti i parametri richiesti per creare un nuovo parser viene visualizzato sul lato destro dello schermo:

   

5. Per definire il nuovo parser, è necessario fornire i seguenti parametri:

   • Name: il nome del parser. Non può essere modificato dopo la creazione.
   • Message Class: nome della classe di messaggi da cui il parser recupera i dati. Non può essere modificato dopo la creazione del parser. Seleziona la classe Message dall'elenco delle classi di messaggi disponibili.
   • Parser Code: file Whistle che definisce la mappatura associata al parser. Può essere modificato in qualsiasi momento. La modifica del codice Whistle non genererà una nuova versione dei parser. I parser non sono versionati.
   • Type: Type di output emesso dal parser. Non può essere modificato dopo la creazione del parser. Seleziona il tipo dall'elenco dei tipi disponibili. Per i nuovi parser, l'ultima versione del tipo è selezionata per impostazione predefinita.

Per creare il parser, modifica i parametri del parser e fai clic su CREA in basso. Se il nuovo parser è stato creato correttamente, viene visualizzato un messaggio di conferma.

Testare un parser

Puoi testare un parser fornendo uno script Whistle e un messaggio di input di esempio:

REST

POST /configuration/v1/parsers:test

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

Sostituisci quanto segue:

• SCRIPT: Script di fischio da testare (formattato come stringa).
• TEST_MESSAGE: messaggio di test di input (formattato come oggetto JSON).

Console

Puoi testare il parser direttamente dal menu Azioni e dal menu Modifica parser.

1. Per testare un parser, fai clic su TEST. Si apre una schermata di test:

   

2. Fornisci un messaggio JSON di esempio per testare il parser.

3. Introduci il messaggio nella casella Input e fai clic sul pulsante ESEGUI TEST.

• Se la trasformazione ha esito positivo, il messaggio di output viene visualizzato nella casella Risultato.
• Se la trasformazione non va a buon fine, viene visualizzato un messaggio di errore con la probabile causa dell'errore.

1. Utilizza un file JSON valido come messaggio di test con una struttura che possa essere elaborata dal file Whistle del parser. Ad esempio, questo è un campione di un payload numerico generato da Manufacturing Connect Edge che può essere testato nel parser 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
}

Modificare un parser

Puoi aggiornare un parser esistente, incluso l'aggiornamento dello script Whistle:

REST

PATCH /configuration/v1/parsers/NAME

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

Sostituisci quanto segue:

• DISABLED: Stato del parser (true o false).
• NAME: il nome del parser.
• TYPE_NAME: il nome del tipo condiviso dai record proto emessi da questo parser.
• TYPE_VERSION: versione del tipo condivisa dai record proto emessi da questo parser.
• WHISTLE_SCRIPT: script Whistle che definisce la trasformazione.

Console

1. Per aprire la sezione di modifica di un determinato parser, fai clic su Visualizza/Modifica nell'icona Azioni:

   

2. Si apre il menu laterale Modifica parser che mostra i parametri richiesti per configurare il parser:

   

• Name: il nome del parser. Non può essere modificato dopo la creazione.
• Message Class: nome della classe di messaggi da cui il parser recupera i dati. Non può essere modificato dopo la creazione del parser.
• Parser Code: file Whistle che definisce la mappatura associata al parser. Può essere modificato in qualsiasi momento. La modifica del codice Whistle non genererà una nuova versione dei parser. I parser non sono versionati.
• Type: Type di output emesso dal parser. Non può essere modificato dopo la creazione del parser.
• Version: versione del tipo di output emessa dal parser. Può essere modificato in qualsiasi momento per le versioni successive.

1. Per modificare un parser, modifica i parametri del parser e fai clic su SALVA.
2. Se il parser è stato creato correttamente, viene visualizzato un messaggio di conferma.