כתיבת סקריפטים ב-Whistle

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

כתיבת תסריט לשריקה

לפני שמתחילים לכתוב סקריפט של Whistle, מומלץ:

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

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

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

  2. הסבר על הסכימה של גרסת הסוג שהוגדרה למנתח הסקריפט Whistle במנתח ממפה הודעות מקור לסכימת גרסת הסוג שמוגדרת למנתח. כדי לדעת איך ליצור רשומת proto שעומדת בדרישות של גרסת הסוג, צריך לעיין במפרט הסוג. חשוב לשים לב במיוחד לסכימה של השדה data, וגם לשיוכים של קטגוריות מטא-נתונים. חשוב במיוחד לשים לב אם יש שיוכים של דלי מטא-נתונים שמסומנים ב-required: true. אם אתם מתכננים לחפש מופעים של מטא-נתונים לפי ערך, כדאי לרשום את הסכימות של הדליים המשויכים.

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

שיטות מומלצות

בקטע הזה מפורטות שיטות מומלצות לכתיבת סקריפטים ב-Whistle.

ביצוע בדיקות של ערך null כשניגשים למאפייני ההודעה

מומלץ לבדוק אם הערך הוא null כשניגשים למאפיין של הודעה, בכל מקרה שבו יש סיכוי שהמאפיין לא מוגדר.

//Add metadata from source bucket if metadata.source attribute is present
if(isNotNil(input.metadata) and isNotNil(input.metadata.source)) then {
{
    var metadataArray[]: {
        bucketReference: {
            bucketName: "source";
            version: 1;
        };
            naturalKey: input.metadata.source;
        }
    }
}

דוגמאות

בקטעים הבאים מוצגות כמה דוגמאות לפעולות בסיסיות באמצעות Whistle.

מיפוי פשוט של משרוקית

בהינתן הודעת המקור הבאה…

{
  "sensor": "rotation-speed-sensor",
  "machine": "m-234",
  "timestamp": "1687973092857",
  "value": 1200
}

והסקריפט הבא של Whistle:

package mde

[
    {
        tagName: $root.machine + " - " + $root.sensor;
        data: {
            numeric: $root.value;
        };
        timestamps: {
            eventTimestamp: $root.timestamp;
        }
    }
]

הפלט של רשומת הפרוטו שיופק על ידי מנתח התוכן יהיה:

[
  {
    "tagName": "m-234-rotation-speed-sensor",
    "data": {
      "numeric": 1200
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  }
]

מיפוי פשוט של שריקה באמצעות פונקציות

בהינתן הודעת המקור הבאה:

{
  "sensor": "rotation-speed-sensor",
  "machine": "m-234",
  "timestamp": "1687973092857",
  "value": 1200
}

והסקריפט הבא של Whistle:

package mde

[
    {
        tagName: getTagName($root);
        data: getValue($root);
        timestamps: getTimestamp($root)
    }
]

def getTagName(input) {
    input.machine + "-" + input.sensor;
}

def getTimestamp(input) {
    eventTimestamp: input.timestamp;
}

def getValue(input) {
    numeric: input.value;
}

הפלט של רשומת הפרוטו שיופק על ידי מנתח התוכן יהיה:

[
  {
    "tagName": "m-234-rotation-speed-sensor",
    "data": {
      "numeric": 1200
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  }
]

הפקת כמה רשומות פרוטו ממנתח 1

בהינתן הודעת המקור הבאה:

{
  "tag": "plc-34",
  "machine": "controller",
  "timestamp": "1687973092857",
  "values": [200, 499]
}

והסקריפט הבא של Whistle:

package mde

var valueLen: listLen($root.values);
var indexes: range(0, valueLen);

[
    getProtoRecords($root.values[], indexes[], $root)
]

def getProtoRecords(value, index, input) {
        tagName: input.machine + "-" + input.tag + "-" + index;
        data: {
            numeric: value;
        };
        timestamps: {
            eventTimestamp: input.timestamp;
        };
}

הפלט של רשומת הפרוטו שיופק על ידי מנתח התוכן יהיה:

[
  {
    "tagName": "controller-plc-34-0",
    "data": {
      "value": 200.0
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  },
  {
    "tagName": "controller-plc-34-1",
    "data": {
      "value": 499.0
    },
    "timestamps": {
      "eventTimestamp": "1687973092857"
    }
  }
]

הנפקת כמה רשומות פרוטו מנתח 2

בהינתן הודעת המקור הבאה:

{
  "machine": "controller",
  "timestamp": "1687973092857",
  "sensors": [
    {
      "tag": "plc-34",
      "value": 200
    },
    {
      "tag": "plc-35",
      "value": 499
    }
  ]
}

והסקריפט הבא של Whistle:

package mde

[$$
    getProtoRecords($root.sensors[], $root)
]

def getProtoRecords(sensor, input) {
        tagName: input.machine + "-" + sensor.tag;
        data: {
            numeric: sensor.value;
        };
        timestamps: {
            eventTimestamp: input.timestamp;
        };
}

הפלט של רשומת הפרוטו שיופק על ידי מנתח התוכן יהיה:

[
  {
    "tagName": "controller-plc-34",
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "data": {
      "numeric": 200
    }
  },
  {
    "tagName": "controller-plc-35",
    "timestamps": {
      "eventTimestamp": "1687973092857"
    },
    "data": {
      "numeric": 499
    }
  }
]