匯入延伸功能
延伸功能為包含延伸功能檔案與中繼資料檔案的 zip 封存。欲將延伸功能的內容安裝到 ThingWorx，您需要匯入 zip 檔案。您可以將所有延伸功能 zip 檔案一起封裝到一個 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 屬性可為延伸功能指定以逗號分隔的名稱/版本配對。格式為 name:major release number.minor release number.patch number (例如：ExtensionA:1.0.0)，用於檢查相依性。
升級支援 Java 的延伸功能
當您嘗試透過匯入新版本來升級支援 Java 的延伸功能時，會顯示資訊訊息，說明您必須重新啟動平台。如果發生這種情況，延伸功能 zip 檔案將放入佇列： /ThingworxStorage/extensions/upgradequeue。重新啟動 Apache Tomcat 伺服器之後，ThingWorx 會試著匯入佇列中的延伸功能 zip 檔案。如果佇列延伸功能匯入失敗，必須再次重新啟動伺服器以還原至先前版本的延伸功能。在 ThingWorx 嘗試匯入佇列延伸功能之後，即會清除該佇列，即使佇列延伸功能匯入失敗時也是如此。
每次匯入支援 Java 的延伸功能之後，您不必重新啟動。如果有多個延伸功能，可將其排入佇列以進行匯入，然後將會根據這些延伸功能在單次重新啟動之後的相依性以適當順序予以匯入。如需有關設定相依性的詳細資訊，請參閱
延伸功能開發指南。
|
|
非 Java 延伸功能在匯入時通常不需要任何重新啟動。但是，下列情境存在例外情況：
• 如果非 Java 延伸功能是包含要升級之 Java 延伸功能的 zip 檔案 zip 的一部份，這些 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 不支援變更實體的基礎物範本。當無法檢查報告的物範本以確定其基礎物範本是否已變更時，會在匯入延伸功能時發生此警告。
重新啟動平台後
重新啟動後，請檢查應用程式記錄檔，以確保排入佇列的延伸功能已成功匯入。針對每個排序佇列等待匯入的延伸功能，您應該會在應用程式記錄檔中看到下列訊息：
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
|
刪除安裝的延伸功能封裝
1. 從 Composer，按一下 > 。
安裝的延伸功能封裝與封裝詳細資訊的清單會顯示在圖標板上。
2. 選取您要刪除的延伸功能，然後按一下 
。
。3. 在刪除確認視窗中，按一下「是」。
所選延伸功能將被刪除。
4. 瀏覽至 Apache Tomcat 安裝目錄的適當子目錄，然後執行下列指令來停止 Tomcat 服務：
shutdown.bat
5. 執行下列指令來重新啟動 Tomcat 服務：
startup.bat
6. 透過查看最終伺服器啟動訊息核對服務是否正確啟動。然後，您可以匯入新版本的延伸功能。