搜索审计数据 (查询，直接久存)
如果要搜索审计数据，请使用 QueryAuditHistoryWithQueryCriteria 服务。审计子系统支持通过 query 参数使用此服务的筛选、排序和分页功能。它将利用数据库查询功能对数据进行筛选和排序。还可以使用所创建的特殊小组件的输入内容，以强化筛选功能并为结果提供分页。
 |
您也可以使用原始 QueryAuditHistory 服务。但是，该服务将在 ThingWorx Platform 的未来版本中被弃用。如果您更喜欢使用此服务，相关详细信息，请参阅主题搜索审计数据 (查询、数据表)。
|
本主题按以下方式组织：
1. 查询基础
2. 使用受约束的上下文进行搜索
3. 从事物的上下文中搜索
6. 支持的区域设置
查询基础
QueryAuditHistoryWithQueryCriteria 服务具有以下格式：
QueryAuditHistoryWithQueryCriteria(maxItems [INTEGER], startDate [DATETIME], endDate [DATETIME],
auditCategory[STRING],query[QUERY], locale[STRING])
下表用于介绍此服务的各个参数：
|
参数
|
说明
|
默认值
|
||
|---|---|---|---|---|
|
maxItems
|
从查询返回的最大结果数。(INTEGER)
|
500 项
|
||
|
locale
|
要使用该语言返回结果的语言名称的缩写。(STRING)。例如，适用于法语的 fr 或适用于中文 (中国) 的 zh_CN。有关 ThingWorx 所支持的区域设置的列表，请参阅下方的支持的区域设置。
|
提交查询的已登录用户的区域设置
|
||
|
startDate
|
日期和时间。查询将从您在此处指定的日期和时间开始查找审计消息。(DATETIME)
|
未指定
|
||
|
endDate
|
日期和时间。如果消息的日期/时间符合您在此处指定的日期和时间，查询将停止查找审计消息。(DATETIME)
|
未指定
|
||
|
query
|
查询字符串 (JSON 格式)。此表下方提供了您可以使用的 JSON 查询的示例。
此参数用于多个 ThingWorx 服务。有关完整的详细信息，请参阅查询服务的查询参数。
|
不可用
|
默认情况下，查询会返回 500 行。要更改查询所返回的行数，可以将 maxItems 参数设置为所需的行数。可以为 maxItems 参数指定的行数存在上限。默认情况下，该上限为 5000 行。系统管理员在配置“审计子系统”时可更改此限制。系统管理员应参阅审计子系统的配置主题。
但是，如果预期结果数量非常大，请使用 QUERY。
以下是 JSON 格式查询的示例：
示例 1. JSON 格式的查询
以下 JSON 格式的查询将展示如何构造要与 QueryAuditHistoryWithQueryCriteria 服务 (直接久存实现) 一起使用的筛选器、排序和分页：
{
"filters": {
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": false
},
"sorts": {
"fieldName": "timestamp",
"isAscending": true,
"isCaseSensitive": true
},
"pagination":{
"pageSize":50,
"pageNumber":2
}
}
从事物的上下文中搜索
事物的 QueryAuditHistory 服务的工作方式与审计子系统上的 QueryAuditHistory 和 QueryAuditHistoryWithQueryCriteria 服务类似，但存在其他限制。此服务的常规行为和所有参数均与审计子系统的服务相同。以下是此服务的限制：
1. 检查调用服务的用户是否为审计者组的成员。如果不是，则使用该用户的权限筛选结果。
2. 从特定事物调用 QueryAuditHistory 服务时，搜索将使用实体标识符而不是名称。
下表介绍了某事物上 QueryAuditHistory 服务的参数：
|
参数名称
|
说明
|
|---|---|
|
maxItems
|
要返回的项的最大数量。此参数的基本类型为 NUMBER。
|
|
startDate
|
要查询的最早审计日期。此参数的基本类型为 DATETIME。
|
|
endDate
|
要查询的最新审计日期。此参数的基本类型为 DATETIME。
|
|
query
|
查询定义。此参数的基本类型为 QUERY。将查询格式化为 JSON 对象。
|
|
locale
|
用于对结果进行本地化的 localizationTable 区域设置。此参数的基本类型为 STRING。
|
为支持审计子系统的上下文约束查询添加了名为“审计者”的用户组。此组允许非管理用户在调用其具有可见性的事物时查看 QueryAuditHistory 服务中的完整结果。
例如，管理员可创建一个名为 ExampleThing 的事物，并对“审计者”组的成员 User_A 提供此事物的访问权限。管理员还可以为不在任何特殊用户组中的 User_B 提供对此事物的访问权限。如果每个用户都从 QueryAuditHistory 中运行 ExampleThing 服务，则预期结果如下所示：
|
用户
|
组成员资格
|
预期结果
|
|---|---|---|
|
管理员
|
管理员
|
返回的 InfoTable 包含与 ExampleThing 相关的所有审计条目。
|
|
User_A
|
审计者
|
返回的 InfoTable 包含与 ExampleThing 相关的所有审计条目。
|
|
User_B
|
无特殊组
|
返回的 InfoTable 仅包含与 User_B 关联的审计条目。
|
在已启用直接久存的情况下查询旧式审计数据
已在审计子系统配置中启用直接久存的情况下，用于处理数据的所有服务都将切换为直接久存模型 - 只有启用了直接久存时所生成的数据才可用。要使用户能够访问以旧式格式 (AuditDataTable 实体中的数据表条目) 保存的数据，当访问这些记录必须进行说明/提供时，才采用替代方式。
 |
