יצירת מנתח

במדריך הזה מוסבר איך ליצור מנתח. הכלי Parsers מבצע טרנספורמציה ומיפוי של נתונים. שלבי השינוי המדויקים מוגדרים במסמכי התיעוד של סקריפט whistle עבור Manufacturing Data Engine‏ (MDE).

יצירת מנתח

מנתחים מבצעים מיפויים ממקור ליעד באמצעות סקריפט Whistle. כשיוצרים מנתח, צריך להגדיר שלושה רכיבי ליבה:

1. סוג ההודעה שאליו מנוי מנתח התוכן (קלט).
2. גרסת הסוג של זרם רשומות ה-proto שהניתוח יוצר (פלט).
3. סקריפט Whistle להמרת הודעות מקור ממחלקה של הודעה שצוינה (קלט) לרשומות פרוטו של גרסת סוג מוגדרת (פלט).

הסקריפט של Whistle מוחל על כל הודעה בזרם של מחלקת הודעות המקור, והוא מוציא רשומות פרוטו של גרסה מסוג מסוים. מומלץ להקדיש זמן ליצירת מודל של מחלקות הודעות המקור, כך שיהיה להן מבנה סמנטי וסכמטי משותף. מחלקות של הודעות מקור מוגדרות היטב עוזרות לצמצם את הלוגיקה המותנית המורכבת במנתחי נתונים. הנחיות נוספות מפורטות בקטע בנושא מידול של מחלקות הודעות ממקורות.

חשוב: החל מגרסה 1.4.1 של Manufacturing Data Engine‏ (MDE), כותרות ההודעות של Pub/Sub נשמרות עכשיו במאפיין שמור שנקרא mdeHeaders. אם הודעות הקלט מכילות את המאפיין הזה, ביטוי כמו embeddedMetadata: $root[where ($.field !=...)] יחליף את המאפיין השמור ויגרום לאובדן נתוני הכותרת של Pub/Sub שסופקו עם הודעת ה-Edge. חשוב להשתמש בזהירות בביטוי המסנן הכללי של Whistle כדי שלא יגרום לאובדן נתונים.

אפשר ליצור מנתח באמצעות Configuration API או המסוף:

REST

POST /configuration/v1/parsers

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫PARSER_NAME: השם של מנתח התוכן.
• ‫SOURCE_MESSAGE_CLASS_NAME: השם של הסיווג של הודעת המקור שהמנתח הזה מנוי לזרם ההודעות שלו.
• ‫TYPE_NAME: השם של type שמשותף לרשומות הפרוטו שמופקות על ידי מנתח התוכן הזה.
• ‫TYPE_VERSION: הגרסה של הסוג שמשותפת לרשומות הפרוטו שמופקות על ידי מנתח התוכן הזה.
• ‫WHISTLE_SCRIPT: סקריפט Whistle שמגדיר את הטרנספורמציה.

המסוף

1. כדי ליצור כלי ניתוח חדש באמצעות המסוף, בוחרים באפשרות PARSERS (כלי ניתוח) בתפריט העליון. מוצגת רשימה של מנתחי הנתונים הזמינים:

   

2. לכל מנתח זמין מוצג המידע הבא ברשימה:

   • ‫Name:שם כלי הניתוח.
   • ‫Message Class Name: השם של מחלקת ההודעות שממנה המנתח מקבל נתונים.
   • ‫Type: סוג היעד שהכלי לניתוח פולט.
   • ‫Type Version: גרסת סוג היעד שהכלי לניתוח פולט.
   • ‫Enabled: הסטטוס של מנתח התוכן (מופעל או מושבת).
   • ‫Actions: פעולות זמינות למנתח:
     • 'הצגה/עריכה': פותח את תפריט העריכה של מנתח נתונים מסוים.
     • 'השבתה/הפעלה: מאפשרת להשבית מנתח מופעל או להפעיל מנתח מושבת.
     • 'Test parser' (בדיקת מנתח): פותח ממשק ייעודי לבדיקת מנתח באמצעות קובץ JSON נתון.
     • מחיקה: מחיקת הכלי לניתוח מ-MDE.

3. כדי ליצור מנתח חדש, לוחצים על ADD NEW PARSER (הוספת מנתח חדש).

4. כדי לפתוח את קטע העריכה של מנתח נתונים מסוים, לוחצים על הצגה/עריכה בסמל פעולות. התפריט הצדדי שבו מוצגים כל הפרמטרים הנדרשים ליצירת מנתח חדש מוצג בצד שמאל של המסך:

   

