Restful API
Restful API
이 가이드는 ThinkingEngine(TE) 플랫폼으로 데이터를 직접 업로드하는 방법을 설명합니다. SDK나 별도의 수집 도구 없이 HTTP POST 메소드를 통해 데이터를 수집할 수 있으며, 데이터를 업로드하기 전에 TE의 데이터 규칙과 형식을 이해하는 것이 중요합니다.
1. 데이터 형식 변환
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
}
}
2. 데이터 업로드
JSON 형식의 데이터가 준비되면, HTTP 표준의 POST 메소드를 사용하여 데이터를 업로드할 수 있습니다. TE는 UTF-8 문자 인코딩을 사용하며, 구체적인 호출 방법은 다음과 같습니다:
2.1 데이터 수신 인터페이스 (커밋 방식: form-data)
클라우드 서비스의 경우, 아래 URL을 사용하여 데이터를 전송하세요:
• https://te-receiver-naver.thinkingdata.kr/sync_data
• https://te-receiver-naver.thinkingdata.kr/sync_json
온프레미스 서비스를 사용하는 경우, 해당 URL을 설정하세요:
• http://업로드 URL/sync_data
• 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 형식의 복수 데이터. UTF-8 및 urlencode 인코딩 필요
• 파라미터 3: client=0 (기본값: 0, 1로 설정 시 데이터 전송 측 IP를 #ip로 강제 변경)
주의사항: 일부 프로그래밍 언어 라이브러리는 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 파라미터를 추가할 수 있습니다. (즉, 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에 압축 필드를 추가하여 압축 데이터를 업로드할 수 있습니다.
• 현재 지원되는 압축 방식: gzip, lzo, lz4, snappy (기본값: 압축 안함)
2.2.5 전송 측 IP 획득
• RequestHeader에 client=1을 추가하면, 서버는 전송 측 IP를 #ip 필드에 기록합니다.
3. 자주 묻는 질문 (FAQ)
데이터 업로드 중 문제가 발생할 경우, 데이터 규칙을 참조하여 데이터 형식 및 포맷 문제를 확인하세요.
.png)