menu
Is this helpful?

# Restful API 使用指南

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

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

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

# 一、数据格式转换

在上传数据之前，首先需要将数据的格式转换成 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://global-receiver-ta.thinkingdata.cn/sync_data

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

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

# 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 参数（即有三个上传参数，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 数据:
{
  "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、lzo、lz4和snappy，默认为不压缩。

# 2.2.5 获取上报端ip

在RequestHeader中增加client=1，服务端会取上报端ip作为#ip字段（强制替换），默认值为0，即不取上报端ip替换

# 三、常见问题

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

← 关于 GDPR →