Menulis skrip di Whistle

Panduan ini memberikan panduan umum tentang cara menulis skrip Whistle untuk parser. Untuk mengetahui informasi selengkapnya tentang sintaksis Whistle dan fungsi yang tersedia, lihat referensi Whistle.

Penulisan skrip siulan

Sebelum mulai menulis skrip Whistle, sebaiknya:

  1. Pahami skema pesan di class pesan sumber yang menjadi tujuan langganan parser. Untuk mencegah kegagalan pemetaan dan, sebagai akibatnya, pesan masuk ke antrean pesan yang dihentikan pengirimannya, skrip Whistle harus dapat memetakan semua pesan masuk. Jika skema pesan berbeda dari pesan ke pesan, skrip Whistle Anda harus menangani perbedaan ini.

    Mengetahui skema pesan sumber membantu Anda memahami kolom apa yang ada dalam pesan sumber dan jenis datanya, sehingga Anda dapat memutuskan cara memetakan kolom dalam pesan sumber ke skema jenis target. Anda juga harus memahami semantik data, sehingga Anda dapat secara efektif memutuskan bagian mana dari pesan sumber yang harus dipetakan ke atribut dalam skema target.

    Misalnya, mengetahui frekuensi perubahan nilai atribut membantu Anda memutuskan data yang harus dipetakan sebagai metadata tersemat versus metadata cloud. Lihat bagian tentang memodelkan class pesan sumber dan memodelkan data.

  2. Pahami skema versi jenis yang ditentukan untuk parser. Skrip Whistle di parser memetakan pesan sumber ke skema versi jenis yang ditentukan untuk parser. Untuk mengetahui cara membuat rekaman proto yang memenuhi persyaratan versi jenis, Anda harus mencari spesifikasi jenis. Secara khusus, Anda harus mencatat skema kolom data, serta semua asosiasi bucket metadata. Terutama penting untuk mencatat apakah ada asosiasi bucket metadata yang ditandai sebagai required: true. Jika Anda berencana mencari instance metadata berdasarkan nilai, Anda harus mencatat skema bucket terkait.

  3. Tulis skrip Whistle. Skrip Whistle melakukan transformasi dari sumber ke target yang sebenarnya. Pesan sumber dimuat ke dalam input yang disebut $root. Lihat Referensi Whistle untuk mengetahui ringkasan bahasa dan fungsi yang tersedia. Selain itu, lihat panduan lainnya di bagian ini, seperti cara menautkan data ke instance metadata.

Praktik terbaik

Bagian ini menguraikan praktik terbaik untuk menulis skrip Whistle.

Lakukan pemeriksaan null saat mengakses properti pesan

Sebaiknya periksa nilai null saat mengakses properti pesan, setiap kali ada kemungkinan properti tersebut tidak ditentukan.

//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;
        }
    }
}

Contoh

Bagian berikut menunjukkan beberapa contoh operasi dasar menggunakan Whistle.

Pemetaan Peluit Sederhana

Dengan pesan sumber berikut...

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

Dan skrip Whistle berikut:

package mde

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

Parser akan menghasilkan output rekaman proto ini:

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

Pemetaan Whistle sederhana menggunakan fungsi

Dengan pesan sumber berikut:

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

Dan skrip Whistle berikut:

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;
}

Parser akan menghasilkan output rekaman proto ini:

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

Memancarkan beberapa catatan proto dari parser 1

Dengan pesan sumber berikut:

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

Dan skrip Whistle berikut:

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;
        };
}

Parser akan menghasilkan output rekaman proto ini:

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

Memancarkan beberapa catatan proto dari parser 2

Dengan pesan sumber berikut:

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

Dan skrip Whistle berikut:

package mde

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

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

Parser akan menghasilkan output rekaman proto ini:

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