---
code: restful_api
name: "Restful API 使用指南"
wikiToken: TvNDwhyoxi2x6qkGGhfc42u0n4e
parentWikiToken: GkqjwwBediy6Jzk35GAcAVNpncg
updateTime: 1769406874000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=restful_api
---
# Restful API 使用指南

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

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

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

### 一、数据格式转换

在上传数据之前，首先需要将数据的格式转换成 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
  }
}
```

具体的数据格式规范，请参考数据格式一节。

### 二、数据上报

当您准备好 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：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替换

### 三、常见问题

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