Retrieve log
Analytics allows you to query data collected in BigQuery via an API.
Reference: Analytics Operation Structure
Preparation¶
To use the data query API, you must complete the application for the log query API through the Hive Console → Analytics → Log Definition menu. Once the application is completed, AccessKey and SecondAccessKey will be issued for the log you can query. Both AccessKey and SecondAccessKey function the same, with the SecondAccessKey being an additional key issued for use when there are issues with the AccessKey.
※ AccessKey and SecondAccessKey should be kept confidential and must not be exposed externally. ※ If AccessKey or SecondAccessKey is exposed, they must be refreshed or revoked immediately.
How to apply for Data Query OpenAPI¶
Select the game for which you want to issue an AccessKey in the Log Definition menu, then click on the log name you want to issue to enter the detail page. Click the 'Apply for OpenAPI' button and then press the 'Confirm' button to issue the key.
How to renew or revoke AccessKey¶
Select the game for which you want to renew or revoke the AccessKey in the Log Definition menu, then click on the log name to enter the detail page. Renew: Click the 'Renew' button to issue a new AccessKey, and the previously issued AccessKey will become unusable. Revoke: Click the 'Revoke' button to delete the existing AccessKey, and this key will no longer be usable.
Common API Information¶
| Service Type | Domain |
| Production | analytics-openapi.com2us.com |
| Sandbox | sandbox-analytics-openapi.com2us.com |
- Required Header Parameter: X-Analyitcs-Accesskey You must include this key value in the request header to verify access rights for the OpenAPI data query.
Data Query API¶
-
URL: https://{domain}/data/query/{logName}
-
Description: Retrieve data that matches the specified query conditions.
Request (POST, application/json)¶
| Name | Type | Required | Description | Example |
| startDate | STRING | O | Search start time in UTC (format: yyyy-MM-dd hh:mm:ss) (Required if sending nextToken value: No) | 2024-01-01 00:00:00 |
| endDate | STRING | O | Search end time in UTC (format: yyyy-MM-dd hh:mm:ss) (Required if sending nextToken value: No) | 2024-01-02 00:00:00 |
| properties | JSON | X | JSON formatted search conditions {BigQuery field name: search value, ...} | {"vid":123, "market":"A"} |
| QueryType | STRING | X | "0": Include only custom fields, "1": Include all fields (Default: "0") | "0" |
| nextPageToken | STRING | X | Token value to retrieve the next page of data, returns 20 data per page, no other parameters are required when querying with this value. | f3ebf4b6859a4f248b283a4fff1ded13 |
Response (application/json)¶
| Name | Type | Description | Example |
| totalRows | INTEGER | Total number of rows in the search results | 123 |
| nextPageToken | STRING | Token for retrieving the next page * If it is the last page, null | f3ebf4b6859a4f248b283a4fff1ded13 |
| datas | LIST[JSON] | Retrieved data | [ { "dateTime": "2024-01-01T23:38:24Z", "vid": 123, "characterLv": 1 }, ... ] |
Request example¶
curl -X 'POST' \
'https://sandbox-analytics-openapi.com2us.com/data/query/hive_login_log' \
-H 'accept: application/json' \
-H 'X-Analyitcs-Accesskey: Your access key' \
-H 'Content-Type: application/json' \
-d '{
"startDate": "2024-04-16 00:00:00",
"endDate": "2024-04-17 00:00:00"
}'
Data check API¶
- URL: https://{domain}/data/check/{logName}
- Description: Checks whether logs matching the search criteria exist in BigQuery within the last year.
Request (POST, application/json)¶
| Name | Type | Required | Description | Example |
| properties | JSON | O | JSON formatted search conditions {BigQuery field name: search value, ...} | {"guid":"52e10350-fe3d-487f-8631-1dc640010c87"} |
Response (application/json)¶
| Name | Type | Description | Example |
| isExists | BOOLEAN | Whether the data exists | true |
| datas | LIST[JSON] | The latest 5 sample values of existing data Includes dateTime and guid values along with field values matching the search criteria. | [ { "vid": 123, "dateTime": "2024-04-16T23:09:24Z", "guid": "52e10350-fe3d-487f-8631-1dc640010c87" }, ... ] |
Request example¶
curl -X 'POST' \
'https://sandbox-analytics-openapi.com2us.com/data/check/hive_login_log' \
-H 'accept: application/json' \
-H 'X-Analyitcs-Accesskey: Your access key' \
-H 'Content-Type: application/json' \
-d '{
"properties": {"guid":"52e10350-fe3d-487f-8631-1dc640010c87"}
}'
Error codes¶
For detailed information on each error code, please refer to the detail message in the return value.
- 40x: Access key error
- The access key must match the access key for the company, game, and log name you are trying to query. If this error occurs, you need to verify that the access key is correct.
- 50x: System error
- An error that occurred during data retrieval and processing.
- Ensure that the field names or value types in the query conditions are correct.
- If the detail indicates "System error," indicating an unknown error, please retry after a short while.