パーサーを作成する

このガイドでは、パーサーの作成方法について説明します。パーサーはデータ変換とマッピングを実行します。正確な変換手順は、Manufacturing Data Engine（MDE）の whistle スクリプトのドキュメントで定義されています。

パーサーを作成する

パーサーは、Whistle スクリプトを使用してソースからターゲットへのマッピングを実行します。パーサーを作成するときは、次の 3 つのコア要素を定義する必要があります。

パーサーがサブスクライブするメッセージストリームのメッセージクラス（入力）。
パーサーが出力する（出力）proto レコードストリームの型バージョン。
指定されたメッセージクラス（入力）から定義された型バージョン（出力）の Proto レコードにソースメッセージを変換する Whistle スクリプト。

Whistle スクリプトは、ソースメッセージクラスストリーム内のすべてのメッセージに適用され、特定のタイプ バージョンの proto レコードを出力します。ソースメッセージクラスをモデル化して、共通のセマンティック構造とスキーマ構造を共有することをおすすめします。ソースメッセージクラスを適切に定義すると、パーサーの複雑な条件付きロジックを最小限に抑えることができます。詳細については、ソースメッセージクラスのモデリングのセクションをご覧ください。

パーサーは、構成 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: このパーサーがメッセージストリームをサブスクライブする Source Message Class の名前。
TYPE_NAME: このパーサーによって出力される proto レコードで共有される型の名前。
TYPE_VERSION: このパーサーによって出力される proto レコードで共有される タイプのバージョン。
WHISTLE_SCRIPT: 変換を定義する Whistle スクリプト。

コンソール

コンソールを使用して新しいパーサーを作成するには、上部メニューの [パーサー] セクションを選択します。使用可能なパーサーのリストが表示されます。
利用可能なパーサーごとに、次の情報がリストに表示されます。
- Name:パーサーの名前。
- Message Class Name: パーサーがフィードしているメッセージクラスの名前。
- Type: パーサーが出力する宛先タイプ。
- Type Version: パーサーが出力する宛先タイプのバージョン。
- Enabled: パーサーのステータス（有効または無効）。
- Actions: パーサーで使用可能なアクション:
  - [View/Edit]: 指定されたパーサーの編集メニューを開きます。
  - [Disable/Enable]: 有効なパーサーを無効にしたり、無効なパーサーを有効にしたりできます。
  - [Test parser]: 指定された JSON ファイルを使用してパーサーをテストするための専用インターフェースを開きます。
  - 'Delete': MDE からパーサーを削除します。
新しいパーサーを作成するには、[新しいパーサーを追加] をクリックします。
特定のパーサーの編集セクションを開くには、[アクション] アイコンの [表示/編集] をクリックします。新しいパーサーを作成するために必要なすべてのパラメータを表示するサイドメニューが、画面の右側に表示されます。
新しいパーサーを定義するには、次のパラメータを指定する必要があります。
- Name: パーサーの名前。作成した後は編集できません。
- Message Class: パーサーがフィードするメッセージクラスの名前。パーサーの作成後に変更することはできません。利用可能なメッセージクラスのリストからメッセージクラスを選択します。
- Parser Code: パーサーに関連付けられたマッピングを定義する Whistle ファイル。この設定はいつでも変更できます。Whistle コードを変更しても、パーサーの新しいバージョンは生成されません。パーサーはバージョン管理されません。
- Type: パーサーによって出力された Type を出力します。パーサーの作成後に変更することはできません。使用可能なタイプのリストからタイプを選択します。新しいパーサーの場合、デフォルトで最新の型バージョンが選択されます。

パーサーを作成するには、パーサーパラメータを変更して、下部の [作成] をクリックします。新しいパーサーが正常に作成されると、確認メッセージが表示されます。

パーサーをテストする

Whistle スクリプトとサンプル入力メッセージを指定して、パーサーをテストできます。

REST

POST /configuration/v1/parsers:test

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

次のように置き換えます。

SCRIPT: テストする Whistle スクリプト（文字列としてフォーマット）。
TEST_MESSAGE: 入力テストメッセージ（JSON オブジェクトとしてフォーマット）。

コンソール

パーサーは、[操作] メニューと [パーサーを編集] メニューから直接テストできます。

パーサーをテストするには、[テスト] をクリックします。テスト画面が開きます。
パーサーをテストするためのサンプル JSON メッセージを指定します。
[入力] ボックスにメッセージを入力し、[テストを実行] ボタンをクリックします。

変換が成功すると、出力メッセージが [結果] ボックスに表示されます。
変換が失敗すると、エラーの原因を示すエラーメッセージが表示されます。

パーサーの Whistle ファイルで処理できる構造を持つ有効な JSON ファイルをテストメッセージとして使用します。たとえば、次の例は、default-numeric-value-to-default-numeric-records パーサーでテストできる Manufacturing Connect エッジによって生成された数値ペイロードのサンプルです。

{
  "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: パーサーによって出力された Type を出力します。パーサーの作成後に変更することはできません。
Version: パーサーによって出力される出力タイプのバージョン。上位バージョンではいつでも変更できます。

パーサーを編集するには、パーサーパラメータを変更して [保存] をクリックします。
パーサーが正常に作成されると、確認メッセージが表示されます。