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

# 三、常见问题

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