The method enables you to search your site's audit log using an SQL-like query. A short delay is possible between the writing of audit log data and its availability in queries.
Only certain APIs and actions are audited (logged). For example, API calls using application keys are not audited. For a complete list of logged APIs, see our Audit Log documentation.
Query Syntax Specification
Gigya queries use the same syntax rules as SQL, however not all standard SQL keywords are available.
When querying for text/strings, values must be wrapped in quotes. e.g.,
- Unsupported SQL syntax in the query string (e.g., HAVING) will produce an error.
- The query string clauses must be ordered in the following way:
- Encrypted fields are decrypted during searches but comparison operators (>, >=, <, <=) and regex expressions are not available on these fields. The Contains keyword can be used for case-insensitive searches on encrypted fields but does not support partial strings.
SELECT - The "SELECT" statement may only be used to select all fields ( * ).
FROM - Name of the data source. Only one data source is supported. Audit queries must state "FROM auditLog" (audit.search).
WHERE - The "WHERE" clause defines conditions for selecting items from the collection. Supported operators:
- > , >=, <, <= , = , != - Only = and != can be used with encrypted fields. The "=" operand is case sensitive.
- AND , OR
- in() - only retrieve items if the field contains one of the list values. For example: 'SELECT * FROM auditLog WHERE errCode in ("0", "400006", "400009")'.
- is null , is not null
- regex ('<regex-pattern>') - defines a search term using regex formatting. The regex syntax can be found in: Regular Expression Language Reference. Regex patterns cannot be used on encrypted fields.
ORDER BY - The "order by" clause specifies a list of fields by which to sort the result objects.
LIMIT - Using the "LIMIT" clause, you may specify the maximum number of returned result objects. If not specified, the default is 300. The maximum limit value accepted is 10000. If the search is sent with openCursor = true, LIMIT will set the batch size. LIMIT must be the last item in the query. Example:
Please note, when using a cursor, the number of results in a batch is not guaranteed.
START - The "START" clause (not an SQL standard clause) may be used for paging. The clause specifies the start index from which to return result objects. Start can not be used with openCursor.
The 'SELECT - FROM - WHERE - ORDER BY' query creates an (internal) indexed list of objects. By also using the START & LIMIT clauses, you will receive a subset of this list, starting with the start index and ending with start+limit index.
Note: When implementing paging, there is no guarantee that there will be no duplications or that recently added data will show up in the query results.
Fields Available in Audit Log Queries
When querying the Audit Log, you may use the following fields in the WHERE clause:
us1.gigya.com- For the US data center.
eu1- For the European data center.
au1- For the Australian data center.
ru1- For the Russian data center.
cn1- For the Chinese data center.
If you are not sure of your site's data center, see Finding Your Data Center.
|||query||string||The SQL-like query used to search the audit log. Please refer to the Query language specification above. Note that Gigya field names are case-sensitive, i.e., uid is NOT the same as UID.|
|||cursorId||string||The cursor ID that contains the nextCursorId value received in the first search call. You cannot pass both cursorId and query on the same request - cursorId brings the next page for the search for which it was opened. In addition, the time between search requests using a cursorId must not exceed 5 minutes. |
Each request should contain a different cursorId obtained from the response of the previous request (not the first) using the nextCursorId field. The exception to this rule is when a request fails or when a particular result set needs to be re-sent; in this case, resend the same cursorID (as long as it has not expired) to receive its associated result set.
|||openCursor||Boolean||When set to true, the search response will include, in addition to the first page, another field named nextCursorId, which is used to fetch the next batch of results. This parameter should only be used on the first request and later should be removed from the request. When openCursor is true, the Limit clause sets the number of results returned in the batch. |
You cannot use a cursor if you have a group by or when using start.
Each REST API request must contain identification and authorization parameters.
Some REST APIs may function without these authorization parameters, however, when that occurs, these calls are treated as client-side calls and all client-side rate limits will apply. In order to not reach client-side IP rate limits that may impact your implementation when using server-to-server REST calls, it is Recommended Best Practice to always sign the request or use a secret. A non-exhaustive list of REST APIs that this may apply to are as follows:
Please refer to the Authorization Parameters section for details.
In order to make API calls to audit.search, you must pass a user key, user secret and API key. Partner secrets cannot be used with audit.search.
|objectsCount||integer||The number of objects returned in the "results" array.|
|totalCount||integer||The total number of objects that satisfy the query in the DB. This is useful when fetching a limited amount using the " limit " parameter.|
|statusCode||integer||The HTML status code of the operation.|
|statusReason||string||A short textual description of the statusCode.|
|results||Array||An array of auditLog objects.|
A field that does not contain data will not appear in the response.
Sample Query and Response