Ricerca dei dati di verifica (interrogazioni, persistenza diretta)
Quando si desidera eseguire la ricerca dei dati di verifica, utilizzare il servizio QueryAuditHistoryWithQueryCriteria. Il sottosistema Verifica supporta le funzionalità di filtraggio, ordinamento e impaginazione per questo servizio tramite il parametro query. Sfrutta la capacità di interrogazione dei database di filtrare e ordinare i dati. Prende inoltre spunto da widget speciali creati per migliorare il filtraggio e fornire l'impaginazione per i risultati.
 |
È inoltre possibile utilizzare il servizio QueryAuditHistory originale. Tuttavia questo servizio viene contrassegnato come obsoleto in una release futura di ThingWorx Platform. Se si desidera usarlo, fare riferimento a Ricerca dei dati di verifica (interrogazioni, tabella dati) per informazioni dettagliate.
|
Questo argomento è organizzato nel modo seguente:
2. Ricerca con contesto vincolato
Nozioni di base sull'interrogazione
Il servizio QueryAuditHistoryWithQueryCriteria ha il formato seguente:
QueryAuditHistoryWithQueryCriteria(maxItems [INTEGER], startDate [DATETIME], endDate [DATETIME],
auditCategory[STRING],query[QUERY], locale[STRING])
Nella tabella seguente sono descritti i parametri di questo servizio:
|
Parametro
|
Descrizione
|
Valore di default
|
||
|---|---|---|---|---|
|
maxItems
|
Numero massimo di risultati che l'interrogazione può restituire. (INTEGER)
|
500 elementi
|
||
|
locale
|
Abbreviazione del nome della lingua in cui restituire i risultati. (STRING). Ad esempio è possibile utilizzare fr per il francese o zh_CN per il cinese (Cina). Per un elenco delle lingue supportate da ThingWorx, fare riferimento a Lingue supportate di seguito.
|
Lingua dell'utente connesso che ha inviato l'interrogazione
|
||
|
startDate
|
Data e ora. L'interrogazione inizia a cercare i messaggi di verifica, a partire dalla data e dall'ora specificate qui (DATETIME).
|
Non specificato
|
||
|
endDate
|
Data e ora. L'interrogazione interrompe la ricerca dei messaggi di verifica quando la data e l'ora dei messaggi raggiungono la data e l'ora specificate qui (DATETIME).
|
Non specificato
|
||
|
query
|
Una stringa di interrogazione (in formato JSON). Di seguito è riportato un esempio di interrogazione JSON che è possibile utilizzare.
Questo parametro viene utilizzato in numerosi servizi di ThingWorx. Per i dettagli completi, fare riferimento a Parametro di interrogazione per servizi di interrogazione.
|
N/D
|
Per default, un'interrogazione restituisce 500 righe. Per modificare il numero di righe restituite dall'interrogazione, è possibile impostare il parametro maxItems sul numero desiderato di righe. Vi è un limite superiore al numero di righe che è possibile specificare per il parametro maxItems. Per default, il limite è 5000 righe. Un amministratore di sistema imposta questo limite quando configura il sottosistema Verifica. Gli amministratori di sistema devono fare riferimento a Configurazione del sottosistema Verifica.
Tuttavia, se si prevede un numero significativamente elevato di risultati, utilizzare QUERY.
Di seguito è riportato un esempio di un'interrogazione in formato JSON.
Esempio 1. Interrogazione in formato JSON
Nell'interrogazione in formato JSON seguente viene illustrato come costruire i filtri, l'ordinamento e l'impaginazione da utilizzare con il servizio QueryAuditHistoryWithQueryCriteria (implementazione della persistenza diretta):
{
"filters": {
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": false
},
"sorts": {
"fieldName": "timestamp",
"isAscending": true,
"isCaseSensitive": true
},
"pagination":{
"pageSize":50,
"pageNumber":2
}
}
Ricerca dal contesto di un oggetto
Il servizio QueryAuditHistory per un oggetto funziona in modo analogo ai servizi QueryAuditHistory e QueryAuditHistoryWithQueryCriteria del sottosistema Verifica, ma con restrizioni aggiuntive. Il comportamento generale e tutti i parametri di questo servizio sono gli stessi dei servizi del sottosistema Verifica. Di seguito sono riportate le limitazioni del servizio.
1. Controlla se l'utente che richiama il servizio è un membro del gruppo di revisori. In caso contrario, i risultati vengono filtrati dai permessi dell'utente.
2. Quando il servizio QueryAuditHistory viene richiamato da un oggetto specifico, la ricerca utilizza gli identificatori di entità anziché i nomi.
Nella tabella seguente vengono descritti i parametri per il servizio QueryAuditHistory per un oggetto:
|
Nome parametro
|
Descrizione
|
|---|---|
|
maxItems
|
Numero massimo di elementi da restituire. Il tipo di base di questo parametro è NUMBER.
|
|
startDate
|
Prima data di verifica per l'interrogazione. Il tipo di base di questo parametro è DATETIME.
|
|
endDate
|
Ultima data di verifica per l'interrogazione. Il tipo di base di questo parametro è DATETIME.
|
|
query
|
Definizione dell'interrogazione. Il tipo di base di questo parametro è QUERY. Formattare l'interrogazione come oggetto JSON.
|
|
locale
|
Lingua della tabella di localizzazione utilizzata per localizzare i risultati. Il tipo di base di questo parametro è STRING.
|
Per supportare le interrogazioni con vincoli di contesto dell'oggetto per il sottosistema Verifica, è stato aggiunto un gruppo di revisori. Questo gruppo consente agli utenti non amministratori di visualizzare i risultati completi del servizio QueryAuditHistory durante la chiamata dagli oggetti per i quali hanno visibilità.
Ad esempio, un amministratore crea un oggetto denominato ExampleThing e concede l'accesso a questo oggetto a User_A, che è un membro del gruppo di revisori. L'amministratore concede inoltre l'accesso a questo oggetto a User_B, che non è presente in alcun gruppo di utenti speciale. Se ogni utente esegue il servizio QueryAuditHistory da ExampleThing, i risultati previsti sono i seguenti:
|
Utente
|
Appartenenza al gruppo
|
Risultato previsto
|
|---|---|---|
|
Amministratore
|
Amministratori
|
La InfoTable restituita contiene tutte le voci di verifica correlate a ExampleThing.
|
|
User_A
|
Revisori
|
La InfoTable restituita contiene tutte le voci di verifica correlate a ExampleThing.
|
|
User_B
|
Nessun gruppo speciale
|
La InfoTable restituita contiene solo le voci di verifica associate a User_B.
|
Interrogazione dei dati di verifica legacy mentre è attivata la persistenza diretta
Mentre la persistenza diretta è attivata nella configurazione del sottosistema Verifica, tutti i servizi che elaborano o gestiscono i dati passano al modello di persistenza diretta. Solo i dati generati durante l'attivazione sono accessibili. Per consentire agli utenti di accedere ai dati salvati nel formato legacy (voci DataTable nell'entità AuditDataTable), è necessario che l'accesso a tali record sia spiegato o specificato.
 |
