Recherche de données d'audit (requêtes, persistance directe)
Lorsque vous souhaitez rechercher des données d'audit, utilisez le service QueryAuditHistoryWithQueryCriteria. Le sous-système d'audit prend en charge les fonctionnalités de filtrage, de tri et de pagination de ce service via le paramètre query. Il tire parti de la capacité d'une requête de base de données à filtrer et à trier les données. Il prend également en entrée les widgets spéciaux créés pour améliorer le filtrage et effectuer la pagination des résultats.
 |
Vous pouvez également utiliser le service QueryAuditHistory d'origine. Toutefois, ce service sera désapprouvé dans une version future de ThingWorx Platform. Si vous préférez l'utiliser, reportez-vous à la rubrique Recherche de données d'audit (requêtes, table de données) pour plus de détails.
|
Cette rubrique est organisée comme suit :
2. Recherche avec contraintes de contexte
Principes de base des requêtes
Le service QueryAuditHistoryWithQueryCriteria prend en charge le format suivant :
QueryAuditHistoryWithQueryCriteria(maxItems [INTEGER], startDate [DATETIME], endDate [DATETIME],
auditCategory[STRING],query[QUERY], locale[STRING])
La table suivante décrit les paramètres de ce service :
|
Paramètre
|
Description
|
Valeur par défaut
|
||
|---|---|---|---|---|
|
maxItems
|
Nombre maximal de résultats renvoyés par la requête (INTEGER)
|
500 lignes
|
||
|
locale
|
Abréviation du nom de la langue dans laquelle les résultats doivent être renvoyés (STRING). Par exemple, fr pour le français ou zh_CN pour le chinois (Chine). Pour obtenir la liste des langues prises en charge par ThingWorx, consultez la section Langues prises en charge ci-dessous.
|
Paramètres régionaux de l'utilisateur connecté qui exécute la requête
|
||
|
startDate
|
Date et heure. La requête commence à rechercher les messages d'audit, à partir des messages correspondant à la date et l'heure spécifiées (DATETIME).
|
Non spécifié
|
||
|
endDate
|
Date et heure. La recherche de messages d'audit s'interrompt lorsque la date et l'heure spécifiées sont atteintes (DATETIME).
|
Non spécifié
|
||
|
query
|
Chaîne de requête (au format JSON) Un exemple de requête JSON vous est proposé à la suite de cette table.
Ce paramètre est utilisé dans plusieurs services ThingWorx. Pour des détails complets, consultez la rubrique Paramètre de requête pour les services de requête.
|
N/A
|
Par défaut, une requête renvoie 500 lignes. Pour modifier le nombre de lignes renvoyées par la requête, vous pouvez définir le paramètre maxItems sur le nombre de votre choix. Le nombre maximal de lignes que vous pouvez définir pour le paramètre maxItems est limité. Par défaut, cette limite est de 5 000 lignes. Un administrateur système peut définir cette limite lors de la configuration du sous-système d'audit. Les administrateurs système doivent se reporter à la rubrique Configuration du sous-système d'audit.
Toutefois, si vous prévoyez un nombre de résultats considérables, utilisez un attribut QUERY.
Voici un exemple de requête au format JSON :
Exemple 1. Requête au format JSON
La requête au format JSON suivante montre comment vous pouvez créer les filtres, les critères de tri et la pagination à utiliser avec le service QueryAuditHistoryWithQueryCriteria (implémentation de type Persistance directe) :
{
"filters": {
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": false
},
"sorts": {
"fieldName": "timestamp",
"isAscending": true,
"isCaseSensitive": true
},
"pagination":{
"pageSize":50,
"pageNumber":2
}
}
Recherche à partir du contexte d'un objet
Le service QueryAuditHistory d'un objet fonctionne de la même manière que les services QueryAuditHistory et QueryAuditHistoryWithQueryCriteria sur le sous-système d'audit, mais avec des restrictions supplémentaires. Le comportement général et tous les paramètres de ce service sont identiques aux services du sous-système d'audit. Les restrictions de ce service sont les suivantes :
1. Vérifie si l'utilisateur qui appelle le service est membre du groupe Auditeurs. Dans le cas contraire, les résultats sont filtrés selon les autorisations de cet utilisateur.
2. Lorsque le service QueryAuditHistory est appelé à partir d'un objet particulier, la recherche utilise les identificateurs d'entité au lieu des noms.
La table suivante décrit les paramètres du service QueryAuditHistory sur un objet :
|
Nom de paramètre
|
Description
|
|---|---|
|
maxItems
|
Nombre maximal d'éléments à renvoyer. Le type de base de ce paramètre est NUMBER.
|
|
startDate
|
Date d'audit la plus ancienne à interroger. Le type de base de ce paramètre est DATETIME.
|
|
endDate
|
Date d'audit la plus récente à interroger. Le type de base de ce paramètre est DATETIME.
|
|
query
|
Définition de la requête. Le type de base de ce paramètre est QUERY. Formatez la requête en tant qu'objet JSON.
|
|
locale
|
Paramètres régionaux localizationTable utilisés pour localiser les résultats. Le type de base de ce paramètre est STRING.
|
Pour prendre en charge les requêtes avec contraintes de contexte sur les objets pour le sous-système d'audit, un groupe d'utilisateurs a été ajouté, appelé Auditeurs. Ce groupe permet aux utilisateurs non-administrateurs de consulter les résultats complets du service QueryAuditHistory lorsqu'il est appelé depuis des objets pour lesquels ils disposent des autorisations de visibilité.
Par exemple, un administrateur crée un objet appelé ExampleThing et autorise User_A, membre du groupe Auditeurs, à y accéder. L'administrateur a également donné accès à cet objet à User_B, qui n'appartient à aucun groupe d'utilisateurs spécial. Si chaque utilisateur exécute le service QueryAuditHistory à partir de ExampleThing, les résultats attendus sont les suivants :
|
Utilisateur
|
Appartenance au groupe
|
Résultat attendu
|
|---|---|---|
|
Administrateur
|
Administrateurs
|
La table InfoTable renvoyée contient toutes les entrées d'audit associées à ExampleThing.
|
|
User_A
|
Auditeurs
|
La table InfoTable renvoyée contient toutes les entrées d'audit associées à ExampleThing.
|
|
User_B
|
Aucun groupe spécial
|
La table InfoTable renvoyée contient des entrées d'audit associées à User_B uniquement.
|
Interrogation des données d'audit héritées lorsque la persistance directe est activée
Lorsque la persistance directe est activée dans la configuration du sous-système d'audit, tous les services qui traitent ou gèrent les données basculent vers le modèle de persistance directe : seules les données générées lorsque ce modèle est activé sont accessibles. Pour permettre aux utilisateurs d'accéder à leurs données héritées enregistrées (entrées de table de données dans l'entité AuditDataTable), il est nécessaire de présenter/fournir une autre méthode d'accès à ces enregistrements.
 |
Il est recommandé d'exporter les données d'audit héritées vers le stockage froid au cours d'une maintenance avant de basculer vers la persistance directe. Lorsque cela n'est pas possible, il existe des solutions de contournement utiles décrites dans cette rubrique.
|
Vous pouvez utiliser l'entité AuditDataTable pour interroger des informations d'audit 1.0 (héritées). L'entité AuditDataTable fait partie d'un sous-ensemble d'entités de table de données auxquelles des restrictions supplémentaires ont été ajoutées, notamment l'interdiction de mise à jour des entrées, et peut utiliser la plupart des mêmes services que d'autres entités de table de données.
QueryDataTableEntries est l'un de ces services. Il vous permet d'utiliser des tags de données, une source et une requête JSON pour filtrer les résultats récupérés.
|
|
Les tags de données des entrées d'audit sont toujours vides.
|
Pour exécuter ce service, spécifiez les mêmes paramètres de requête JSON que lors de l'exécution des QueryAuditHistory ou QueryAuditHistoryWithQueryCriteria. L'exemple de requête JSON ci-après utilise des filtres d'horodatage et d'utilisateur et trie les entrées du plus récent au plus ancien.
|
|
La pagination n'est pas prise en charge avec les services de requête sur table de données.
|
Exemple 2. Requête 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
}
]
}
|
|
Ce service renvoie des enregistrements d'audit bruts (non traduits), ainsi que des informations d'entrée d'audit. Pour plus d'informations sur la traduction, reportez-vous à la section suivante.
|
Ecriture d'un service QueryAuditHistory personnalisé
En raison de la nature des données renvoyées par le service QueryDataTableEntries, il n'est pas toujours adapté aux besoins de l'utilisateur moyen. Pour obtenir les mêmes informations qu'avec les services QueryAuditHistory et QueryAuditHistoryWithQueryCriteria du sous-système d'audit, les développeurs peuvent créer un service wrapper. Ce service doit effectuer les tâches de base suivantes :
• Interroger des données à partir de AuditDataTable
• Appliquer la traduction des jetons de localisation (champs message et category)
• Appliquer une substitution de variable pour les remplacements d'arguments de message (champ message)
• Supprimer les informations d'entrée de table de données
Vous trouverez ci-après un exemple de ce type de service.
Exemple 3. Service QueryAuditHistory personnalisé
Ce service est écrit en JavaScript simple et peut être utilisé sur toute entité ThingWorx appropriée.
// 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;
}
Langues prises en charge
La figure suivante illustre les langues prises en charge par ThingWorx :
