数据格式

方舟支持多种 SDK 上报数据，接口会有所不同，但底层数据都使用统一的数据格式，尤其是通过工具导入数据时，也需要符合相应的数据格式。同时，不同的属性，会有不同的数据类型，在分析时对应不同的计算方式，所以在上报数据时需要注意采用合适的格式。

上报数据的格式

数据整体是 JSON 格式，描述一条事件或者属性。

Event 数据样例

[
    {
        "appid":"demo",
        "xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e",
        "xwhat":"confirmOrder",
        "xwhen":1533110482778,
        "xcontext":{
            "$pagename":"com.analysys.demo.activity.MainActivity",
            "$channel":"豌豆荚",
            "$manufacturer":"Xiaomi",
            "$app_version":"4.0.4.001",
            "$model":"MIX 2S",
            "$os":"Android",
            "$os_version":"8.0.0",
            "$network":"WIFI",
            "$screen_width":1080,
            "$screen_height":2030,
            "$brand":"Xiaomi",
            "$is_first_day":true,
            "$lib":"Android",
            "$platform":"Android",
            "$is_login":false,
            "$lib_version":"4.0.4",
            "$debug":2，
            "order_price":1213.23
        }
    }
]

上述字段说明：

• appid：字符串类型，记录项目的 AppKey，创建项目后生成；

• xwho：字符串类型，记录用户 ID，调用接口生成；

• xwhat：字符串类型，记录事件 ID，必须是合法的变量名，由字母、数字和下划线组成，不能以数字开头，对于系统预置的事件以 $ 开头 ;

• xwhen：数据值类型，记录事件发生的时间戳，精确到毫秒；

• xcontext：事件的属性，以 dict 的形式存在，其中每个属性，有相应格式。以 $ 开头表示为系统预置的属性，其属性值数据类型都是约定好的，自定义的属性不要以 $ 开头，同一个属性 ID 在不同事件中的定义和数据类型应该保持一致。

Profile 数据样例

[
{
    "appid":"demo",
    "xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e",
    "xwhat":"$profile_set",
    "xwhen":1533110558121,
    "xcontext":{
        "Email":"[e-mail]",
        "$mac":"9c:2e:a1:fe:b7:eb",
        "$lib":"Android",
        "$platform":"Android",
        "$is_login":false,
        "$lib_version":"4.0.4",
        "$debug":2
    }
}
]

Profile 信息是通过一些特殊的事件上报，数据格式要求和事件相同。Profile 系列事件包括：

• $profile_set

• $profile_set_once

• $profile_unset

• $profile_increment

• $profile_append

• $profile_delete

特别说明：

建议您在上报数据时，用户属性ID 和 事件属性ID 使用小写英文字母和下划线组合命名，例如 pagename 、page_name；

不建议使用含大写字母的属性ID，例如 pageName 、pageTitle。

因为易观方舟会将 事件属性ID 和 用户属性ID 中的大写字母强制转换为小写字母。

属性值的数据类型

除了整体数据要以 JSON 作为数据传输格式之外，属性值的数据类型也会对应一定格式。

方舟定义了以下数据类型：

数据类型	JSON类型	说明	示例
字符串	string	使用UTF-8编码后最大长度1024字节	"易观方舟"
数值	number	-9E14到9E14, 小数点后最多保留3位	123 或者123.12
布尔	boolean	true/false	true/false
日期	datetime	格式：yyyy-MM-dd HH:mm:ss.SSS 或yyyy-MM-dd HH:mm:ss 或yyyy-mm-dd	"2018-06-18 18:18:18.188"
集合	array	元素为字符串，去重后最大元素个数 100，其中每个元素使用 UTF-8 编码后最大长度 255字节；是去重的无序的字符串集合，输入可有重复，导入过程中会去重	[ "写作","摄影","烹饪" ]

方舟预置的一些事件属性和用户属性，也会同时定义好数据类型，详见《预置事件和属性》。

方舟不会自动对数据类型错误的属性进行转换

假如我们有一个表示商品数量的属性 product_number 首次上报时是数值（number）类型，那么数据库就会将存储这个属性的字段的类型设置为数值（number）。如果接下来 product_number 收到非数值类型的值时，这一整条日志都会被标记为异常，进入错误队列，而不会进入方舟参与到正常计算中。

错误队列中的数据会保留7天，如果需要恢复当中的数据，请随时联系我们。

