使用延伸功能建立自訂稽核類別
使用 ThingWorx Java SDK，您可以建立自訂稽核事件與訊息。雖然您無法透過 ThingWorx Composer 新增自訂事件，但有兩種方法可以新增客戶稽核類別與訊息：
• 透過 Composer。如需詳細資訊，請參閱自訂稽核類別 。
• 根據 ThingWorx Extension SDK 建立 Java 延伸功能，且本主題將對此進行說明。此方法也需要使用當地語系化表，但您可以透過 Composer 使用者介面以程式設計或互動方式建立權杖。
本主題包含建立延伸功能以針對所稽核事件新增自訂稽核事件、訊息與類別的流程。您可以透過建立自訂 ThingWorx 延伸功能，使其包括具有稽核事件所需屬性的實體，來新增自訂稽核類別。
您可使用 ThingWorx Extension SDK 建立以 Java 為基礎的延伸功能。SDK 可讓您存取支援的 ThingWorx Platform 類別與 API。這會顯示內建服務與方法，讓您更容易在 ThingWorx Platform 上建立及管理實體。如需有關平台中可用類別的詳細資訊，請參閱 Javadoc 文件集。
欲針對稽核建立延伸功能，請遵循下列步驟：
1. 下載並安裝所需軟體。
2. 建立新延伸功能專案。
6. 針對事件啟用稽核。
8. 匯入延伸功能。
事前準備
從 ThingWorx Foundation 的 PTC 軟體下載頁下載下列軟體：
• Eclipse Plugin for ThingWorx Extensions
• ThingWorx Extension SDK
欲安裝 Eclipse 外掛程式：
1. 開啟 Eclipse 並選擇工作區。
2. 按一下 > 。
Install 視窗即會開啟。
3. 按一下 Add。
Add Repository 對話方塊即會開啟。
4. 將 thingworxeclipse-plugin-[version].zip 檔案的內容解壓縮至具有相同名稱的資料夾，然後選取資料夾。
5. 在 ThingWorx 下，選取 ThingWorx Extension Builder 核取方塊，然後按一下 Next。
6. 接受授權合約，然後按一下 Finish。安全性訊息即會開啟。
7. 按一下 OK 來確認安裝。
8. 完成安裝後，重新啟動 Eclipse。
您可以按一下 > 來確認安裝。ThingWorx Extension Project 選項會顯示在清單中。
建立新延伸功能專案
1. 在 Eclipse 中，按一下 > > 。New Project 視窗即會開啟。
2. 展開 ThingWorx，從清單中選取 ThingWorx Extension Project，然後按一下 Next。
3. 輸入延伸功能專案的名稱，然後選取您之前下載的 ThingWorxExtension-SDK-[version]-latest.zip 檔案。
4. 選取 Gradle 或 Ant 作為延伸功能的建構架構。如此會為專案建立 gradle.build 或 build-extension.xml 檔案，具體取決於您所進行的選取。
5. 輸入封裝版本與廠商名稱，然後按一下 Finish。
專案現在會列在 Package Explorer 窗格中。
建立當地語系化表實體並定義權杖
您必須先為自訂稽核類別與訊息定義權杖，才能建立具有稽核事件的實體。您可以在可作為延伸功能一部份包括的當地語系化表實體內定義權杖。當您匯入延伸功能時，會將指定的權杖自動新增至 ThingWorx Platform 中的當地語系化表實體。您可以匯出及修改當地語系化表的預設 XML 範本，來建立當地語系化表實體。
欲在平台中匯出英文的 Default 當地語系化表，請執行下列步驟：
1. 在 Composer 中，開啟「匯入/匯出」選單，然後選取「匯出」。
2. 在「匯出選項」下，從下拉清單中選取「至檔案」。
3. 在「實體」欄位下，選取 Default 當地語系化表。
4. 按一下「匯出」。
在您匯出 Default 當地語系化表的 XML 檔案之後，使用 XML 編輯器開啟該檔案。您可以將權杖手動新增至當地語系化表，作為 Rows 區段下的 Row 元素。例如：
<Rows>
<Row>
<context/>
<name><![CDATA[audit.AuditCategory.ExampleCustomCategory]]></name>
<usage/>
<value><![CDATA[ExampleCustomCategoryEN]]></value>
</Row>
<Row>
<context/>
<name><![CDATA[com.example.audit.ExampleCustomMessage]]></name>
<usage/>
<value><![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]></value>
</Row>
</Rows>
<Row>
<context/>
<name><![CDATA[audit.AuditCategory.ExampleCustomCategory]]></name>
<usage/>
<value><![CDATA[ExampleCustomCategoryEN]]></value>
</Row>
<Row>
<context/>
<name><![CDATA[com.example.audit.ExampleCustomMessage]]></name>
<usage/>
<value><![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]></value>
</Row>
</Rows>
下表描述自訂稽核類別 Row 元素的語法：
|
元素
|
值
|
描述
|
||
|---|---|---|---|---|
|
name
|
<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>
|
audit.AuditCategory. 部份指定用來定義自訂稽核類別名稱的前綴。在此範例中，前綴後面為下列類別名稱：ExampleCustomCategory
|
||
|
value
|
<value><![CDATA[ExampleCustomCategoryEN]]></value>
|
定義自訂類別權杖的值。您可以包括字母數字字元、空格與底線。在此範例中，值設定為顯示下列字串：Example Custom Category EN。
|
下表描述自訂稽核訊息 Row 元素的語法：
|
元素
|
值
|
描述
|
||
|---|---|---|---|---|
|
name
|
<![CDATA[com.example.audit.ExampleCustomMessage]]>
|
定義要針對稽核類別顯示的訊息。您必須定義前綴，然後為訊息提供唯一名稱。
|
||
|
value
|
<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>
|
定義自訂類別權杖的值。您可以指定簡單的訊息，也可以在訊息內包括參數。參數可以參考值，且必須用兩條底線括起來，如下所示：
__type__
|
您應包括延伸功能支援之每種語言的當地語系化表。例如，欲包括日文權杖，您必須建立 ja 當地語系化表實體並新增所需權杖。
完成對當地語系化表的變更後，請將其儲存至系統中任何位置名為 LocalizationTables 的資料夾。
將當地語系化表實體匯入至延伸功能
新增所需權杖之後，您可以匯入在上一部份匯出及修改的當地語系化表實體：
1. 在 Eclipse 中，開啟延伸功能專案，然後按一下 > 。「匯入」視窗會開啟。
2. 在 ThingWorx 下，選取 Entities，然後按一下 Next。
3. 在 Source 欄位中，按一下 Browse，然後選取包含當地語系化表實體的 LocalizationTables 資料夾。
4. 選取您要匯入的實體，然後按一下 Finish。
如此即會將您選取的實體新增至延伸功能專案的 /Entities/LocalizationTables/ 資料夾下。
建立新物件實體並新增稽核事件
您可以將註釋新增至類別內的方法來定義新事件。會將註釋的方法匯入為可在執行時間於平台或混搭中執行的 ThingWorx 服務。欲為延伸功能中的 ThingWorx 實體定義服務，請執行下列步驟：
1. 在 Eclipse 中，開啟 ThingWorx 選單，然後從清單中選取實體類型。
2. 輸入來源資料夾與封裝。
3. 輸入實體名稱，然後按一下 Next。
4. 選取 Editable Extension Entity 核取方塊，然後按一下 Finish。
即會在 /src 資料夾下的指定封裝中建立 Java 來源檔案，且 metadata.xml 檔案會自動更新。
針對事件啟用稽核
您可以在延伸功能中定義在符合一組條件時會觸發的事件。您可以使用事件來觸發具有自訂功能的服務。事件需要預先定義的資料形式。資料形式會儲存與事件關聯的資料，其可由訂閱存取。您可以將 ThingWorx 事件配置為記錄稽核子系統的資訊。欲針對事件啟用稽核，您必須指派事件的以下層面：
• auditCategoryKey:customCategoryToken
• auditMessageKey:customMessageToken
您只能透過建立會新增事件的 Java 程式碼延伸功能來新增這兩個層面，然後再為事件手動定義層面。
下一部份提供定義事件層面的範例。
範例：建立自訂稽核事件
下列程式碼顯示物範本內名為 ExampleAuditedEvent 的稽核事件定義範例。事件已定義標準內容，例如 name、description、category 與實行的 DataShape。稽核的所需層面在 aspects 值中定義。
如需有關事件定義的詳細資訊，請在 ThingWorx Javadoc API 文件集中搜尋以下內容：
com.thingworx.metadata.annotations.ThingworxEventDefinition
下列程式碼顯示了具有稽核所需層面的事件定義：
@ThingworxEventDefinitions{
events = {
@ThingworxEventDefinition(
name = "ExampleAuditedEvent",
description = "Event with Audit specific Aspects",
category = "Example",
dataShape = "EntityReference",
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
)
}
)
@ThingworxBaseTemplateDefinition(name = Thing.GENERIC_THING_TEMPLATE)
public class ExampleAuditedEventExtensionThingTemplate extends Thing {
// Customer business logic implementation
}
events = {
@ThingworxEventDefinition(
name = "ExampleAuditedEvent",
description = "Event with Audit specific Aspects",
category = "Example",
dataShape = "EntityReference",
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
)
}
)
@ThingworxBaseTemplateDefinition(name = Thing.GENERIC_THING_TEMPLATE)
public class ExampleAuditedEventExtensionThingTemplate extends Thing {
// Customer business logic implementation
}
您可以執行下列步驟，將事件新增至延伸功能內的 ThingWorx 實體：
1. 在 Eclipse 中，於 src 資料夾下的實體上按一下滑鼠右鍵，然後從前後關聯選單中選取 > 。
2. 輸入下列資訊：
◦ 事件名稱
◦ 類別名稱
◦ 事件的實行資料形式。在提供的範例中，值設定為 EntityReference
3. 按一下「完成」。
如此即會為實體建立新事件，並會將指定註釋新增至 ThingWorx 實體的 Java 來源檔案。依預設，不會定義稽核的所需層面。欲針對新事件啟用稽核，您必須在 Java 來源內手動定義層面，如下所示：
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
• audit.AuditCategory.ExampleCustomCategory - 指定您在 Default 當地語系化表中定義之自訂類別的權杖名稱。
• com.example.audit.ExampleCustomMessage - 指定您在當地語系化表中定義之自訂訊息的權杖名稱。
新增協力廠商 JAR 檔案
/lib 資料夾包含已針對延伸功能編寫自訂 Java 類別的 JAR 檔案，以及延伸功能需要的其他協力廠商 JAR 檔案。
請確保 metadata.xml 檔案包含每個 JAR 檔案的項目。
 |
