# 数据接入 API

> 本文档所描述的内容属于神策分析的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。

神策分析 [数据接入](https://54td.gitbook.io/shence/technical_guide/data_import)一般使用各语言的 SDK 或我们提供的批量或流式数据导入工具来完成。

在一些特殊情况下，如果用户希望实现自己的接入工具，可以参考本文档。

**若无特殊需求，建议使用我们的 SDK 或工具来进行数据接入，以避免未知的问题，并方便以后新功能的使用。例如当使用的编程语言没有对应的 SDK 时，可以考虑使用** [**LogAgent**](https://54td.gitbook.io/shence/technical_guide/import_tool/log_agent) **或其他批量导入工具。**

外部数据接入神策分析分为几个步骤：

## 1. 生成数据

在神策分析数据接入过程中，每条数据（包括任何事件行为和用户属性数据）都是一个符合[数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema)的 Json。

例如：

```javascript
{
    "distinct_id": "2b0a6f51a3cd6775",
    "time": 1434556935000,
    "type": "track",
    "event": "ViewProduct",
    "properties": {
        "$manufacturer":"Apple",
        "$model": "iPhone 5",
        "$os":"iOS",
        "$os_version":"7.0",
        "$app_version":"1.3",
        "$wifi":true,
        "$ip":"180.79.35.65",
        "$province":"湖南",
        "$city":"长沙",
        "$screen_width":320,
        "$screen_height":640,
        "product_id":12345,
        "product_name":"苹果",
        "product_classify":"水果",
        "product_price":14.0
    }
}
```

当希望一次发送多条数据时，可以构造一个 Json 数组，每个元素是一个完整的 Json。

* 建议一次最多不超过 50 条数据；
* 仅发送一条可以使用长度为 1 的 Json 数组。

例如：

```javascript
[
    {
        "distinct_id":"2b0a6f51a3cd6775",
        "time":1434556935000,
        "type":"track",
        "event":"ViewProduct",
        "properties":{
            "product_name":"苹果",
            "product_classify":"水果",
            "product_price":14
        }
    },
    {
        "distinct_id":"12345",
        "type":"profile_set",
        "time":1435290195610,
        "properties":{
            "Age":33,
            "IncomeLevel":"3000~5000"
        }
    }
]
```

## 2. 编码

本步骤主要是将 `1.生成数据` 中的 `Json` 或 `Json 数组` 进行编码。其下几个子步骤需要顺次执行。

* 请使用 UTF-8 编码;

### 2.1 进行 Gzip 压缩（可选）

为了优化数据传输，可以先对数据进行 Gzip 压缩。

* 此为可选步骤，可以不压缩。

### 2.2 进行 Base64 编码（必须）

为了更好的兼容各种传输方式，需要对数据进行 Base64 编码。若进行了 `2.1 进行 Gzip 压缩`，则将压缩后的数据进行 Base64 编码；否则直接将要传输的 `Json` 或 `Json 数组` 进行 Base64 编码。

### 2.3 进行 UrlEncode 编码（必须）

由于需要兼容数据作为 URL 参数传输，故需要对 `2.2 进行 Base64 编码` 得到的结果进行 UrlEncode，这个步骤可能是由浏览器或数据发送框架完成的。

### 2.4 拼装 request

#### 2.4.1 一条 Json 数据

如果处理的是一条 Json 数据，request 格式如下：

```
data=xxxxx&gzip=1
```

* data：即为 `2.3 进行 UrlEncode` 得到的编码结果；
* gzip：是否进行了 Gzip 压缩；

#### 2.4.2 多条 Json 构成的数组

如果是一次发送多条 Json 构成的数组，request 格式如下：

```
data_list=xxxxx&gzip=1
```

* data\_list：即为 `2.3 进行 UrlEncode` 得到的编码结果；
* gzip：是否进行了 Gzip 压缩；

### 2.4 编码例子

本节演示对样例数据进行编码，假设数据已经写入到了 `data.json` 文件中：

```javascript
[
    {
        "distinct_id":"2b0a6f51a3cd6775",
        "time":1434556935000,
        "type":"track",
        "event":"ViewProduct",
        "properties":{
            "product_name":"苹果",
            "product_classify":"水果",
            "product_price":14
        }
    },
    {
        "distinct_id":"12345",
        "type":"profile_set",
        "time":1435290195610,
        "properties":{
            "Age":33,
            "IncomeLevel":"3000~5000"
        }
    }
]
```

1. 先对数据进行 Gzip 并进行 Base64 编码，在 Linux 下可使用如下命令：

   ```
   cat data.json | gzip | base64 -w 0
   ```

   得到结果：

   ```
   H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD+VsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO+Zl5yfm+oDDMwcoJ3GwKCvA4W/EronuGIBDY0g6OEBAAA=
   ```
2. 再对数据进行 UrlEncode 编码，如使用在线工具 [链接](http://tool.chinaz.com/tools/urlencode.aspx)

   样例数据 UrlEncode 编码得到：

   ```
   H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d
   ```
3. 拼装 request：

   ```
   gzip=1&data_list=H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d
   ```

## 3. 发送数据

即将编码后的数据发送到神策分析接收数据的 API。

API 地址：

![](https://3928609189-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Levm4x0IpHBx6dxiaCM%2F-LeydYULqjq7WfRLX0IT%2F-Leydck2ctJbhNeQRsjz%2Fmulti_project_data_api.png?generation=1557976757617660\&alt=media)

如果使用神策分析 Cloud 服务，则:

* 数据接收地址，建议使用不带端口号的: <http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}>
* 数据接收地址，带端口号的: <http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}>

如果用户使用单机版私有部署的神策分析，默认的配置信息为：

* 数据接收地址: <http://{$host_name}:8106/sa?project={$project_name}>

  （注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）

如果用户使用集群版私有部署的神策分析，默认的配置信息为：

* 数据接收地址: <http://{$host_name}:8106/sa?project={$project_name}>

其中 `{$host_name}` 可以是集群中任意一台机器。

如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。

例如，以 Cloud 服务为例，使用 curl 发送：

```
curl -v \
     --data 'gzip=1&data_list=H4sIAFsmElcAA4vmUgCCajAJAkopmcUlmXnJJfGZKUpWSkZJBolmaaaGicbJKWbm5qZKOgiVJZm5qUpWhibGJqamZpbGpgYGBsiylQVAWaWSosTkbGRdqWWpeSVAibDM1PKAovyU0uQSZOmCovyC1KKSzNRiJSuEq2BSINXxeYkge5VedO98Nm8Okl4URck5icXFmWmVQIXPNmzBo7CgKDMZ7A24dC2YVauDP2QMjYD%2bVsL0MNDctMyc1Pji1BKsgWVqZGlgaGlqZmhAnK8d04H6jI3RXO%2bZl5yfm%2boDDMwcoJ3GwKCvA4W%2fEronuGIBDY0g6OEBAAA%3d' \
     http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}
```

### 4. 其他

* 如果没有特殊情况，不建议自己实现上面的接入流程，而是使用 SDK 或工具的方式接入数据。
* 神策分析是异步处理接收的数据，所以发送完成后需要等待片刻才能查询到。
* 本地反编码一条数据查看内容可以通过：

  ```
   UrlDecode > data   # 将数据 UrlDecode（这步没有好用的 bash 命令，可以使用在线工具）
   cat data | base64 -d | gzip -d
  ```