Membuat parser

Panduan ini menjelaskan cara membuat parser. Parser melakukan transformasi dan pemetaan data. Langkah-langkah transformasi yang tepat ditentukan dalam dokumentasi skrip whistle untuk Manufacturing Data Engine (MDE).

Membuat parser

Parser melakukan pemetaan sumber ke target dengan menggunakan skrip Whistle. Saat membuat parser, Anda harus menentukan tiga elemen inti:

1. Class pesan yang aliran pesannya dilanggan oleh parser (input).
2. Versi jenis stream rekaman proto yang dikeluarkan (output) oleh parser.
3. Skrip Whistle untuk mengubah pesan sumber dari class pesan (input) yang ditentukan menjadi rekaman proto dari versi jenis (output) yang ditentukan.

Skrip Whistle diterapkan ke setiap pesan dalam aliran class pesan sumber, dan menghasilkan proto record dari versi jenis tertentu. Sebaiknya luangkan waktu untuk memodelkan class pesan sumber agar memiliki struktur semantik dan skematis yang sama. Class pesan sumber yang ditentukan dengan baik membantu meminimalkan logika bersyarat yang kompleks dalam parser. Lihat bagian tentang membuat model class pesan sumber untuk mendapatkan panduan selengkapnya.

Penting: Mulai rilis Manufacturing Data Engine (MDE) 1.4.1, header pesan Pub/Sub kini disimpan dalam atribut khusus yang disebut mdeHeaders. Jika pesan input Anda berisi atribut tersebut, ekspresi seperti embeddedMetadata: $root[where ($.field !=...)] akan menggantikan atribut yang dicadangkan dan mengakibatkan hilangnya data header Pub/Sub yang diberikan dengan pesan edge. Pastikan Anda menggunakan ekspresi filter Whistle generik dengan hati-hati agar tidak menyebabkan kehilangan data.

Anda dapat membuat parser menggunakan Configuration API atau Konsol:

REST

POST /configuration/v1/parsers

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

Ganti kode berikut:

• PARSER_NAME: nama parser.
• SOURCE_MESSAGE_CLASS_NAME: nama Source Message Class yang aliran pesannya diikuti oleh parser ini.
• TYPE_NAME: nama type yang dibagikan oleh rekaman proto yang dikeluarkan oleh parser ini.
• TYPE_VERSION: versi jenis yang dibagikan oleh rekaman proto yang dikeluarkan oleh parser ini.
• WHISTLE_SCRIPT: skrip Whistle yang menentukan transformasi.

Konsol

1. Untuk membuat parser baru menggunakan konsol, pilih bagian PARSER di menu atas. Daftar parser yang tersedia akan ditampilkan:

   

2. Untuk setiap parser yang tersedia, informasi berikut ditampilkan dalam daftar:

   • Name:Nama parser.
   • Message Class Name: Nama class pesan yang digunakan parser untuk mengambil data.
   • Type: Jenis tujuan yang dikeluarkan parser.
   • Type Version: Versi jenis tujuan yang dikeluarkan parser.
   • Enabled: Status parser (diaktifkan atau dinonaktifkan).
   • Actions: Tindakan yang tersedia untuk parser:
     • 'Lihat/Edit': Membuka menu edit untuk parser tertentu.
     • 'Nonaktifkan/Aktifkan: Memungkinkan penonaktifan parser yang diaktifkan atau pengaktifan parser yang dinonaktifkan.
     • 'Penguji parser': Membuka antarmuka khusus untuk menguji parser menggunakan file JSON tertentu.
     • 'Delete': Menghapus parser dari MDE.

3. Untuk membuat parser baru, klik ADD NEW PARSER.

4. Untuk membuka bagian edit parser tertentu, klik Lihat/Edit di ikon Tindakan. Menu samping yang menampilkan semua parameter yang diperlukan untuk membuat parser baru ditampilkan di sisi kanan layar:

   

