Filter audit data through API
Introduction¶
To reduce the quantity of data retrieved, several types of filter can be applied:
- to header properties
- to dimensional parameters
Query parameter¶
$filter=()
Filter heading properties: filter by date¶
Property¶
dateTimeUtc (format: ISO 8601, UTC)
Description¶
Filter data based on operation date.
Operators¶
| Operator | Net result |
|---|---|
| gt | Shows records from dates after the selected date. |
| lt | Shows records from dates prior to the selected date. |
| ge | Shows records from or after the selected date. |
| le | Shows records from or prior to the selected date. |
Example
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/dataprocessing/SOLLECITATORE_ CERTIFICAZIONI?$filter=(dateTimeUtc lt 2020-08-21T08:01:26.758Z)
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/CONTO?$filter=(dateTimeUtc gt 2020- 12- 21T08:00:00.000Z) and (dateTimeUtc lt 2020- 12-21T12:00:00.000Z)
Particular features of the dateTimeUtc property¶
The value stored in the database is more precise than can be specified in the endpoint. For this reason, the search results will be based on the level of precision of the endpoint.
Filter header properties: string-type data¶
Property¶
oid, status, user, database, client, ipClient, editType and key.
Description¶
Filter data based on header properties.
Operators¶
| Operator | Net result |
|---|---|
| eq | Shows records for which the parameter is the same as the one reported in quotes. |
| ne | Shows records for which the parameter is different from the one reported in quotes. |
Example
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/UTENTE?$filter=(clientIp eq '10.10.10.10')
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/UTENTE?$filter=(user eq 'UTENTEA') or (user eq 'UTENTEB')
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/UTENTE?$filter=(key eq '%7BTEST, GRAFFE%7D')
Note: if the key property contains braces {}, encoding must be performed as in the example.
Filter dimensional parameters¶
Description¶
This filter is applied to the data processing APIs. It filters data by applying dimensional parameters, invoking the endpoint which returns the metadata.
Operators¶
| Operator | Net result |
|---|---|
| eq | Shows records whose header string is the same as the one reported in quotes. |
| ne | Shows records with a different header string from the one reported in quotes. |
Example
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/dataprocessing/ESPLOSIONE(periodo eq '10')
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/ESPLOSIONE(raccolta ne 'ACT')
In the following two examples, the records shown are those where the “currency” parameter has ‘no value’:
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/AGGIORNA_PARAM_BANCARIE(valuta eq 'no value')
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/AGGIORNA_PARAM_BANCARIE(valuta eq null)
Note: it is not possible to filter for a parameter that has not been specified (e.g. “currency” : null).
Pagination of results¶
Description¶
Makes it possible to subdivide the data returned on pages with specific characteristics. This type of query allows retrieval of a maximum of 10,000 elements.
Parameters¶
| Parameter | Net result |
|---|---|
| $top=N1 | (N1 positive integer) Reports N results. |
| $skip=N2 | (N2 positive integer) Omits the first N results. |
| ?$top=N1&skip=N2 | Combines the results of the two parameters. |
Note: It is possible to use several query parameters by concatenating them with the & symbol.
Example
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/dataprocessing/SOLLECITATORE_ CERTIFICAZIONI?$top=2&$skip=5
http://127.0.0.1:8080/tagetikcpm/api/audit/v1/datamanagement/CONTO?$top=5
Results sorting¶
Data can be sorted by using:
| Parameter | Net result |
|---|---|
| $orderby=P1 ORD,P2 ORD, ... | (P1, P2, ...) These represent the set of properties you want to sort on (you can sort by one or more properties) (ORD) This represents the asc or desc sorting type: for ascending and descending sorting respectively. |
Note: By default, if no sort type is specified, the ascending sort will be applied.
The properties on which the sorting can be performed are the header properties: oid, dateTimeUtc, status, user, database (not present for the user login api), client, ipClient.
Moreover, sorting by key is available for the data management APIs
Several properties can be combined by following ?$orderby=P1 ORD,P2 ORD,P3 ORD.
Example
http://127.0.0.1:8080/tagetikcpm/api/audit/v2/datamanagement/CONTO?$orderby=dateTimeUtc desc
http://127.0.0.1:8080/tagetikcpm/api/audit/v2/datamanagement/CONTO?$orderby=user asc,dateTimeUtc
Caching system¶
To optimise the performance of the query through APIs, a caching system has been introduced through the system property it.grupposervizi.easy.audit.odata.cache.cron.
The cron expression contains six asterisks (*) which indicate the following fields:
- seconds
- minutes
- hour
- day
- month
- year
Note: without that system property, the default value is 0 30 * * * *, and therefore a refresh is performed every 30 minutes.
The following data are saved in the cache:
- dimensional characteristics, for data processing
- all the properties of the edited table, for the management of the tables and data
Changes made after the cache has been built will only appear after the next cache update. For data processing, the header properties and parameters present in the cache are always displayed.