サービスの作成、実装、およびテスト
Thing サービスは Thing が実行可能な機能です。サービスは ThingWorx プラットフォーム内部およびマッシュアップによって使用され、適切なアクセス権を持つ外部ソースからアクセスできます。サービスは以下の ThingWorx エンティティにのみ定義できます。
• Thing
• Thing Template
• Thing Shape
• リソース
• 認証システム
サービスは JavaScript、SQL、または Java を介して実装されます。
 |
Java は拡張機能でのみ使用できます。
|
URL、REST クライアントアプリケーション、または ThingWorx の別のサービスによってサービスを呼び出すことができます。
プロジェクトの要件を満たすため、ThingWorx でモデルにカスタムサービスを作成します。
サービスを作成および実装する際の最良事例
サービスを作成および実装する際には、以下の最良事例を使用します。
• サービスの命名規則を定義します。以下の点に留意してください。
◦ サービスに論理的で意味のある名前と説明を指定します。
◦ すべてのサービスで標準の命名法を使用します。たとえば、サービス名にサービスの動詞と説明をプレフィックスとして付けます。動詞のいくつかの例を以下に示します。
|
動詞
|
説明
|
|---|---|
|
Get
|
データベースから値を取得します。
|
|
Set
|
データベースエントリの値を設定します。
|
|
Query
|
データベースからレコードのグループを返します。
|
|
Add
|
データベースにレコードを追加します。
|
|
Update
|
データベース内のレコードを更新します。
|
|
Delete
|
データベース内のレコードを削除します。
|
|
Validate
|
データベース内のレコードを検証します。
|
|
Purge
|
データベース内のレコードをパージします。
|
|
Create
|
データベース内にレコードのセットを作成します。
|
|
Import
|
データベースにデータをインポートします。
|
|
Export
|
データベースからデータをエクスポートします。
|
|
Parse
|
データを解析します。
|
例: 履歴データを取得するサービスに推奨される名前は History ではなく getHistory です。
◦ あいまいな名前は避けます。
◦ できるかぎり、長いサービス名は避けます。
• 共通のプロパティおよびサービスを単一のエンティティ (できれば Thing Shape) にグループ化します。
• できるかぎり、サービスは Thing Shape に実装します。
|
|
Thing Shape を使用してプロパティとサービスを定義することをお勧めします。Thing Template 上でプロパティおよびサービスを定義した場合、その定義を Thing Shape に移動するのは困難です。
|
• ユーザーインタフェース、ビジネスロジック、データ取得などの各種レイヤーにサービスを設計します。異なるレイヤー内のサービスは異なる役割を果たします。以下の図に、異なるレイヤーにおける役割の例を示します。
• サービスを作成する際には、ThingWorx コードスニペットライブラリ内の使用可能なスニペットを再使用するようにしてください。コードスニペットの使用方法がわからない場合は、サービス内で使用する前にテストします。
• 出力を JSON に設定してサービスを作成する際には、以下の点に注意してください。
◦ プロパティの値が null または undefined の場合、結果に返されません。
たとえば、以下のようになります。
var test = {
test1: "aaa",
test2: 123,
test3: null,
test4: undefined
};
var result = test;
test1: "aaa",
test2: 123,
test3: null,
test4: undefined
};
var result = test;
出力: {"test1": "aaa", "test2": 123}
◦ プロパティが JSON オブジェクトであり、null に設定されている場合、結果に返されます。
たとえば、以下のようになります。
var test = {
test1: "aaa",
test2: 123,
test3: null,
test4: undefined,
"line_categories": [ null ]
};
var result = test;
test1: "aaa",
test2: 123,
test3: null,
test4: undefined,
"line_categories": [ null ]
};
var result = test;
出力: {"test1": "aaa", "test2": 123, "line_categories": [ null ]}
• サービスの実行時間が長いことが予想される場合、ユーザーがそのサービスを同時に複数回トリガーできないようにしてください。
• サービスがマッシュアップ内のイベントトリガーに基づいている場合、ServiceInvokeCompleted イベントを使用して、アプリケーションでのデータフローを許可します。
• マッシュアップ内のデータを再表示するには、自動再表示ウィジェットまたは GetProperties サービスを使用することをお勧めします。
マッシュアップが GetProperties をサービスを使用し、ブラウザが WebSocket をサポートしている場合、ブラウザは更新されたプロパティの値をサーバーからリアルタイムで自動的に受信します。この場合、自動再表示ウィジェットを使用する必要はありません。この機能は、サービスプロパティパネルで「可能な場合、値を自動的に更新」チェックボックスをオンにした場合にのみ使用できます。
自動再表示ウィジェットを使用している場合、システムへの負荷を回避するため、自動再表示ウィジェットを 15 秒以上に設定することをお勧めします。
| | サーバー側の遅延サービスは、ほかのサービスがブロックされる可能性があるので使用しないでください。これによってアプリケーションがクラッシュする可能性があります。 |
• ランタイムでの単純な変換の場合、サービスではなく定義式ウィジェットを使用することをお勧めします。
たとえば、温度を°C で表示している場合に°F で表示できるようにするには、定義式ウィジェットを使用します。
• エンドユーザーがエラーを受信する可能性を回避するため、コードにチェックを追加します。
たとえば、コードが実行するためにいくつかの入力パラメータを必要とする場合、サービス実行時にそれらの入力パラメータが Null でないことを確認するチェックを作成します。
• アプリケーションがローカライズされ、サービスの結果に基づいて動的に変化するテキストが UI エレメントに含まれている場合、マッシュアップに表示されるテキストの値をサービス内でハードコーディングしないようにします。これは、テキストを返すサービスの結果をローカライズする必要があるためです。これにより、後から UI テキストを簡単に保守および修正することも可能になります。
• カスタムサービスを作成する際に、そのサービスを呼び出すアクセス許可をどのユーザーまたはユーザーグループに付与するかを決定します。詳細については、
表示権限およびアクセス許可を使用した ThingWorx Platform 上に構築されたアプリケーションのセキュリティ保護を参照してください。
• サービスを実行した結果、ゴーストエンティティが作成される可能性があります。ゴーストエンティティは、ThingWorx Composer からではなく、コード/スクリプトを介して動的に作成されます。ゴーストエンティティが作成されるのは良いことではありません。詳細については、
ThingWorx でのゴーストエンティティの検出、除去、防止を参照してください。
ゴーストエンティティが作成された場合、以下のいずれかの方法で除去できます。
◦ ThingWorx サーバーを再起動します。永続データから JVM メモリが再ロードされ、ゴーストエンティティが除外されます。
◦ Ghost Entities Cleaner 拡張機能を使用します。これは
PTC Marketplace からダウンロードできます。
• ThingWorx プラットフォームでのスクリプトのタイムアウトのデフォルト設定は 30 秒です。スクリプトがデフォルト設定よりも長く実行されると、プラットフォームが実行を強制終了します。ThingWorx 管理者は、platform-settings.json ファイルの基本設定セクションでスクリプトのタイムアウトを設定できます。
サービスをテストする際の最良事例
サービスをテストする際には、以下の最良事例を使用します。
• サービスを構築しながら段階的にテストします。該当する場合、スクリプトロガーメッセージを使用します。
| | サービスに無限ループがあると ThingWorx サーバーがダウンする可能性があります。 |
• サービスのテスト中に、エラーメッセージがないかログをチェックします。これは購読のサービスで特に役立ちます。以下のログファイルが便利です。
◦ ErrorLog.log - エラーの詳細なスタックトレースを提供します
◦ ScriptErrorLog.log - サービスコンテキスト情報 (スタックエラー行番号) を提供します
エラーがこのファイルに記録されるのは、「LoggingSubsystem」サブシステムの「コンフィギュレーション」タブで「スクリプトスタックトレースを有効化」チェックボックスをオンにした場合だけです。
| | 上記のファイルは ThingworxStorage/logs フォルダに含まれています。これらのファイルを読み取るには、ThingWorx サーバーにアクセスする必要があります。 |
• サービスがマッシュアップから呼び出される場合、Composer とマッシュアップでサービスをテストします。
• サービスを実行するためにユーザー入力が必要な場合、バリデータウィジェットを使用できます。
• ブラウザで使用可能な開発者ツールを使用して、サービスの結果をチェックします。これはマッシュアップで実行するサービスのシーケンスをデバッグする場合に便利です。このツールでは、サービスの結果がその特定の実行のコンテキストで表示されます。
ヒント
• サービスをサーチする場合、エンティティを編集モードで開かないでください。エンティティ名の左側にあるプレビューリンクを使用して、エンティティを表示モードで開きます。
その他の注意事項
• セキュリティ
◦ セキュリティを向上させるには、サービスオーバーライドを使用して、プラットフォームで使用可能な重要なサービスに対するアクセス許可を拒否します。
• アップグレード
◦ 良いコーディング習慣を身に付け、大きなモノリシックサービスを作成しないようにします。