使用扩展创建自定义审计类别
您可以使用 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-[版本].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。
Java 源文件即在 /src 文件夹下的指定包中创建完成，且 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. 单击 Finish。
即为实体创建一个新事件，并将指定注释添加到 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 文件夹包含 JAR 文件 (其中包含为扩展编写的自定义 Java 类) 以及扩展所需的其他第三方 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. 在 Gralde Tasks 选项卡上，添加以下任务：
clean
build
build
3. 单击 Run。成功消息即会记录在 Eclipse 控制台区域中。
扩展 ZIP 文件即在项目的 > 文件夹下创建。您可以在 ThingWorx Platform 中将此 ZIP 文件作为扩展导入。
使用 Ant 构建扩展
如果您的扩展使用 Ant 作为构建框架，请执行以下步骤：
1. 在 Package Explorer 中，右键单击 build-extension.xml 文件，然后选择 > 。
2. 刷新扩展项目。
在 > 下创建一个 ZIP 文件。您可以在 ThingWorx Platform 中将此 ZIP 文件作为扩展导入。
导入扩展
1. 在 Composer 中，打开“导入/导出”菜单，然后选择“导入”。“导入”对话框随即打开。
2. 在“导入选项”下，从下拉列表中选择“扩展”。
3. 单击“浏览”，然后选择在上一部分中创建的扩展 ZIP 文件。
4. 单击“导入”。
扩展即会导入。
查看审计更改
在 Composer 中，以下更改是可见的：
• 添加了具有审计事件的新实体。
• 向本地化表中添加了自定义审计类别和消息的本地化标记。
要测试新的自定义审计类别和消息，请对通过扩展添加的实体执行自定义事件。可通过使用相应的参数执行 QueryAuditHistory 或 QueryAuditHistoryWithQueryCriteria 服务来查看审计历史记录。有关可用参数的详细信息，请参阅您所使用的实现的相关主题 (直接持久化或数据表)：搜索审计数据 (查询，直接久存) 或在线和离线审计数据 (数据表)。