Búsqueda de datos de auditoría (consultas, persistencia directa)
Si desea buscar datos de auditoría, utilice el servicio QueryAuditHistoryWithQueryCriteria. El subsistema de auditoría soporta las funciones de filtrado, clasificación y paginación para este servicio a través del parámetro query. Aprovecha la capacidad de una consulta de base de datos para filtrar y clasificar los datos. También toma entradas de widgets especiales que se han creado para mejorar el filtrado y proporcionar paginación para los resultados.
 |
También se puede utilizar el servicio QueryAuditHistory original. Sin embargo, el servicio quedará obsoleto en una versión futura de ThingWorx Platform. Si prefiere utilizarlo, consulte el tema Búsqueda de datos de auditoría (consultas y tabla de datos) para obtener más información.
|
Este tema se organiza del siguiente modo:
2. Búsqueda con contexto restringido
Conceptos básicos de la consulta
El servicio QueryAuditHistoryWithQueryCriteria tiene el siguiente formato:
QueryAuditHistoryWithQueryCriteria(maxItems [INTEGER], startDate [DATETIME], endDate [DATETIME],
auditCategory[STRING],query[QUERY], locale[STRING])
En la siguiente tabla se describen los parámetros de este servicio:
|
Parámetro
|
Descripción
|
Valor por defecto
|
||
|---|---|---|---|---|
|
maxItems
|
El número máximo de resultados que se devolverán de la consulta. (INTEGER)
|
500 elementos
|
||
|
locale
|
La abreviatura del nombre del idioma en el que se deben devolver los resultados. (STRING). Por ejemplo, fr para francés o zh_CN para chino (China). Para obtener una lista de configuraciones regionales que ThingWorx soporta, consulte el apartado Configuraciones regionales soportadas a continuación.
|
La configuración regional del usuario conectado que envía la consulta.
|
||
|
startDate
|
Fecha y hora. La consulta empieza a buscar mensajes de auditoría a partir de la fecha y hora que el usuario especifica aquí. (DATETIME)
|
No especificado
|
||
|
endDate
|
Fecha y hora. La consulta deja de buscar mensajes de auditoría cuando la fecha/hora de los mensajes alcanza la fecha y hora que el usuario especifica aquí. (DATETIME)
|
No especificado
|
||
|
query
|
Una cadena de consulta (en formato JSON). Después de la tabla se muestra un ejemplo de una consulta JSON que se puede utilizar.
Este parámetro se utiliza en varios servicios ThingWorx. Para obtener detalles completos, consulte Parámetro de consulta para servicios de consulta.
|
N/D
|
Por defecto, una consulta devuelve 500 filas. Para cambiar el número de filas que la consulta devuelve, defina el parámetro maxItems en el número de filas deseado. Hay un límite máximo en el número de filas que se pueden especificar para el parámetro maxItems. Por defecto, el límite es 5.000 filas. Un administrador del sistema puede cambiar este límite al configurar el subsistema de auditoría. Los administradores del sistema deben consultar el tema Configuración del subsistema de auditoría.
Sin embargo, si se prevé un número significativamente grande de resultados, se debe utilizar QUERY.
A continuación, se muestra un ejemplo de una consulta con formato JSON:
Ejemplo 1. Consulta con formato JSON
En la siguiente consulta con formato JSON se muestra cómo se pueden construir los filtros, la clasificación y la paginación que se utilizarán con el servicio QueryAuditHistoryWithQueryCriteria (implementación de la persistencia directa):
{
"filters": {
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": false
},
"sorts": {
"fieldName": "timestamp",
"isAscending": true,
"isCaseSensitive": true
},
"pagination":{
"pageSize":50,
"pageNumber":2
}
}
Búsqueda desde el contexto de una cosa
El servicio QueryAuditHistory de una cosa funciona de forma similar a los servicios QueryAuditHistory y QueryAuditHistoryWithQueryCriteria en el subsistema de auditoría, pero con restricciones adicionales. El comportamiento general y todos los parámetros de este servicio son los mismos que los servicios del subsistema de auditoría. A continuación, se indican las restricciones de este servicio:
1. Se verifica si el usuario que invoca el servicio es miembro del grupo auditores. De lo contrario, los resultados se filtran según los permisos del usuario.
2. Cuando el servicio QueryAuditHistory se invoca desde una cosa determinada, en la búsqueda se utilizan identificadores de entidad en lugar de nombres.
En la siguiente tabla se describen los parámetros para el servicio QueryAuditHistory en una cosa:
|
Nombre del parámetro
|
Descripción
|
|---|---|
|
maxItems
|
El número máximo de elementos que se devolverán. El tipo base de este parámetro es NUMBER.
|
|
startDate
|
La fecha de auditoría más temprana que se debe consultar. El tipo base de este parámetro es DATETIME.
|
|
endDate
|
La fecha de auditoría más reciente que se debe consultar. El tipo base de este parámetro es DATETIME.
|
|
query
|
La definición de la consulta. El tipo base de este parámetro es QUERY. Formatee la consulta como objeto JSON.
|
|
locale
|
La configuración regional localizationTable que se utiliza para localizar los resultados. El tipo base de este parámetro es STRING.
|
Para soportar consultas restringidas por contexto de cosa para el subsistema de auditoría, se ha añadido un grupo de usuarios, llamado Auditores. Este grupo permite a los usuarios no administrativos ver los resultados completos del servicio QueryAuditHistory cuando se llama desde cosas para las que tiene visibilidad.
Por ejemplo, un administrador crea una cosa llamada ExampleThing y da acceso a esta cosa a User_A, que es miembro del grupo de auditores. El administrador también da acceso a esta cosa a User_B, que no se encuentra en ningún grupo de usuarios especial. Si cada usuario ejecuta el servicio QueryAuditHistory desde ExampleThing, los resultados esperados son los siguientes:
|
Usuario
|
Afiliación a grupo
|
Resultado esperado
|
|---|---|---|
|
Administrador
|
Administradores
|
El objeto InfoTable que se devuelve contiene todas las entradas de auditoría relacionadas con ExampleThing.
|
|
User_A
|
Auditores
|
El objeto InfoTable que se devuelve contiene todas las entradas de auditoría relacionadas con ExampleThing.
|
|
User_B
|
Ningún grupo especial
|
El objeto InfoTable que se devuelve contiene las entradas de auditoría asociadas solo a User_B.
|
Consulta de datos de auditoría heredados mientras se activa la persistencia directa
Aunque se active la persistencia directa en la configuración del subsistema de auditoría y todos los servicios que procesan o gestionan datos se cambien al modelo de persistencia directa, solo se podrá acceder a los datos generados cuando esté activado. Para permitir que los usuarios accedan a sus datos guardados con el formato heredado (entradas de DataTable en la entidad AuditDataTable), se debe explicar/proporcionar una forma alternativa de acceder a esos registros.
 |