5. כדי להגדיר את מנתח התוכן החדש, צריך לספק את הפרמטרים הבאים:

   • ‫Name: שם המנתח. אחרי שיוצרים את המיקום, אי אפשר לערוך אותו.
   • ‫Message Class: השם של מחלקת ההודעות שהמנתח מזין ממנה. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את כלי הניתוח. בוחרים את Message Class מרשימת ה-Message Classes הזמינים.
   • ‫Parser Code: קובץ Whistle שמגדיר את המיפוי שמשויך למנתח. אפשר לשנות את השם מתי שרוצים. שינוי קוד Whistle לא ייצור גרסה חדשה של מנתחי הנתונים. נכון, אין גרסאות של מנתחי נתונים.
   • ‫Type: סוג הפלט שמופק על ידי מנתח התוכן. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את כלי הניתוח. בוחרים את הסוג מתוך רשימת הסוגים הזמינים. במנתחים חדשים, גרסת הסוג העדכנית ביותר נבחרת כברירת מחדל.

כדי ליצור את כלי הניתוח, משנים את הפרמטרים של כלי הניתוח ולוחצים על יצירה בתחתית. אם יצירת מנתח התוכן החדש הצליחה, תוצג הודעת אישור.

בדיקת מנתח

כדי לבדוק מנתח, צריך לספק סקריפט Whistle והודעת קלט לדוגמה:

REST

POST /configuration/v1/parsers:test

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫SCRIPT: סקריפט Whistle לבדיקה (בפורמט מחרוזת).
• ‫TEST_MESSAGE: הודעת בדיקה לקלט (בפורמט של אובייקט JSON).

המסוף

אפשר לבדוק את כלי הניתוח ישירות מהתפריט פעולות וגם מהתפריט עריכת כלי הניתוח.

1. כדי לבדוק מנתח, לוחצים על בדיקה. ייפתח מסך בדיקה:

   

2. מזינים הודעת JSON לדוגמה כדי לבדוק את מנתח התוכן.

3. מזינים את ההודעה בתיבה Input ולוחצים על הלחצן RUN TEST (הפעלת בדיקה).

• אם ההמרה מצליחה, הודעת הפלט מוצגת בתיבה תוצאה.
• אם ההמרה לא תצליח, תוצג הודעת שגיאה עם הסיבה האפשרית לשגיאה.

1. משתמשים בקובץ JSON תקין כהודעת בדיקה עם מבנה שאפשר לעבד באמצעות קובץ Whistle של כלי הניתוח. לדוגמה, זו דוגמה למטען ייעודי (payload) מספרי שנוצר על ידי Manufacturing Connect edge שאפשר לבדוק אותו במנתח התוכן 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
}

עריכת מנתח

אפשר לעדכן מנתח קיים, כולל עדכון של סקריפט Whistle:

REST

PATCH /configuration/v1/parsers/NAME

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

מחליפים את מה שכתוב בשדות הבאים:

• ‫DISABLED: מצב המנתח (true או false).
• ‫NAME: שם המנתח.
• ‫TYPE_NAME: השם של הסוג שמשותף לרשומות הפרוטו שמופקות על ידי מנתח התוכן הזה.
• ‫TYPE_VERSION: הגרסה של הסוג שמשותפת לרשומות הפרוטו שמופקות על ידי מנתח התוכן הזה.
• ‫WHISTLE_SCRIPT: סקריפט Whistle שמגדיר את הטרנספורמציה.

המסוף

1. כדי לפתוח את קטע העריכה של מנתח נתון, לוחצים על הצגה/עריכה בסמל פעולות:

   

2. התפריט הצדדי Edit Parser (עריכת כלי הניתוח) נפתח ובו מוצגים הפרמטרים הנדרשים להגדרת כלי הניתוח:

   

• ‫Name: שם המנתח. אחרי שיוצרים את המיקום, אי אפשר לערוך אותו.
• ‫Message Class: השם של מחלקת ההודעות שהמנתח מזין ממנה. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את כלי הניתוח.
• ‫Parser Code: קובץ Whistle שמגדיר את המיפוי שמשויך למנתח. אפשר לשנות את השם מתי שרוצים. שינוי קוד Whistle לא ייצור גרסה חדשה של מנתחי הנתונים. אין גרסאות של מנתחי נתונים.
• ‫Type: סוג הפלט שמופק על ידי מנתח התוכן. אי אפשר לשנות את ההגדרה הזו אחרי שיוצרים את כלי הניתוח.
• ‫Version: הגרסה של סוג הפלט שהמנתח פולט. אפשר לשנות את הגרסה בכל שלב לגרסה מתקדמת יותר.

1. כדי לערוך מנתח, משנים את הפרמטרים של המנתח ולוחצים על שמירה.
2. אם יצירת כלי הניתוח הצליחה, תוצג הודעת אישור.