감사 데이터 검색(질의, 직접 지속성)
감사 데이터를 검색하려면 QueryAuditHistoryWithQueryCriteria 서비스를 사용하십시오. 감사 하위 시스템은 query 매개 변수를 통해 필터링, 정렬 및 페이지 매김 기능을 지원합니다. 감사 하위 시스템은 데이터베이스 질의의 기능을 사용하여 데이터를 필터링 및 정렬할 수 있습니다. 또한 필터링을 개선할 목적으로 작성된 특수한 위젯에서 입력을 가져와 결과에 대한 페이지 매김을 제공합니다.
 |
원래 QueryAuditHistory 서비스를 사용할 수도 있습니다. 그러나 이 서비스는 ThingWorx Platform 향후 릴리즈에서 더 이상 사용되지 않습니다. 이 서비스를 사용하려면 감사 데이터(질의, 데이터 테이블) 검색 항목에서 자세한 내용을 확인하십시오.
|
이 항목은 다음과 같이 구성되어 있습니다.
1. 질의 기본 사항
2. 컨텍스트 제한을 사용하여 검색
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 매개 변수에 대해 지정할 수 있는 행 수의 상한값이 있습니다. 기본적으로 이 제한은 5,000개 행입니다. 시스템 관리자는 감사 하위 시스템을 구성할 때 이러한 제한을 변경할 수 있습니다. 시스템 관리자는 감사 하위 시스템 구성 항목을 참조해야 합니다.
그러나 결과의 양이 많을 것으로 예상되는 경우 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에서 지원하는 로캘을 보여줍니다.
