로그 조회 API

/카테고리: /작성자:

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 설명

서비스 구분 도메인
상용 analytics-openapi.com2us.com
샌드박스 sandbox-analytics-openapi.com2us.com

 

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