剖析器

剖析器是設定實體，可定義如何將特定來源訊息類別的訊息剖析及轉換為特定目標類型的記錄。

來源到目標

剖析器設定包含下列三個元件：

  1. 來源訊息類別關聯：剖析器會處理單一來源訊息類別的來源訊息。詳情請參閱來源訊息類別。
  2. 類型版本關聯：剖析器會發出單一類型版本的 Proto 記錄。類型版本設定會定義發出的 Proto 記錄中必須包含哪些欄位，並決定這些欄位的結構 (結構定義)。詳情請參閱「類型」。
  3. Whistle 指令碼：Whistle 指令碼會定義如何使用對應、剖析和轉換邏輯，將來源訊息轉換為 Proto 記錄。Whistle 指令碼是由使用者編寫，但 Manufacturing Data Engine (MDE) 會提供常見用途的設定套件。詳情請參閱下節。

口哨定義

Whistle 是一種對應語言，可用於將複雜的巢狀資料從一個結構定義轉換為另一個結構定義。在製造業中，資料模型可能很複雜，且可能包含許多巢狀和重複結構。因此難以用程序格式表示對應邏輯。Whistle 提供宣告式語言，讓您以自然的方式定義對應和轉換邏輯，解決這個問題。

舉例來說，您可以使用 Whistle，將不同工廠的數個感應器資料模型，整合為統一的 MDE 類型模型。來源資料可能包含巢狀結構，例如元件清單或特徵階層。Whistle 可讓您以自然的方式表示這些巢狀結構的對應邏輯，不必編寫程序碼。

Whistle 也支援函式，可將涉及重複結構的複雜對應項目分解為函式。這樣一來，您就能更輕鬆地瞭解及維護對應程式碼，並重複使用程式碼。

相較於程序式方法，Whistle 具有以下優點：請參閱以下範例：

假設有以下範例酬載：

{
  "payload": {
    "tag": "vibration-sensor"
  },
  "details": {
    "value": 0.24,
    "timestamp": "2023-06-26 12:19:20.046000 UTC"
  }
}

以及下列 Whistle 指令碼：

package mde

[{
    tagName: $root.payload.tag
    timestamps: {
        eventTimestamp: $root.details.timestamp
    }
    data: {
        numeric: $root.details.value
    }
}]

套用先前的 Whistle 指令碼後，剖析器會產生類似下列的 Proto 記錄：

[
  {
    "tagName": "vibration-sensor",
    "timestamps": {
      "eventTimestamp": "2023-06-26 12:19:20.046000 UTC"
    },
    "data": {
      "value": 0.24
    }
  }
]

如要進一步瞭解 Whistle 語言語法和可用函式，請參閱 Whistle 說明文件。

剖析器的執行階段行為

在執行階段，剖析器會接收與其相關聯的來源訊息類別的所有訊息，對每則訊息套用已設定的 Whistle 腳本，並發出已設定類型的一或多個 Proto 記錄。

發出的 Proto 記錄必須符合類型設定。如果不符合規定，就會移至無效信件佇列。

關聯規則

剖析器只能與單一訊息類別和單一類型/版本建立關聯。不過，只要記錄屬於與剖析器連結的類型版本，剖析器可能會發出多筆記錄。剖析器的輸出內容是 proto 記錄物件的陣列。

parser-multiple-proto-records

如果來源訊息包含要取消彙整的讀取或事件陣列，從剖析器發出多筆記錄就很有用。剖析器可將來源訊息「分割」為多個 Proto 記錄，讓每項讀取作業 (例如) 成為 BigQuery 記錄資料表中的一列。

發出的 Proto 記錄可能會參照任何標記名稱。這項行為與 1.1 和 1.2 版不同，後者會將標記名稱限定在類型範圍內。在 1.3 版之後，任何剖析器發出的 MDE proto 記錄

Proto 記錄結構定義

Proto 記錄必須符合的 JSON 結構定義取決於：

  1. 原型：與類型相關聯的特定原型。
  2. 類型設定：為類型定義的設定。

原型會定義記錄的基本結構定義。舉例來說，discrete 原型系列中的某個類型需要原型記錄包含下列屬性的值：

  • tagName
  • timestamps.eventTimestamp
  • data.complex

該類型可能會對 Proto 記錄施加進一步限制。舉例來說，您可以為 data 欄位定義結構定義，也可以要求 Proto 記錄提供中繼資料執行個體的參照。

詳情請參閱 proto 記錄參考資料。

參考資料查詢

MDE 提供自訂 Whistle 函式，可從查閱 bucket 中查閱所提供鍵的值。

您可以在 Whistle 指令碼中呼叫 mde::lookupByKey 函式，依自然鍵查閱查閱 bucket 例項。這個函式會將執行個體的查閱bucketName、bucketVersion 和 naturalKey 做為引數，並傳回所提供自然鍵的最新中繼資料執行個體。您可以使用這個執行個體，在剖析器中填入 Proto 記錄的欄位。例如：

"data" : {
  "complex" : {
    "VIN" : mde::lookupByKey("vin-lookup-bucket", input.vinKey, 1).VIN,
    "vin_registration_time" : mde::lookupByKey("vin-lookup-bucket", input.vinKey, 1).vin_registration_time,
    "ResultValue" : 163.0482614,
  }
}

剖析器的命名限制

剖析器名稱可包含下列項目：

  • 字母 (大寫和小寫)、數字和特殊字元 - 和 _。
  • 長度上限為 255 個半形字元。

您可以使用下列規則運算式進行驗證：^[a-z][a-z0-9\\-_]{1,255}$。

如果您嘗試建立違反命名限制的實體，系統會顯示 400 error。

您可以使用 mde::sanitizeTagName() 函式，確保名稱符合命名限制。詳情請參閱這篇文章。