建议在维护窗口中将旧式审计数据导出到冷存储，然后再切换到直接久存。但此方式并非始终可行，本部分的其余内容将提供有用的解决方法。
|
您可以使用 AuditDataTable 实体来查询 Audit 1.0 (“旧式”) 信息。AuditDataTable 实体是数据表实体子集的一部分，其中添加了一些附加限制，例如不允许条目更新，并且可以使用大多数与其他数据表实体相同的服务。
此类服务之一为 QueryDataTableEntries。此服务可使用数据标记、源和 JSON 查询来筛选检索到的结果。
|
|
审计条目的数据标记始终为空。
|
要运行此服务，请指定与运行 QueryAuditHistory 或 QueryAuditHistoryWithQueryCriteria 时相同的 JSON 查询参数。下面的 JSON 查询示例使用用户和时间戳筛选器，并按照从最新到最早的顺序对条目进行排序。
|
|
数据表查询服务不支持分页。
|
示例 2. JSON 查询
{
"filters": {
"type": "AND",
"filters": [
{
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": true
}, {
"type": "BETWEEN",
"fieldName": "timestamp",
"from": 1577836800000,
"to": 1609459199000
}
]
},
"sorts": [
{
"fieldName": "timestamp",
"isAscending": false
}
]
}
|
|
此服务会返回原始 (未翻译) 的审计记录以及审计条目信息。有关翻译的信息，请参阅下一部分。
|
编写自定义 QueryAuditHistory 服务
根据 QueryDataTableEntries 服务返回的数据的性质，可能并非总能满足平均用户的需求。要获取与审计子系统的 QueryAuditHistory 和 QueryAuditHistoryWithQueryCriteria 服务中相同的信息，开发人员可以编写包装服务。此服务需要执行以下基本任务：
• 查询来自的 AuditDataTable 的数据
• 应用本地化标记 (message 和 category 字段) 的翻译
• 对消息自变量替换 (message 字段) 应用变量替换
• 移除数据表条目信息
下面是此类服务的一个示例。
示例 3. 自定义 QueryAuditHistory 服务
此服务以简单 JavaScript 的形式写入，并可用于任何适用的 ThingWorx 实体。
// Query auditing data with provided parameters
var result = Things["AuditDataTable"].QueryDataTableEntries({
maxItems: maxItems /* NUMBER */,
values: undefined /* INFOTABLE */,
query: query /* QUERY */,
source: source /* STRING */,
tags: undefined /* TAGS */
});
// Applying translation
var categoryCache = {};
var messageCache = {};
var size = result.getRowCount();
for (var i = 0; i < size; i++) {
var row = result.getRow(i);
row.message = applyReplacements(getTranslatedToken(row.message, locale, messageCache), row.messageArgs);
row.auditCategory = getTranslatedToken(row.auditCategory, locale, categoryCache);
}
// Removing non AuditHistory columns
result.RemoveField("id");
result.RemoveField("key");
result.RemoveField("tags");
result.RemoveField("location");
result.RemoveField("messageArgs");
// Helper translation and caching function
function getTranslatedToken(token, language, cache) {
if (cache[token] == null || cache[token] == undefined) {
var params = {
language: language /* STRING */,
token: token /* STRING */
};
var translation = Resources["RuntimeLocalizationFunctions"].GetEffectiveTokenForLanguage(params);
cache[token] = translation;
return translation;
} else {
return cache[token];
}
}
// Helper variable replacement function
function applyReplacements(translation, replacementsInfoTable) {
var filledInTranslation = translation;
var replacements = replacementsInfoTable.getRow(0);
for (var key in replacements) {
if (replacements[key] != null && replacements[key] != undefined) {
filledInTranslation = filledInTranslation.replace(new RegExp("__" + key + "__", "g"), replacements[key]);
}
}
return filledInTranslation;
}
支持的区域设置
下图显示了 ThingWorx 所支持的区域设置：
