Prüfdaten durchsuchen (Abfragen, direkte Persistenz)
Wenn Sie Prüfdaten durchsuchen möchten, verwenden Sie den Dienst QueryAuditHistoryWithQueryCriteria. Das Untersystem für Prüfung unterstützt Filter-, Sortier- und Paginierungsfunktionen für diesen Dienst über den Parameter query. Es nutzt die Möglichkeit einer Datenbankabfrage zum Filtern und Sortieren der Daten. Es verwendet außerdem Eingaben von speziellen Widgets, die erstellt wurden, um die Filterung zu verbessern und die Paginierung der Ergebnisse zu ermöglichen.
 |
Sie können auch den ursprünglichen Dienst QueryAuditHistory verwenden. Dieser Dienst wird jedoch in einer zukünftigen Version von ThingWorx Platform eingestellt. Wenn Sie ihn verwenden möchten, finden Sie weitere Informationen im Thema Prüfungsdaten suchen (Abfragen, Datentabelle).
|
Dieses Thema ist wie folgt aufgebaut:
2. Mit eingeschränktem Kontext suchen
Abfragegrundlagen
Der Dienst QueryAuditHistoryWithQueryCriteria weist das folgende Format auf:
QueryAuditHistoryWithQueryCriteria(maxItems [INTEGER], startDate [DATETIME], endDate [DATETIME],
auditCategory[STRING],query[QUERY], locale[STRING])
In der folgenden Tabelle werden die Parameter für diesen Dienst beschrieben:
|
Parameter
|
Beschreibung
|
Standardwert
|
||
|---|---|---|---|---|
|
maxItems
|
Die maximale Anzahl von Ergebnissen, die die Abfrage zurückgeben soll. (INTEGER)
|
500 Elemente
|
||
|
locale
|
Die Abkürzung für den Namen der Sprache, in der die Ergebnisse zurückgegeben werden sollen. (STRING). Beispielsweise fr für Französisch oder zh_CN für Chinesisch (China). Eine Liste der von ThingWorx unterstützten Gebietsschemata finden Sie unten unter Unterstützte Gebietsschemata.
|
Das Gebietsschema des angemeldeten Benutzers, der die Abfrage sendet
|
||
|
startDate
|
Datum und Uhrzeit Die Abfrage beginnt mit der Suche nach Prüfmeldungen ab dem Datum und der Uhrzeit, die Sie hier angeben. (DATETIME)
|
Nicht angegeben
|
||
|
endDate
|
Datum und Uhrzeit Die Abfrage beendet die Suche nach Prüfmeldungen, wenn das Datum/die Uhrzeit der Meldungen das hier angegebene Datum und die hier angegebene Uhrzeit erreicht. (DATETIME)
|
Nicht angegeben
|
||
|
query
|
Abfragezeichenfolge (im JSON-Format). Ein Beispiel für eine JSON-Abfrage, die Sie verwenden können, finden Sie im Anschluss an diese Tabelle.
Dieser Parameter wird in mehreren ThingWorx Diensten verwendet. Ausführliche Informationen finden Sie unter Abfrageparameter für Abfragedienste.
|
N/A
|
Standardmäßig gibt eine Abfrage 500 Zeilen zurück. Um die Anzahl der von der Abfrage zurückgegebenen Zeilen zu ändern, können Sie den Parameter maxItems auf die gewünschte Anzahl von Zeilen festlegen. Es gibt eine Obergrenze für die Anzahl von Zeilen, die Sie für den Parameter maxItems angeben können. Standardmäßig ist dieser Grenzwert auf 5000 Zeilen festgelegt. Ein Systemadministrator kann diesen Grenzwert beim Konfigurieren des Untersystems für Prüfung ändern. Weitere Informationen finden Systemadministratoren im Thema Konfiguration des Untersystems für die Prüfung.
Wenn Sie jedoch eine besonders große Anzahl von Ergebnissen erwarten, verwenden Sie eine QUERY.
Im Folgenden finden Sie ein Beispiel für eine Abfrage im JSON-Format:
Beispiel 1. Abfrage im JSON-Format
Die folgende Abfrage im JSON-Format zeigt, wie Sie die Filter, Sortierung und Paginierung konstruieren können, die mit dem Dienst QueryAuditHistoryWithQueryCriteria (Implementierung direkter Persistenz) verwendet werden sollen:
{
"filters": {
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": false
},
"sorts": {
"fieldName": "timestamp",
"isAscending": true,
"isCaseSensitive": true
},
"pagination":{
"pageSize":50,
"pageNumber":2
}
}
Im Kontext eines Dings suchen
Der Dienst QueryAuditHistory für ein Ding funktioniert auf ähnliche Weise wie die Dienste QueryAuditHistory und QueryAuditHistoryWithQueryCriteria für das Untersystem für Prüfung, jedoch mit zusätzlichen Einschränkungen. Das allgemeine Verhalten und alle Parameter dieses Diensts entsprechen den Diensten des Untersystems für Prüfung. Die folgenden Einschränkungen gelten für diesen Dienst:
1. Es wird überprüft, ob der Benutzer, der den Dienst aufruft, Mitglied der Gruppe "Prüfer" ist. Wenn dies nicht der Fall ist, werden die Ergebnisse nach den Berechtigungen dieses Benutzers gefiltert.
2. Wenn der Dienst QueryAuditHistory von einem bestimmten Ding aufgerufen wird, verwendet die Suche die Entitäts-IDs anstelle von Namen.
In der folgenden Tabelle werden die Parameter für den Dienst QueryAuditHistory für ein Ding beschrieben:
|
Parametername
|
Beschreibung
|
|---|---|
|
maxItems
|
Die maximale Anzahl der zurückzugebenden Elemente. Der Basistyp dieses Parameters ist NUMBER.
|
|
startDate
|
Das früheste Prüfungsdatum, das abgefragt werden soll. Der Basistyp dieses Parameters ist DATETIME.
|
|
endDate
|
Das späteste Prüfungsdatum, das abgefragt werden soll. Der Basistyp dieses Parameters ist DATETIME.
|
|
query
|
Die Abfragedefinition. Der Basistyp dieses Parameters ist QUERY. Formatieren Sie die Abfrage als JSON-Objekt.
|
|
locale
|
Das Gebietsschema der Lokalisierungstabelle, das zum Lokalisieren der Ergebnisse verwendet wird. Der Basistyp dieses Parameters ist STRING.
|
Um Dingabfragen mit eingeschränktem Kontext für das Untersystem für Prüfung zu unterstützen, wurde eine Benutzergruppe namens "Prüfer" hinzugefügt. Diese Gruppe ermöglicht es Benutzern ohne Administratorrechte, vollständige Ergebnisse des Diensts QueryAuditHistory anzuzeigen, wenn sie ihn über Dinge aufrufen, die für sie sichtbar sind.
Beispiel: Ein Administrator erstellt ein Ding namens ExampleThing und gewährt User_A, einem Mitglied der Gruppe "Prüfer", Zugriff auf dieses Ding. Der Administrator hat auch User_B Zugriff auf dieses Ding gewährt, dieser Benutzer gehört jedoch keinen speziellen Benutzergruppen an. Wenn diese beiden Benutzer den Dienst QueryAuditHistory über ExampleThing ausführen, sind die erwarteten Ergebnisse wie folgt:
|
Benutzer
|
Gruppenmitgliedschaft
|
Erwartetes Ergebnis
|
|---|---|---|
|
Administrator
|
Administratoren
|
Die zurückgegebene InfoTable enthält alle Prüfungseinträge in Bezug auf ExampleThing.
|
|
User_A
|
Prüfer
|
Die zurückgegebene InfoTable enthält alle Prüfungseinträge in Bezug auf ExampleThing.
|
|
User_B
|
Keine speziellen Gruppen
|
Die zurückgegebene InfoTable enthält nur Prüfungseinträge im Zusammenhang mit User_B.
|
Legacy-Prüfdaten bei aktivierter direkter Persistenz abfragen
Während direkte Persistenz in der Konfiguration des Untersystems für Prüfung aktiviert ist, werden alle Dienste, die Daten verarbeiten oder handhaben, auf das Modell der direkten Persistenz umgestellt – es kann nur auf Daten zugegriffen werden, die generiert werden, während das Modell aktiviert ist. Um Benutzern den Zugriff auf ihre Daten zu ermöglichen, die im Legacy-Format gespeichert wurden (Datentabelleneinträge im AuditDataTable-Element), muss eine alternative Methode für den Zugriff auf diese Datensätze erläutert/bereitgestellt werden.
 |
