建立剖析器

本指南說明如何建立剖析器。剖析器會執行資料轉換和對應。如要瞭解確切的轉換步驟，請參閱 Manufacturing Data Engine (MDE) 的 whistle 指令碼說明文件。

建立剖析器

剖析器會透過 Whistle 指令碼執行來源到目標的對應作業。建立剖析器時，您必須定義三個核心元素：

剖析器訂閱的訊息串流所屬的訊息類別 (輸入)。
剖析器發出的 proto 記錄串流類型版本 (輸出)。
Whistle 指令碼，可將指定訊息類別 (輸入) 的來源訊息轉換為定義類型版本 (輸出) 的 Proto 記錄。

Whistle 指令碼會套用至來源訊息類別串流中的每則訊息，並輸出特定類型版本的 proto 記錄。建議您花時間為來源訊息類別建立模型，確保這些類別共用常見的語意和結構架構。定義完善的來源訊息類別有助於盡量減少剖析器中複雜的條件邏輯。如需更多指引，請參閱「建立來源訊息類別模型」一節。

您可以使用 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：這個剖析器發出的 Proto 記錄共用的型別名稱。
TYPE_VERSION：這個剖析器發出的 Proto 記錄共用的類型版本。
WHISTLE_SCRIPT：定義轉換的 Whistle 指令碼。

控制台

如要使用控制台建立新的剖析器，請選取頂端選單中的「PARSERS」部分。系統會顯示可用的剖析器清單：
清單會顯示每個可用剖析器的下列資訊：
- Name：剖析器的名稱。
- Message Class Name：剖析器饋送的訊息類別名稱。
- Type：剖析器發出的目的地類型。
- Type Version：剖析器發出的目的地類型版本。
- Enabled：剖析器的狀態 (已啟用或已停用)。
- Actions：剖析器可執行的動作：
  - 「查看/編輯」：開啟特定剖析器的編輯選單。
  - 「停用/啟用」：允許停用已啟用的剖析器，或啟用已停用的剖析器。
  - 「測試剖析器」：開啟專用介面，使用指定的 JSON 檔案測試剖析器。
  - 「刪除」：從 MDE 刪除剖析器。
如要建立新的剖析器，請按一下「新增剖析器」。
如要開啟特定剖析器的編輯區段，請按一下「動作」圖示中的「查看/編輯」。畫面右側會顯示側邊選單，列出建立新剖析器所需的所有參數：
如要定義新的剖析器，必須提供下列參數：
- Name：剖析器名稱。建立後就無法編輯。
- Message Class：剖析器從中饋送的訊息類別名稱。剖析器建立後即無法修改。從可用訊息類別清單中選取訊息類別。
- Parser Code：定義與剖析器相關聯對應的 Whistle 檔案。隨時可以修改。修改 Whistle 程式碼不會產生新版本的剖析器。剖析器確實沒有版本。
- Type：剖析器發出的輸出類型。剖析器建立後即無法修改。從可用類型清單中選取類型。如果是新的剖析器，系統預設會選取最新版本的類型。

如要建立剖析器，請修改剖析器參數，然後按一下底部的「建立」。如果成功建立新的剖析器，系統會顯示確認訊息。

測試剖析器

您可以提供 Whistle 指令碼和輸入訊息範例，測試剖析器：

REST

POST /configuration/v1/parsers:test

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

更改下列內容：

SCRIPT：要測試的 Whistle 指令碼 (格式為字串)。
TEST_MESSAGE：輸入測試訊息 (格式為 JSON 物件)。

控制台

您可以直接從「動作」選單和「編輯剖析器」選單測試剖析器。

如要測試剖析器，請按一下「測試」。系統會開啟測試畫面：
提供 JSON 訊息範例，測試剖析器。
在「Input」方塊中輸入訊息，然後按一下「RUN TEST」按鈕。

如果轉換成功，輸出訊息會顯示在「Result」(結果) 方塊中。
如果轉換失敗，系統會顯示錯誤訊息，並指出可能原因。

使用有效的 JSON 檔案做為測試訊息，該檔案的結構必須能由剖析器的 Whistle 檔案處理。舉例來說，以下是 Manufacturing Connect 邊緣產生的數值酬載範例，可在 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：這個剖析器發出的 Proto 記錄共用的型別名稱。
TYPE_VERSION：這個剖析器發出的 Proto 記錄共用的類型版本。
WHISTLE_SCRIPT：定義轉換的 Whistle 指令碼。

控制台

如要開啟特定剖析器的編輯區段，請按一下「動作」圖示中的「查看/編輯」：
「編輯剖析器」側邊選單隨即開啟，顯示設定剖析器所需的參數：

Name：剖析器名稱。建立後就無法編輯。
Message Class：剖析器從中饋送的訊息類別名稱。剖析器建立後即無法修改。
Parser Code：定義與剖析器相關聯對應的 Whistle 檔案。隨時可以修改。修改 Whistle 程式碼不會產生新版本的剖析器。剖析器沒有版本。
Type：剖析器發出的輸出類型。剖析器建立後即無法修改。
Version：剖析器發出的輸出類型版本。隨時可以修改，以支援較新的版本。

如要編輯剖析器，請修改剖析器參數，然後按一下「儲存」。
如果剖析器建立成功，系統會顯示確認訊息。