Restful API 使用指南

本指南将会为您介绍如何使用数据接入API，通过使用数据接入API，可以在不依赖传输工具与SDK的情况下，使用HTTP的POST方法直接向ThinkingAnalytics后台传输数据。

在开始对接前，您需要先阅读数据规则，在熟悉TA的数据格式与数据规则后，再阅读本指南进行对接。

POST方法上传的数据必须遵循TA的数据格式

一、数据格式转换

在上传数据之前，首先需要将数据的格式转换成TA的数据格式，TA的每一条数据都是一个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数据后，即可进行数据上报，TA后台接受HTTP标准POST方式的调用请求，所有接口数据字符集编码均采用UTF-8方式，具体的调用方式如下：

2.1 数据接收接口（提交方式为form-data）

如果您使用的是云服务，请输入以下URL:

http://receiver.ta.thinkingdata.cn/sync_data

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/sync_data

2.1.1 接收参数（写在requestBody中）

如果是一条json数据：
- 参数1：appid=您项目的APPID
- 参数2：data=JSON数据，UTF-8编码，需要urlencode编码
如果是多条数据：
- 参数1：appid=您项目的APPID
- 参数2：data_list=JSONArray格式的数据，包含多条JSON数据，UTF-8编码，需要urlencode编码

注意 : 不同语言的库有可能自带 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：

http://receiver.ta.thinkingdata.cn/sync_json

如果您使用的是私有化部署的版本，请输入以下URL:

http://数据采集地址/sync_json

2.2.1 接收参数（写在requestBody中）

如果是一条json数据:

{"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"},{"#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]格式"}

3 常见问题

请参考数据规则常见问题，排查由于数据格式问题而产生的数据传输异常。

Restful API使用指南