請勿將已經包括在 ThingWorx 平台中的協力廠商 JAR 檔案新增至您的延伸功能。
|
使用 Gradle 建構延伸功能
欲建構延伸功能，請建立建構任務。
1. 在 Eclipse 工具列中，按一下 Run 按鈕旁邊的箭頭，然後選取 Run Configurations。
2. 在左側導覽窗格中的 Gradle Task 上按一下滑鼠右鍵，然後選取 New Configuration。
3. 輸入 Build 作為任務組態名稱。
在 Gradle Tasks 標籤中，新增下列任務：
clean
build
build
|
|
您可以選取 Run Configurations 視窗內 Common 標籤中的 Run 核取方塊，將任務作為捷徑新增至 Run 下拉清單。
|
4. 選取您專案的工作目錄，然後按一下 Apply。
5. 在工具列中，按一下 Run 指令，然後選取 Build。
針對較舊版本的 Eclipse，您也可以使用 Gradle STS 外掛程式：
1. 在 Package Explorer 中，於 build.gradle 檔案上按一下滑鼠右鍵，然後選取 > 。組態視窗即會開啟。
2. 在 Gradle Tasks 標籤中，新增下列任務：
clean
build
build
3. 按一下「執行」。即會在 Eclipse 控制台區域記錄一則成功訊息。
系統會在您專案的 > 資料夾下建立延伸功能 ZIP 檔案。您可將此 ZIP 檔案作為延伸功能匯入 ThingWorx Platform。
使用 Ant 建構延伸功能
如果您的延伸功能使用 Ant 作為建構架構，請執行下列步驟：
1. 在 Package Explorer 中，於 build-extension.xml 檔案上按一下滑鼠右鍵，然後選取 >
2. 重新整理您的延伸功能專案。
系統會在 > 下建立一個 ZIP 檔案。您可將此 ZIP 檔案作為延伸功能匯入 ThingWorx Platform。
匯入延伸功能
1. 在 Composer 中，開啟「匯入/匯出」選單，然後選取「匯入」。Import 對話方塊即會開啟。
2. 在「匯入選項」下，從下拉清單中選取「延伸功能」。
3. 按一下「瀏覽」，然後選取您在上一部份建立的延伸功能 ZIP 檔案。
4. 按一下「匯入」。
即會匯入延伸功能。
檢視稽核變更
在 Composer 中，您可以看到下列變更：
• 已新增具有稽核事件的新實體。
• 已將自訂稽核類別與訊息的當地語系化權杖新增至當地語系化表。
欲測試新的自訂稽核類別與訊息，請針對您透過延伸功能新增的實體執行自訂事件。您可以搭配適當參數執行 QueryAuditHistory 或 QueryAuditHistoryWithQueryCriteria 服務來檢視稽核記錄。如需有關可用參數的詳細資訊，請參閱適用於您使用之實行 (「直接持續性」或「資料表」) 的主題：搜尋稽核資料 (查詢，直接持續性) 或線上與離線稽核資料 (資料表) 。