拡張機能のインポート
拡張機能は、拡張機能ファイルとメタデータファイルから構成される ZIP アーカイブです。拡張機能のコンテンツを ThingWorx にインストールするには、ZIP ファイルをインポートする必要があります。すべての拡張機能の ZIP ファイルを 1 つの ZIP フォルダにパッケージ化することで、複数の拡張機能を一度にインポートできます。
拡張機能のインポートの有効化
拡張機能のインポートはすべてのユーザーでデフォルトでは無効になっていますが、platform-settings.jsonファイルを設定することによって有効にできます。
1. platform-settings.json ファイルを開きます。デフォルトでは、このファイルは ThingworxPlatform フォルダにあります。
2. 以下の ExtensionPackageImportPolicy のパラメータを追加または更新して true に設定することで、拡張機能をインポートできるようにします。設定の最良事例については、以下のセクションを参照してください。
 |
デフォルトでは、すべてのパラメータが false になっています。各パラメータの詳細については、platform-settings.jsonを参照してください。
|
"ExtensionPackageImportPolicy": {
"importEnabled": false,
"allowJarResources": false,
"allowJavascriptResources": false,
"allowCSSResources": false,
"allowJSONResources": false,
"allowWebAppResources": false,
"allowEntities": false,
"allowExtensibleEntities": false
},
"importEnabled": false,
"allowJarResources": false,
"allowJavascriptResources": false,
"allowCSSResources": false,
"allowJSONResources": false,
"allowWebAppResources": false,
"allowEntities": false,
"allowExtensibleEntities": false
},
3. platform-settings.json ファイルを保存して閉じます。
拡張機能インポート制御の最良事例
ExtensionPackageImportPolicy のパラメータを設定する際には、最小限の数のパラメータを有効にすることで拡張機能のインポートを制御するため、反復的アプローチをとります。デフォルトでは、すべてのパラメータが false になっています。
1. importEnabled パラメータを true に設定し、拡張機能をインポートします。
2. インポートに失敗した場合、allowEntities パラメータを true に設定し、拡張機能をインポートします。
3. インポートに失敗した場合、allowExtensibleEntites パラメータを true に設定し、拡張機能をインポートします。
4. インポートに失敗した場合、該当する allow<Content>Resources パラメータ (allowJarResources など) を設定します。リソースは拡張機能の metadata.xml ファイルで指定されています。
5. インポートに成功した後、すべてのパラメータを false に戻します。
6. プラットフォームを再起動して、拡張機能のインポートを無効にします。
拡張機能のインポート
拡張機能をインポートするには、次の手順に従います。
1. Composer で、 > の順にクリックします。
2. 「インポートオプション」ドロップダウンリストで、「拡張機能」を選択します。
3. ローカルディレクトリをブラウズして拡張機能の ZIP ファイルを選択し、「開く」をクリックします。
4. 「検証」をクリックして、「インポート」をクリックします。
5. 「閉じる」をクリックして「インポート」ダイアログボックスを閉じます。
インポートされた拡張機能ファイルがダッシュボードに表示されます。
拡張機能のバージョン管理
ExtensionPackage エレメントの dependsOn 属性を使用して、拡張機能のコンマ区切りの名前とバージョンのペアを指定できます。フォーマットは <名前:メジャーリリース番号.マイナーリリース番号.パッチ番号> (例: ExtensionA:1.0.0) で、これは依存チェックに使用されます。
Java ベースの拡張機能のアップグレード
新規バージョンをインポートすることで Java ベースの拡張機能をアップグレードしようとすると、プラットフォームを再起動しなければならないことを示す情報メッセージが表示されます。この場合、拡張機能の ZIP ファイルは /ThingworxStorage/extensions/upgradequeue というキューに配置されます。Apache Tomcat サーバーを再起動すると、ThingWorx がキューに入れられた拡張機能の ZIP ファイルのインポートを試みます。キューに入れられた拡張機能のインポートに失敗した場合は、もう一度サーバーを再起動して、拡張機能を前のバージョンに戻す必要があります。ThingWorx がキューに入れられた拡張機能のインポートを試みた後は、キューに入れられた拡張機能のインポートが失敗した場合でも、キューはクリアされます。
Java ベースの拡張機能をインポートするたびに再起動する必要はありません。複数の拡張機能をインポートのキューに入れることができ、1 回再起動した後で依存に基づいて適切な順序でインポートされます。依存の設定の詳細については、拡張機能開発ガイドを参照してください。
|
|
通常、Java 以外の拡張機能のインポート時に再起動が要求されることはありません。ただし、次のシナリオでの例外があります。
• Java 以外の拡張機能が、アップグレード対象の Java 拡張機能を含む ZIP ファイルの一部として圧縮されている場合、ZIP ファイル全体がキューに追加され、再起動後にインポートされます。
• Java 以外の拡張機能が (最初のインストールまたはアップグレードで) インポートされており、アップグレードのためにキューに追加されている拡張機能に依存している場合、その Java 以外の拡張機能もキューに追加されます。
|
拡張機能のインポート結果の一般的なメッセージ
拡張機能のインポート時には、以下のような情報メッセージと警告が表示されることがよくあります。
Info: Extension <extension-name> is queued for installation on the next server restart because it contains JAR files, and an older version of this extension is already installed.
JAR が組み込まれた拡張機能をインポートした場合には必ず、インポートを完了するためにはサーバーを再起動しなければならないことを通知するこのメッセージが表示されます。
Warning: Extension <extension-name> skipped because it is already installed.
Warning: Extension Package <extension-name> may be trying to change the template of the following Entities: <entity: entity-name>
ThingWorx はエンティティの基本 Thing Template の変更をサポートしていません。この警告は、拡張機能のインポート時に、レポートされた Thing Template を調べてもその基本 Thing Template が変更されているかどうかを判別できない場合に表示されます。
プラットフォームの再起動後
再起動の後、アプリケーションログで、キューに入っている拡張機能が正常にインポートされたことを確認します。キューに入っている拡張機能がインポートされるたびに、アプリケーションログに以下が記録されます。
Starting entity import of /ThingworxStorage/extensions/XSS_Test/metadata.xml
キューに入っているインポートが正常に完了した場合、以下のメッセージが表示されます。
*** Import completed successfully
問題があった場合、以下のエラーが表示されます。
Error occurred while installing Extensions from upgrade queue
|
|
問題が原因でキューに入っているインポートが失敗した場合、システムを再び再起動して、以前のバージョンの拡張機能に戻します。
|
拡張機能インポートの失敗メッセージの分析
拡張機能のインポートに失敗した場合、"拡張機能のインポートに失敗した" ことを通知して詳細を含むエラーログを参照先として示すメッセージがアプリケーションログに記録されます。ErrorLog.log ファイルでは、インポートの失敗について記録されたエラーメッセージの末尾に、拡張機能パッケージのインポートが失敗した理由が示されます。失敗の例には、インポートが無効になっている、jar のインポートが許可されていないなどがあります。このエラーを基に、適切なコンフィギュレーション設定になるように調整して、拡張機能のインストールを成功させます。
|
ログメッセージ
|
ExtensionPackageImportPolicy でパラメータコンフィギュレーションを確認
|
|---|---|
|
ExtensionPackage upload attempted while import disabled
|
"importEnabled": true
|
|
ExtensionPackage<XYZ> upload attempted while allow jars is disabled
|
"allowJarResources": true
|
|
ExtensionPackage<XYZ> upload attempted while allow Javascript is disabled
|
"allowJavascriptResources": true
|
|
ExtensionPackage<XYZ> upload attempted while allow CSS is disabled
|
"allowCSSResources": true
|
|
ExtensionPackage<XYZ> upload attempted while allow JSON is disabled
|
"allowJSONResources": true
|
|
ExtensionPackage<XYZ> upload attempted while allow WebApp is disabled
|
"allowWebAppResources": true
|
|
ExtensionPackage<XYZ> upload attempted while allow entities is disabled
|
"allowEntities": true
|
|
ExtensionPackage<XYZ> upload attempted while allow extensible entities is disabled
|
"allowExtensibleEntities": true
|