HIVE 애널리틱스 로그 조회 API 란?

HIVE 애널리틱스 빅쿼리에 수집된 데이터를 API를 통해 조회하는 기능 입니다.
참고 : 애널리틱스 동작 구조 (https://developers.withhive.com/ko/dev4/analytics/hive-structure/)

사전 준비

데이터 조회 API를 사용하기 위해서는 HIVE 콘솔 → 애널리틱스 → 로그정의 메뉴를 통해 로그 조회 API 사용 신청이 완료 되어야 합니다.
신청이 완료된 로그는 해당 로그를 조회할 수 있는 AccessKey와 SecondAccessKey 가 발급 됩니다.
AccessKey와 SecondAccessKey는 동일하게 동작하며, SecondAccessKey는 AccessKey 동작에 문제가 발생 하였을 때 사용하기 위한 추가 발급 키 입니다.
※ AccessKey, SecondAccessKey는 비공개키 방식으로 외부에 절대 노출 되지 않도록 주의 해야 합니다.
※ AccessKey, SecondAccessKey가 노출 되었을 경우 즉시 갱신 또는 폐기 해야 합니다.

• 데이터 조회 OpenAPI 사용 신청 방법
  로그정의 메뉴에서 AccessKey를 발급 받고자 하는 게임을 선택 후 발급 받고자 하는 로그명을 클릭 하여 상세 페이지로 진입 합니다.
  ‘OpenAPI 사용 신청’ 버튼을 클릭 후 ‘확인’ 버튼을 누르면 키가 발급 됩니다.
  
• AccessKey 갱신, 폐기 방법
  로그정의 메뉴에서 AccessKey를 갱신, 폐기 하고자 하는 게임을 선택 후 로그명을 클릭 하여 상세 페이지로 진입 합니다.
  갱신 : ‘갱신’버튼을 클릭하면 새로운 AccessKey가 발급 되며, 이전에 발급 된 엑세스키는 사용 불가능 합니다.
  폐기 : ‘폐기’ 버튼을 클릭하면 기존에 발급된 AccessKey가 삭제 되며 더 이상 해당 키는 사용 불가능 합니다.
  

API 설명

• 필수 Header Parameter : X-Analyitcs-Accesskey
  OpenAPI의 데이터 조회 권한을 확인 하기 위해 반드시 해당 키 값을 요청 Header에 포함 해야 합니다.
• 데이터 조회 API
  • URL : https://{도메인}/data/query/{로그명}
  • 설명 : 조회 조건에 맞는 데이터를 조회.
  • Request(POST, application/json)
    

    이름	자료형	필수여부	설명	예시
    startDate	STRING	O	검색 시작 시간 UTC 기준( 형식 : yyyy-MM-dd hh:mm:ss) (nextToken 값 전송시 필수 X)	2024-01-01 00:00:00
    endDate	STRING	O	검색 종료 시간 UTC 기준( 형식 : yyyy-MM-dd hh:mm:ss) (nextToken 값 전송시 필수 X)	2024-01-02 00:00:00
    properties	JSON	X	JSON 형식의 검색 조건 {빅쿼리 필드명:검색값, …}	{“vid”:123, “market”:”A”}
    QueryType	STRING	X	“0” : 사용자 정의 필드만 포함, “1” : 모든 필드 포함(Default : “0”)	“0”
    nextPageToken	STRING	X	다음 페이지 데이터를 조회하기 위한 토큰값 * 페이지당 20개의 데이터 반환 * 해당 값으로 조회시 다른 파라메터는 입력하지 않음.	f3ebf4b6859a4f248b283a4fff1ded13

  • Response(application/json)
    

    이름	자료형	설명	예시
    totalRows	INTEGER	검색 결과 총 열수	123
    nextPageToken	STRING	다음 페이지 조회용 토큰 * 마지막 페이지일 경우 null	f3ebf4b6859a4f248b283a4fff1ded13
    datas	LIST[JSON]	조회된 데이터	[ { “dateTime”: “2024-01-01T23:38:24Z”, “vid”: 123, “characterLv”: 1 }, … ]

  • 요청 예제
    
    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" }'

    1 2 3 4 5 6 7 8 9

    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" }'

     
• 데이터 확인 API
  • URL : https://{도메인}/data/check/{로그명}
  • 설명 : 최근 1년내 검색 조건에 해당하는 로그가 빅쿼리에 존재 하는지 여부를 검사합니다.
  • Request(POST, application/json) :
    

    이름	자료형	필수여부	설명	예시
    properties	JSON	O	JSON 형식의 검색 조건 {빅쿼리 필드명:검색값, …}	{“guid”:”52e10350-fe3d-487f-8631-1dc640010c87″}

  • Response(application/json)
    

    이름	자료형	설명	예시
    isExists	BOOLEAN	데이터가 존재 하는지 여부	true
    datas	LIST[JSON]	존재 하는 데이터의 최근 5개의 샘플값 dateTime, guid 값을 포함하여 검색 조건에 해당 하는 필드 값을 포함 합니다.	[ { “vid”: 123, “dateTime”: “2024-04-16T23:09:24Z”, “guid”: “52e10350-fe3d-487f-8631-1dc640010c87” }, … ]

  • 요청 예제
    
    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"} }'

    1 2 3 4 5 6 7 8

    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"} }'

     
• 에러 코드
  • 각 에러 코드에 대한 자세한 사항은 리턴값의 detail 메시지를 참고 바랍니다.
  • 40x : 엑세스키 오류
    • 엑세스키는 조회하려는 회사, 게임, 로그명의 엑세스키와 일치 해야 합니다.
      해당 오류가 발생 한다면 엑세스키가 올바른 값인지 확인 해야 합니다.
  • 50x : 시스템 오류
    • 데이터 조회 및 처리시 발생한 오류 입니다.
    • 조회 조건의 필드명 또는 값의 자료 형이 올바른지 확인 해야 합니다.
    • detail이 System error 로 알 수 없는 오류 일 경우 잠시 후 재시도 합니다.