menu
Is this helpful?

# Restful API 사용 가이드

본 가이드에서는 데이터 수집 API에 대해 소개합니다. 데이터 수집 API를 사용하면, 수집 도구나 SDK에 의존하지 않고, HTTP의 POST 메소드를 사용하여 ThinkingEngine 플랫폼으로 직접 데이터를 수집할 수 있습니다.

업로드를 시작하기 전에, 데이터 규칙을 참조하고, TE의 데이터 형식과 데이터 규칙을 이해한 상태에서, 본 가이드의 안내에 따라 업로드를 진행해 주세요.

POST 메소드로 업로드되는 데이터는, TE의 데이터 규칙을 준수합니다.

# 1. 데이터 형식 변환

데이터를 업로드하기 전에, 데이터의 전송 포맷을 지정된 형식으로 변환해야 합니다. TE의 각 데이터는 JSON 형태로, 아래는 샘플입니다. (읽기 쉽게, 형식이 이미 정돈되어 있음)

{
  "#account_id": "ABCDEFG-123-abc",
  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
  "#type": "track",
  "#ip": "192.168.171.111",
  "#time": "2017-12-18 14:37:28.527",
  "#event_name": "test",
  "properties": {
    "#lib": "LogBus",
    "#lib_version": "1.0.0",
    "#screen_height": 1920,
    "#screen_width": 1080,
    "argString": "abc",
    "argNum": 123,
    "argBool": true
  }
}

구체적인 데이터 형식의 규칙은, 데이터 규칙을 참고해 주세요.

# 2. 데이터 업로드

JSON 형식의 데이터 준비가 완료되면, 데이터를 업로드할 수 있는 상태가 됩니다. TE 시스템은 HTTP 표준의 POST 메소드 호출 요구를 지원합니다. 모든 인터페이스의 데이터 문자 인코딩은 UTF-8을 사용합니다. 구체적인 호출 방법은 다음과 같습니다.

# 2.1 데이터 수신 인터페이스 (커밋 방식은 form-data)

클라우드 서비스를 사용하고 있다면, 다음 URL을 입력해주세요.

https://te-receiver-naver.thinkingdata.kr/sync_data or

https://te-receiver-naver.thinkingdata.kr/sync_json

온프레미스 서비스를 사용하는 경우, 다음의 URL을 입력해주세요.

http://업로드 URL/sync_data or

http://업로드 URL/sync_json

# 2.1.1 수신 파라미터 (requestBody에 기입)

  • JSON 데이터의 경우:
    • 파라미터 1: appid=프로젝트의 APPID
    • 파라미터 2: data=JSON 데이터, UTF-8 인코딩, urlencode 인코딩 필요
    • 파라미터 3: client=0, 기본값은 0, 1을 설정할 때 데이터 전송 측 IP를 #ip로 강제 변경
  • 복수 데이터의 경우:
    • 파라미터 1: appid=프로젝트의 APPID
    • 파라미터 2: data_list=JSONArray 형식의 데이터, 복수의 JSON 데이터, UTF-8 인코딩, urlencode 인코딩 필요
    • 파라미터 3: client=0, 기본값은 0, 1을 설정할 때 데이터 전송 측 IP를 #ip로 강제 변경

주의: 다른 언어의 라이브러리는 urlencode를 지원할 수 있습니다. 이 경우, 다시 urlencode할 필요는 없습니다. 예를 들어, Python3의 requests 라이브러리, postman의 요청 테스트 등이 있습니다.

아래는 curl을 사용하여 RESTful API를 호출하는 방법을 보여줍니다.

{
"#account_id": "testing",
"#time": "2019-01-01 10:00:00.000",
"#type": "track",
"#event_name": "testing",
"properties": {
"test": "test"
}
}

위 데이터는 먼저 urlencode 처리가 필요합니다.

%7b%22%23account_id%22%3a%22testing%22%2c%22%23time%22%3a%222019-01-01+10%3a00%3a00.000%22%2c%22%23type%22%3a%22track%22%2c%22%23event_name%22%3a%22testing%22%2c%22properties%22%3a%7b%22test%22%3a%22test%22%7d%7d

파라미터를 추가하고 데이터를 업로드합니다.

curl "http://receiver:9080/sync_data" --data "appid=test-sdk-appid&data=%7b%22%23account_id%22%3a%22testing%22%2c%22%23time%22%3a%222019-01-01+10%3a00%3a00.000%22%2c%22%23type%22%3a%22track%22%2c%22%23event_name%22%3a%22testing%22%2c%22properties%22%3a%7b%22test%22%3a%22test%22%7d%7d"

# 2.1.2 반환 값 파라미터

반환 값 파라미터 code: 0을 받은 경우, 데이터 업로드는 성공입니다.

# 2.1.3 Debug 모드

파라미터를 업로드할 때, debug 파라미터를 추가할 수 있습니다. (즉, 3개의 업로드 파라미터, appid, data\data_list, debug가 있음) 추가는 선택적이며 기본값은 꺼짐입니다. 소량의 테스트 데이터를 업로드할 때만 디버그 모드를 켭니다. 운영 환경에서 디버그 모드를 켜지 마십시오. debug=1의 경우, 반환 값은 에러의 상세한 원인을 보여줍니다. 예를 들어:

{"code":-1,"msg":"#time 필드의 포맷이 잘못되어 [yyyy-MM-dd HH:mm:ss] 또는 [yyyy-MM-dd HH:mm:ss.SSS]를 전달해야 함"}

# 2.2 데이터 수신 인터페이스(커밋 방식은 raw)

클라우드 서비스를 사용하는 경우, 아래의 URL을 입력하세요:

http://ta-receiver.thinkingdata.io/sync_json

온프레미스 서비스를 사용하는 경우, 다음 URL을 입력하세요:

http://업로드 URL/sync_json

# 2.2.1 수신 파라미터 (requestBody에 기록)

  • json 데이터의 경우:
{
  "appid": "debug-appid",
  "debug": 0,
  "data": {
    "#type": "업로드",
    "#event_name": "test",
    "#time": "2019-11-15 11:35:53.648",
    "properties": { "a": "123", "b": 2 },
    "#distinct_id": "1111"
  }
}
  • 복수 데이터의 경우:
  [
  {
  "appid": "debug-appid",
  "debug": 0,
  "data": {
  "#type": "track",
  "#event_name": "test",
  "#time": "2019-11-15 11:35:53.648",
  "properties": { "a": "123", "b": 2 },
  "#distinct_id": "1111"
  },
  {
  "appid": "debug-appid",
  "debug": 0,
  "data": {
  "#type": "track",
  "#event_name": "test",
  "#time": "2019-11-15 11:35:53.648",
  "properties": { "a": "123", "b": 2 },
  "#distinct_id": "1111"
  }
  }
  }

# 2.2.2 반환 값 파라미터:

반환 값 파라미터 code: 0을 받은 경우, 데이터 업로드는 성공입니다.

# 2.2.3 Debug 모드

파라미터를 업로드할 때, debug 파라미터를 추가할 수 있습니다. (즉, JSON에 debug 파라미터를 추가). 추가는 선택적이며, 기본값은 꺼짐입니다. 소량의 테스트 데이터를 업로드할 때만 디버그를 켭니다.

운영 환경에서 디버그를 켜지 마십시오. debug=1의 경우, 반환 값은 에러의 상세한 원인을 보여줍니다.

{
  "code": -1,
  "msg": "#time 필드의 형식이 잘못되었습니다. [yyyy-MM-dd HH:mm:ss] 또는 [yyyy-MM-dd HH:mm:ss.SSS]가 필요합니다."
}

# 2.2.4 데이터 압축

RequestHeader에 압축 필드를 추가하여 압축 데이터를 업로드할 수 있습니다. 예를 들어: compress=gzip, 서버 측은 gzip을 사용하여 데이터를 압축 해제합니다. 현재 지원되는 압축 방식: gzip, lzo, lz4, snappy입니다. 기본적으로 압축하지 않습니다.

# 2.2.5 전송 측 IP 획득

RequestHeader에 client=1을 추가하면, 서버 측은 전송 IP를 #ip 필드에 기록합니다(강제 변경). 기본값은 0입니다.

# 3. 자주 묻는 질문

데이터 규칙을 참고하여, 데이터 포맷 문제로 인한 데이터 업로드 이상을 확인하십시오.

← GDPR에 관하여 →