如果发现数据异常变少，可以通过“数据入库检查”中的“错误数据日志”查看日志是否因为此种情况而被抛弃。

数据入库验证

不同数据类型属性值的应用

数据上报中的属性，在分析时可以作为条件查询，也可以作为维度去细分，之所以需要定义不同属性值的数据类型，就是为了进行合适的运算和维度细分，例如 “支付订单金额” ，分析时希望对它进行求和、最大值、最小值、均值等运算，这就要求这个属性值的类型应该是数值型。

以下说明不同数据类型作为细分维度和过滤条件时的使用差异：

维度

数据类型	维度处理方式	举例属性	查询用户数，按举例维度细分
字符串	按离散值	商品类别 上报的属性值： 3C电器、服装、化妆品……	3C电器：12人 服装：12人 化妆品：18人
数值型	按离散值 自定义区间分组	商品价格 上报的属性： 12、20、90、300……	按离散值： 12：2人 20：3人 90：13人 300：1人 按用户自定义区间的话可能是： (-∞,50)：5人 [50,200)：13人 [200,+∞]：1人
布尔值	按离散值	是否使用优惠券 上报的属性值： true、false	使用了优惠券的：12人 没有使用优惠券的：18人
日期时间	按分钟、小时、日、周、月、季、年 按时段汇总：按分钟、小时、日、周，月	下单时间 上报的属性值： 2017-03-12 12:12:32、 2018-03-15 12:12:32、 2018-04-12 12:12:32……	不按时段汇总，按月： 2017年3月：23人 2018年3月：27人 2018年4月：12人 按时段汇总，按月： 每年3月：50人 每年4月：12人
集合	按集合字符串	用户爱好 上报的属性值： [网球，摄影]、[户外，摄影]、[户外、壁球]……	[网球，摄影]：34人 [户外，摄影]：53人 [户外、壁球]：23人

条件

字符串类型

操作符	使用场景	e.g.
=(等于)	当输入一个值时，表示等于某个具体确定的属性值；当输入多个时，表示满足其中的一项或多项	设备品牌 = 苹果，小米；设备品牌满足苹果、小米中的任意一个
≠（不等于）	完全排除输入的某个或多个属性值	设备品牌 ≠ 苹果，小米；设备品牌不满足苹果、小米中的任何一个
like（包含）	查找属性值中包含某些字符的值	设备品牌中包含苹果这个词的
notlike（不包含）	排除属性值中包含某些字符的值	设备品牌中不包含苹果这个词的
有值	查找有属性值的数据	有设备品牌名称的
无值	查找无属性值的数据	无设备品牌名称的
正则匹配	用来检查一个串是否含有某种子串、将匹配的子串替换或者从某个串中取出符合某个条件的子串等	-
正则不匹配	用来检查一个串是否不含有某种子串、将匹配的子串替换或者从某个串中排除符合某个条件的子串等	-

数值型

操作符	使用场景	e.g.
= (等于)	等于某个具体数字	商品金额 = 100
≠（不等于）	不等于某个数字	商品金额 ≠ 100
<（小于）	小于某个数字	商品金额 < 100
≤（小于等于）	小于等于某个数字	商品金额 ≤ 100
>（大于）	大于某个数字	商品金额 ＞ 100
≥（大于等于）	大于等于某个数字	商品金额 ≥ 100
介于区间	在某个数据区间内的数值	100＜商品金额 ≤ 500
有值	查找有属性值的数据	有商品金额的
无值	查找无属性值的数据	无商品金额的

布尔值

操作符	使用场景	e.g.
为真	某个判断为真	是否成功 = 是
为假	某个判断为假	是否成功 = 否
有值	查找有属性值的数据	有值
无值	查找无属性值的数据	无值

日期时间

操作符	使用场景	e.g.
绝对时间	在某个具体的时间范围	在 2018/12/14- 2018/12/17
相对当前时间点	在相对当前的某段时间里	在近 30 天内
相对事件发生时间	在相对事件发生的某段时间里	登录之前的 5 分钟里
有值	查找有属性值的数据	有日期
无值	查找无属性值的数据	无日期

字符串集合

操作符	使用场景	e.g.
like（包含）	集合中包含某个字符的值	用户标签中包含 摄影
notlike（不包含）	集合中不包含某个字符的值	用户标签不包含设计摄影
有值	查找有属性值的数据	有用户标签
无值	查找无属性值的数据	无用户标签

以上内容没有解答我的问题？点击我进入方舟论坛去反馈 🚀