HTTP API

注意

• 服务端上报的http接口默认开通，如果您接入的应用没有开通，请联系客户成功经理解决；

• 本文档部分内容对于SaaS、SaaS云原生、私有化不同环境会有差异，请注意区分；

1. 请求的header里带"Content-Type: application/json"以及“X-MCS-AppKey”，作为app的标识。通过http api上报时，如果用代码及一些工具时，一般请求头上会自动带上User-Agent字段，如果手动发送可能会提示User-Agent is not allowed，则需要手动在请求头上加入User-Agent字段；

2. 请求的body包含user，header，event三个部分，其中的header是埋点数据本身的header；

3. 单次上传events数建议控制在20条以内，超过50条会报413；

4. 上传如采用/v2/event/list接口，json数目建议控制在20条以内，超过50条会报413。

2.1 请求header

APP Key的获取位置请参考以下截图：

2.2 请求body

2.3 user格式

2.4 header格式

2.5 event格式

4.1 /v2/event/json接口

curl -X POST -H "Content-Type: application/json" -H "X-MCS-AppKey: 12345678key" -d '{"user": {...}, "header":{...}, "events":{...}}' https://gator.volces.com/v2/event/json

请求body：

{
    "user": {
         // 建议先在客户端上报用户的user_unique_id，然后再在服务端使用
        "user_unique_id": "74481585297"   //用户唯一标示
    },
    "header": {
        "ab_sdk_version": "91223,83097",   //AB实验vid
        "app_channel": "App Store",    //App渠道
        "app_name": "news_article",    //App名称
        "app_package": "com.ss.android.article.news",   //App包名
        "app_version": "5.1.3",        //App版本
        "client_ip": "10.100.1.1",     //客户端ip地址
        "device_model": "SM-G9250",    //设备型号
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "traffic_type": "app",
        "custom":"{\"A\":\"a\"}"         //事件公共属性
    },
    "events": [
        {
            "ab_sdk_version": "91223,83097",   //AB实验vid
            "event": "test_go_detail",    //事件名称
            "params": "{\"paramName\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生时刻的时间戳
        }
    ]
}

说明
local_time_ms ：这个是毫秒时间戳，标识这个事件发生的时刻。

4.2 /v2/event/list接口

curl -X POST -H "Content-Type: application/json" -H "X-MCS-AppKey: 12345678key" -d '[{"user": {...}, "header":{...}, "events":{...}}]  https://gator.volces.com/v2/event/list

请求body：

[{
    "user": {
        "user_unique_id": "74481585297"   //用户唯一标示
    },
    "header": {
        "ab_sdk_version": "91223,83097",   //AB实验vid
        "app_channel": "App Store",    //App渠道
        "app_name": "news_article",    //App名称
        "app_package": "com.ss.android.article.news",   //App包名
        "app_version": "5.1.3",        //App版本
        "client_ip": "10.100.1.1",     //客户端ip地址
        "device_model": "SM-G9250",    //设备型号
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "traffic_type": "app"
    },
    "events": [
        {
            "event": "test_go_detail",    //事件名称
            "params": "{\"paramName\":\"a\"}",    //事件属性
            "local_time_ms": 1489573628001   //事件发生时刻的时间戳
        }
    ]
}]

说明
local_time_ms ：这个是毫秒时间戳，标识这个事件发生的时刻。

注意
本节仅适用于【SaaS云原生】、【私有化】版本，SaaS版本请参考User Profile API（服务端）。
用户属性是通过特殊的事件进行上报，通过设置下面几个event可以修改用户属性：

5.1 上报用户属性

用户属性放在params中 示例请求，作用为设置一个用户属性age，删除一个用户属性name，body：

{
    "user": {
        "user_unique_id": "74481585297"   //用户唯一标示
    },
    "header": {
        "ab_sdk_version": "91223,83097",   //AB实验vid
        "app_channel": "App Store",    //App渠道
        "app_name": "news_article",    //App名称
        "app_package": "com.ss.android.article.news",   //App包名
        "app_version": "5.1.3",        //App版本
        "client_ip": "10.100.1.1",     //客户端ip地址
        "device_model": "SM-G9250",    //设备型号
        "os_name": "Android",          //操作系统
        "os_version": "6.0.1",         //操作系统版本
        "traffic_type": "app"
    },
    "events": [
        {
            "event": "__profile_set",    //操作名
            "params": "{\"age\": 10}",    //设置属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }，
        {
            "event": "__profile_unset",    //操作名
            "params": "{\"name\":\"tom\"}",    //设置属性
            "local_time_ms": 1489573628001   //事件发生的时间戳
        }
    ]
}

5.2 批量上报用户属性

当需要批量上报用户属性时，可以在params里加上一个特殊字段__uuid_list来实现，__uuid_list是一个user_unique_id的列表，params中除__uuid_list字段的其他字段作为这个__uuid_list中所有user_unique_id的属性，参考代码：

{
    "user": {
        "user_unique_id": "user1"
    },
    "header":{"app_name":"init","app_id":"10000000"},
    "events": [
        {
            "event": "__profile_set",
            "params": {
                "__uuid_list": ["user1", "user2", "user3", "user4"],
                "age":20
            }
        }
    ]
}
matlab

注意
这个列表每次上报限制1000个用户。

5.3 验证上报的用户属性

可以在行为细查页面中查看特定用户的数据。

注意
【SaaS版本】历史数据导入需要隔天才能查看，【SaaS云原生】、【私有化】版本可实时查看。
如果数据的客户端时间超过七天，正常情况下无法导入。如需导入历史数据，需在header的custom字段中增加历史数据的标识__is_history，属性值设置为字符串"true"。 上报示例如下：

[{
   "user": {
       "user_unique_id": "74481585297"   //用户唯一标示
   },
   "header": {

       "custom": {
              "__is_history": "true" //导入历史数据标识，默认为false;
       }
   },
   "events": [
       {
           "event": "test_go_detail",    //事件名称
           "params": "{\"paramName\":\"a\"}",    //事件属性
           "local_time_ms": 1489573628001   //事件发生时刻的时间戳
       }
   ]
}]

说明
local_time_ms: 这个是毫秒时间戳，标识这个事件发生的时刻，注意不是导数的时间。
上报完成后，需要在界面上点击刷新数据，即可查询到上报的历史数据。

请参考文档：

• 数据格式文档中的数据上报限制：数据格式

如果知道特定的user_unique_id，可以在行为细查里查询。