본문으로 건너뛰기

Restful API 사용 가이드

최근 업데이트 2026. 10. 03.

이 가이드에서는 데이터 연동 API를 사용하는 방법을 소개합니다. 데이터 연동 API를 사용하면 전송 도구나 SDK 없이 HTTP의 POST 메서드로 ThinkingAnalytics 백엔드에 데이터를 직접 전송할 수 있습니다.

연동을 시작하기 전에 먼저 데이터 규칙을 읽어야 합니다. AE의 데이터 형식과 데이터 규칙을 숙지한 후 이 가이드를 읽고 연동을 진행하십시오.

POST 메서드로 업로드하는 데이터는 반드시 AE의 데이터 형식을 따라야 합니다

1. 데이터 형식 변환​

데이터를 업로드하기 전에 먼저 데이터 형식을 AE의 데이터 형식으로 변환해야 합니다. AE의 각 데이터는 하나의 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 데이터가 준비되면 데이터를 전송할 수 있습니다. AE 백엔드는 HTTP 표준 POST 방식의 호출 요청을 받으며, 모든 인터페이스 데이터의 문자 집합 인코딩은 UTF-8을 사용합니다. 구체적인 호출 방법은 다음과 같습니다:

2.1 데이터 수신 인터페이스(제출 방식: form-data)​

클라우드 서비스를 사용하는 경우 다음 URL을 입력하십시오:

https://global-receiver-ta.thinkingdata.cn/sync_data

프라이빗 배포 버전을 사용하는 경우 다음 URL을 입력하십시오:

http://데이터-수집-주소/sync_data

2.1.1 수신 파라미터(requestBody에 작성)​

  • json 데이터가 1건인 경우:

    • 파라미터 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 파라미터를 추가할 수 있습니다(즉, 업로드 파라미터가 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을 입력하십시오:

https://global-receiver-ta.thinkingdata.cn/sync_json

프라이빗 배포 버전을 사용하는 경우 다음 URL을 입력하십시오:

http://데이터-수집-주소/sync_json

2.2.1 수신 파라미터(requestBody에 작성)​

  • json 데이터가 1건인 경우:
{
  "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",
        "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",
        "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 모드를 켜지 마십시오

debug=1이면 반환 결과에 자세한 오류 원인이 표시됩니다. 예:

{
  "code": -1,
  "msg": "#time字段格式不对,需传递[yyyy-MM-dd HH:mm:ss]或者[yyyy-MM-dd HH:mm:ss.SSS]格式"
}

2.2.4 데이터 압축​

RequestHeader에 compress 필드를 추가하면 압축된 데이터를 업로드할 수 있습니다. 예를 들어 compress=gzip을 전달하면 서버는 gzip으로 데이터 압축을 해제합니다. 현재 지원하는 압축 방식은 gzip과 snappy이며, 기본값은 압축하지 않음입니다.

2.2.5 전송 측 ip 가져오기​

RequestHeader에 client=1을 추가하면 서버는 전송 측 ip를 #ip 필드로 사용합니다(강제 대체). 기본값은 0이며, 이 경우 전송 측 ip로 대체하지 않습니다

3. 자주 묻는 질문​

데이터 형식 문제로 발생하는 데이터 전송 이상은 데이터 규칙 FAQ를 참고하여 확인하십시오.

이 문서가 도움이 되었나요?
이 페이지의 내용