搜尋稽核資料 (查詢，直接持續性)
如果需要搜尋稽核資料，請使用 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
|
提交查詢之登入使用者的地區設定
|
|||
|
startDate
|
日期與時間。查詢會從您在此指定的日期與時間開始，尋找稽核訊息。(DATETIME)
|
未指定
|
||
|
endDate
|
日期與時間。當訊息的日期/時間到達您在此指定的日期與時間時，查詢會停止尋找稽核訊息。(DATETIME)
|
未指定
|
||
|
query
|
查詢字串 (JSON 格式)。在此表格下面的內容中，為您提供了可以使用之 JSON 查詢的範例。
在多個 ThingWorx 服務中，都會用到此參數。如需完整詳細資訊，請參閱查詢服務的查詢參數。
|
N/A
|
依預設，查詢會傳回 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 提供了存取此物件的權限，而此使用者不屬於任何特殊的使用者群組。如果這兩位使用者都從 ExampleThing 執行 QueryAuditHistory 服務，則預期結果如下：
|
使用者
|
群組成員資格
|
預期結果
|
|---|---|---|
|
管理員
|
管理員
|
傳回的 InfoTable 包含與 ExampleThing 相關的所有稽核項目。
|
|
User_A
|
稽核員
|
傳回的 InfoTable 包含與 ExampleThing 相關的所有稽核項目。
|
|
User_B
|
無特殊群組
|
傳回的 InfoTable 僅包含與 User_B 相關聯的稽核項目。
|
在已啟用直接持續性的情況下查詢舊有稽核資料
若在稽核子系統組態中啟用了直接持續性，則處理資料的所有服務都會轉換為直接持續性模式 - 只有在已啟用情況下產生的資料可供存取。若要讓使用者能夠存取其以舊有格式儲存的資料 (AuditDataTable 實體中的 DataTable 項目)，如果要存取這些記錄，必須說明/提供替代方法。
 |
建議在維護期間先將舊有稽核資料匯出至冷儲存區，然後再轉換為直接持續性。在某些情況下，此方法可能會行不通，因此，本部份的其餘內容將會為提供一些有幫助的因應措施。
|
您可以使用 AuditDataTable 實體來查詢 Audit 1.0 (「舊有」) 資訊。AuditDataTable 實體是增加了額外一些限制 (例如禁止項目更新) 之 DataTable 實體子集的一部份，而且可以使用大多數與其他 DataTable 實體相同的服務。
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 欄位) 的變數替代
• 移除 DataTable 項目資訊
此類服務的範例如下。
範例 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 支援的地區設定：