È consigliabile esportare i dati di verifica legacy nello spazio di archiviazione non in linea sicura durante un periodo di manutenzione prima di passare alla persistenza diretta. Se ciò non è possibile, leggere il resto di questa sezione per trovare una soluzione alternativa.
|
È possibile utilizzare l'entità AuditDataTable per interrogare le informazioni di Audit 1.0 ("legacy"). L'entità AuditDataTable fa parte di un sottoinsieme di entità DataTable che comprendono alcune restrizioni aggiuntive, ad esempio il divieto di aggiornamento delle voci, e può utilizzare la maggior parte degli stessi servizi delle altre entità DataTable.
Un servizio di questo tipo è QueryDataTableEntries. Questo servizio consente di utilizzare i tag dati, l'origine e l'interrogazione JSON per filtrare i risultati recuperati.
|
|
I tag dati per le voci di verifica sono sempre vuoti.
|
Per eseguire questo servizio, specificare gli stessi parametri di interrogazione JSON di quando si esegue QueryAuditHistory o QueryAuditHistoryWithQueryCriteria. Nell'esempio di interrogazione JSON seguente vengono utilizzati i filtri utente e data e ora e le voci vengono ordinate dalla più recente alla meno recente.
|
|
L'impaginazione non è supportata con i servizi di interrogazione della tabella dati.
|
Esempio 2. Interrogazione 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
}
]
}
|
|
Questo servizio restituisce record di verifica non elaborati (non tradotti), nonché informazioni sulle voci di verifica. Per informazioni sulla traduzione, fare riferimento alla sezione successiva.
|
Scrittura di un servizio QueryAuditHistory personalizzato
A causa della natura dei dati restituiti dal servizio QueryDataTableEntries a volte può non soddisfare le esigenze dell'utente medio. Per ottenere le stesse informazioni contenute nei servizi QueryAuditHistory e QueryAuditHistoryWithQueryCriteria del sottosistema Verifica, gli sviluppatori possono scrivere un servizio wrapper. Questo servizio deve eseguire i task di base seguenti.
• Interrogazione dei dati da AuditDataTable
• Applicazione della traduzione dei token di localizzazione (campi message e category)
• Applicazione della sostituzione delle variabili per le sostituzioni degli argomenti dei messaggi (campo message)
• Rimozione delle informazioni sulle voci DataTable
Di seguito è riportato un esempio di tale servizio.
Esempio 3. Servizio QueryAuditHistory personalizzato
Questo servizio è scritto in JavaScript semplice e può essere utilizzato per qualsiasi entità ThingWorx appropriata.
// 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;
}
Lingue supportate
Nella figura seguente sono riportate le lingue supportate da ThingWorx:
