menu
Is this helpful?

# Restful API User Guide(Restful API 활용 가이드)

# Restful API 활용 가이드

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

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

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

# 데이터 형식 변환

데이터를 업로드하기 전에, 데이터의 전송 형식을 지정된 형식으로 변환해야 합니다. 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
  }
}

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

# 데이터 업로드

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 모드를 켭니다. 프로덕션 환경에서 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를 켭니다. 실제 환경에서는 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입니다.

# 자주 묻는 질문

데이터 규칙을 참조하여, 데이터 형식의 문제로 인한 데이터 업로드의 이상을 확인하십시오.

← About GDPR →