Se recomienda exportar los datos de auditoría heredados a almacenamiento en frío durante una ventana de mantenimiento antes de cambiar a la persistencia directa. Si no es siempre posible, en el resto de esta sección se ofrecen soluciones útiles.
|
Se puede utilizar la entidad AuditDataTable para consultar la información de auditoría 1.0 ("heredada"). La entidad AuditDataTable forma parte de un subconjunto de entidades DataTable a las que se han añadido algunas restricciones adicionales, como no permitir la actualización de entradas, y pueden utilizar la mayoría de los mismos servicios que otras entidades DataTable.
Uno de estos servicios es QueryDataTableEntries. Este servicio permite utilizar las etiquetas de datos, el origen y la consulta JSON para filtrar los resultados recuperados.
|
|
Las etiquetas de datos de las entradas de auditoría siempre están vacías.
|
Para ejecutar este servicio, especifique los mismos parámetros de consulta JSON que cuando se ejecuta QueryAuditHistory o QueryAuditHistoryWithQueryCriteria. En el siguiente ejemplo de consulta JSON se utilizan filtros de usuario y fecha, y se clasifican las entradas de la más reciente a la más antigua.
|
|
La paginación no se soporta con los servicios de consulta de tabla de datos.
|
Ejemplo 2. Consulta 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
}
]
}
|
|
Este servicio devuelve registros de auditoría en bruto (sin traducir), junto con la información de entrada de auditoría. Para obtener información sobre la traducción, consulte la siguiente sección.
|
Escritura de un servicio QueryAuditHistory personalizado
Debido a la naturaleza de los datos devueltos por el servicio QueryDataTableEntries, es posible que no siempre se ajusten a las necesidades del usuario medio. Para obtener la misma información que en los servicios QueryAuditHistory y QueryAuditHistoryWithQueryCriteria del subsistema de auditoría, los desarrolladores pueden escribir un servicio empaquetador. Este servicio debe realizar las siguientes tareas básicas:
• Consultar datos de AuditDataTable
• Aplicar la traducción de los tokens de localización (campos message y category)
• Aplicar la sustitución de variables para los reemplazos de argumentos del mensaje (campo message)
• Quitar información de entrada de DataTable
A continuación, se muestra un ejemplo de este tipo de servicio.
Ejemplo 3. Servicio QueryAuditHistory personalizado
Este servicio se escribe en JavaScript sencillo y se puede utilizar en cualquier entidad de ThingWorx adecuada.
// 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;
}
Configuraciones regionales soportadas
En la siguiente figura se muestran las configuraciones regionales que ThingWorx soporta:
