監査データのサーチ (クエリー、直接永続)
監査データをサーチする場合、QueryAuditHistoryWithQueryCriteria サービスを使用します。監査サブシステムは、このサービスで query パラメータによるフィルタ、並べ替え、ページ付け機能をサポートしています。データベースクエリーの機能を使用してデータのフィルタと並べ替えを行います。また、フィルタを強化するために作成された特別なウィジェットからの入力をとり、結果のページ付けを行います。
 |
以前からある QueryAuditHistory サービスを使用することもできます。ただし、このサービスは将来のリリースの ThingWorx Platform で廃止される予定です。これを使用する場合は、詳細について監査データのサーチ (クエリー、データテーブル)のトピックを参照してください。
|
このトピックは以下のように構成されています。
1. クエリーの基本
2. コンテキストに制約があるサーチ
クエリーの基本
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
}
}
Thing のコンテキストからのサーチ
Thing の QueryAuditHistory サービスは監査サブシステムの QueryAuditHistory サービスや QueryAuditHistoryWithQueryCriteria サービスと同様の働きをしますが、追加の制限があります。このサービスの一般的な動作とすべてのパラメータは、監査サブシステムのサービスと同じです。このサービスには以下のような制限があります。
1. このサービスを呼び出しているユーザーが監査担当者グループのメンバーであるかどうかをチェックします。メンバーでない場合、結果はそのユーザーのアクセス許可に従ってフィルタされます。
2. QueryAuditHistory サービスが特定の Thing から呼び出された場合、このサーチでは名前の代わりにエンティティ識別子が使用されます。
次の表では、Thing に対する QueryAuditHistory サービスのパラメータについて説明しています。
|
パラメータ名
|
説明
|
|---|---|
|
maxItems
|
返すアイテムの最大数。このパラメータのベースタイプは NUMBER です。
|
|
startDate
|
クエリーする最初の監査日。このパラメータのベースタイプは DATETIME です。
|
|
endDate
|
クエリーする最新の監査日。このパラメータのベースタイプは DATETIME です。
|
|
query
|
クエリー定義。このパラメータのベースタイプは QUERY です。クエリーを JSON オブジェクトとしてフォーマットします。
|
|
locale
|
結果のローカライズに使用される localizationTable ロケール。このパラメータのベースタイプは STRING です。
|
監査サブシステムでコンテキストに制約がある Thing のクエリーをサポートするため、監査担当者と呼ばれるユーザーグループが追加されました。非管理者ユーザーは、このグループを使用することで、表示アクセス許可がある Thing から QueryAuditHistory サービスを呼び出した場合に、このサービスからのすべての結果が表示されるようになります。
たとえば、管理者が ExampleThing という名前の Thing を作成し、監査担当者グループのメンバーである User_A にこの Thing へのアクセス権を付与したとします。さらに、管理者が、特別なユーザーグループに属していない User_B にも、この Thing へのアクセス権を付与したとします。各ユーザーが ExampleThing から QueryAuditHistory サービスを実行した場合、予想される結果は以下のようになります。
|
ユーザー
|
グループメンバーシップ
|
予想される結果
|
|---|---|---|
|
管理者
|
管理者
|
返される InfoTable には、ExampleThing に関連するすべての監査エントリが含まれています。
|
|
User_A
|
監査担当者
|
返される InfoTable には、ExampleThing に関連するすべての監査エントリが含まれています。
|
|
User_B
|
特別なグループなし
|
返される InfoTable には、User_B のみに関連する監査エントリが含まれています。
|
直接永続が有効な状態でのレガシー監査データのクエリー
監査サブシステムのコンフィギュレーションで直接永続が有効になると、データを処理するすべてのサービスが直接永続モデルに切り替わり、これが有効になっている間に生成されたデータにだけアクセス可能になります。レガシーフォーマットで保存されたデータ (AuditDataTable エンティティ内の DataTable エントリ) にユーザーがアクセスできるようにするには、これらのレコードにアクセスするための別の方法について説明/提供する必要があります。
 |
直接永続に切り替える前に、メンテナンス中にレガシー監査データをコールドストレージにエクスポートすることをお勧めします。これは実行できないこともあるので、このセクションの残りの部分で役立つ次善策について説明します。
|
AuditDataTable エンティティを使用して、Audit 1.0 ("レガシー") 情報をクエリーできます。AuditDataTable エンティティは DataTable エンティティのサブセットの一部であり、エントリの更新を禁止するなどの追加の制限があり、その他の DataTable エンティティと同じサービスのほとんどを使用できます。
そのようなサービスの 1 つに 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 でサポートされているロケールを示します。