5. Untuk menentukan parser baru, parameter berikut harus diberikan:

   • Name: Nama parser. Tidak dapat diedit setelah dibuat.
   • Message Class: Nama Message Class yang digunakan parser untuk mendapatkan data. Tidak dapat diubah setelah parser dibuat. Pilih Message Class dari daftar Message Class yang tersedia.
   • Parser Code: File Whistle yang menentukan pemetaan yang terkait dengan parser. Nama ini dapat diubah kapan saja. Mengubah kode Whistle tidak akan menghasilkan versi baru parser. Parser memang tidak memiliki versi.
   • Type: Output Type yang dikeluarkan oleh parser. Tidak dapat diubah setelah parser dibuat. Pilih jenis dari daftar jenis yang tersedia. Untuk parser baru, versi jenis terbaru dipilih secara default.

Untuk membuat parser, ubah parameter parser, lalu klik BUAT di bagian bawah. Pesan konfirmasi akan ditampilkan jika parser baru telah berhasil dibuat.

Menguji parser

Anda dapat menguji parser dengan memberikan skrip Whistle dan pesan input sampel:

REST

POST /configuration/v1/parsers:test

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

Ganti kode berikut:

• SCRIPT: Skrip Whistle yang akan diuji (diformat sebagai string).
• TEST_MESSAGE: Masukkan pesan pengujian (diformat sebagai objek JSON).

Konsol

Anda dapat menguji parser secara langsung dari menu Tindakan serta di menu Edit Parser.

1. Untuk menguji parser, klik UJI. Layar pengujian akan terbuka:

   

2. Berikan contoh Pesan JSON untuk menguji parser.

3. Masukkan pesan di kotak Input, lalu klik tombol JALANKAN UJI.

• Jika transformasi berhasil, pesan output akan ditampilkan di kotak Hasil.
• Jika transformasi tidak berhasil, pesan error akan ditampilkan dengan kemungkinan penyebab error.

1. Gunakan file JSON yang valid sebagai pesan pengujian yang memiliki struktur yang dapat diproses oleh file Whistle parser. Misalnya, ini adalah contoh payload numerik yang dihasilkan oleh edge Manufacturing Connect yang dapat diuji di 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
}

Mengedit parser

Anda dapat memperbarui parser yang ada, termasuk memperbarui skrip Whistle:

REST

PATCH /configuration/v1/parsers/NAME

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

Ganti kode berikut:

• DISABLED: Status parser (benar atau salah).
• NAME: Nama parser.
• TYPE_NAME: Nama type yang dibagikan oleh rekaman proto yang dikeluarkan oleh parser ini.
• TYPE_VERSION: Versi jenis yang dibagikan oleh rekaman proto yang dikeluarkan oleh parser ini.
• WHISTLE_SCRIPT: Skrip Whistle yang menentukan transformasi.

Konsol

1. Untuk membuka bagian edit parser tertentu, klik Lihat/Edit di ikon Tindakan:

   

2. Menu samping Edit Parser akan terbuka dan menampilkan parameter yang diperlukan untuk mengonfigurasi parser:

   

• Name: Nama parser. Tidak dapat diedit setelah dibuat.
• Message Class: Nama Message Class yang digunakan parser untuk mendapatkan data. Tidak dapat diubah setelah parser dibuat.
• Parser Code: File Whistle yang menentukan pemetaan yang terkait dengan parser. Nama ini dapat diubah kapan saja. Mengubah kode Whistle tidak akan menghasilkan versi baru parser. Parser tidak memiliki versi.
• Type: Output Type yang dikeluarkan oleh parser. Tidak dapat diubah setelah parser dibuat.
• Version: Versi jenis output yang dikeluarkan oleh parser. Dapat dimodifikasi kapan saja untuk versi yang lebih tinggi.

1. Untuk mengedit parser, ubah parameter parser, lalu klik SIMPAN.
2. Pesan konfirmasi akan ditampilkan jika parser telah berhasil dibuat.