Es wird empfohlen, Legacy-Prüfdaten während eines Wartungsfensters in den Cold Storage zu exportieren, bevor Sie zu direkter Persistenz wechseln. Dies ist jedoch nicht immer möglich, daher finden Sie im Rest dieses Abschnitts hilfreiche Workaround-Lösungen.
|
Sie können die Entität AuditDataTable verwenden, um Informationen der Version Audit 1.0 ("Legacy"-Informationen) abzufragen. Die Entität AuditDataTable ist Teil einer Untermenge von Datentabellen-Entitäten, denen zusätzliche Einschränkungen hinzugefügt wurden (z.B. ist das Aktualisieren von Einträgen nicht zulässig) und die zum großen Teil die gleichen Dienste wie andere Datentabellen-Entitäten nutzen können.
Ein solcher Dienst ist QueryDataTableEntries. Dieser Dienst ermöglicht es Ihnen, Daten-Tags, Quelle und JSON-Abfrage zu verwenden, um abgerufene Ergebnisse zu filtern.
|
|
Daten-Tags für Prüfeinträge sind immer leer.
|
Um diesen Dienst auszuführen, geben Sie die gleichen JSON-Abfrageparameter wie beim Ausführen von QueryAuditHistory oder QueryAuditHistoryWithQueryCriteria an. Das folgende JSON-Abfragebeispiel verwendet Benutzer- und Zeitstempelfilter und sortiert Einträge vom neuesten zum ältesten Eintrag.
|
|
Die Paginierung wird bei den Datentabelle-Abfragediensten nicht unterstützt.
|
Beispiel 2. JSON-Abfrage
{
"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
}
]
}
|
|
Dieser Dienst gibt unformatierte (nicht konvertierte) Prüfdatensätze sowie Informationen zu Prüfeinträgen zurück. Weitere Informationen zur Übersetzung finden Sie im nächsten Abschnitt.
|
Benutzerdefinierten QueryAuditHistory-Dienst schreiben
Aufgrund der Art der vom Dienst QueryDataTableEntries zurückgegebenen Daten entspricht das Ergebnis möglicherweise nicht immer den Anforderungen des Durchschnittsbenutzers. Um die gleichen Informationen wie in den Diensten QueryAuditHistory und QueryAuditHistoryWithQueryCriteria des Untersystems für Prüfung zu erhalten, können Entwickler einen Wrapper-Dienst schreiben. Dieser Dienst muss die folgenden grundlegenden Aufgaben ausführen:
• Daten aus der AuditDataTable abfragen
• Übersetzung der Lokalisierungs-Token anwenden (Felder message und category)
• Variable Ersetzung für Nachrichtenargument-Ersetzungen anwenden (Feld message)
• Informationen zu Datentabelleneinträgen entfernen
Ein Beispiel für einen solchen Dienst folgt.
Beispiel 3. Benutzerdefinierter QueryAuditHistory-Dienst
Dieser Dienst ist in einfachem JavaScript geschrieben und kann für jede geeignete ThingWorx Entität verwendet werden.
// 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;
}
Unterstützte Gebietsschemata
Die folgende Abbildung zeigt die von ThingWorx unterstützten Gebietsschemata:
