# 数据格式 方舟支持多种 SDK 上报数据,接口会有所不同,但底层数据都使用统一的数据格式,尤其是通过工具导入数据时,也需要符合相应的数据格式。同时,不同的属性,会有不同的数据类型,在分析时对应不同的计算方式,所以在上报数据时需要注意采用合适的格式。 ## 上报数据的格式 数据整体是 JSON 格式,描述一条事件或者属性。 **Event 数据样例** ```javascript [ { "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 数据样例** ```javascript [ { "appid":"demo", "xwho":"9692043c-7d85-417a-b84e-fd37e1b7a67e", "xwhat":"$profile_set", "xwhen":1533110558121, "xcontext":{ "Email":"yonghu@163.com", "$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字节;是去重的无序的字符串集合,输入可有重复,导入过程中会去重 | \[ "写作","摄影","烹饪" ] | 方舟预置的一些事件属性和用户属性,也会同时定义好数据类型,详见[《预置事件和属性》](default-data/)。 >[danger]**方舟不会自动对数据类型错误的属性进行转换** >假如我们有一个表示商品数量的属性 product_number 首次上报时是数值(number)类型,那么数据库就会将存储这个属性的字段的类型设置为数值(number)。如果接下来 product_number 收到非数值类型的值时,这一整条日志都会被标记为异常,进入错误队列,而不会进入方舟参与到正常计算中。 >错误队列中的数据会保留7天,如果需要恢复当中的数据,请随时联系我们。 >[info]如果发现数据异常变少,可以通过“**数据入库检查**”中的“**错误数据日志**”查看日志是否因为此种情况而被抛弃。 **不同数据类型属性值的应用** 数据上报中的属性,在分析时可以作为条件查询,也可以作为维度去细分,之所以需要定义不同属性值的数据类型,就是为了进行合适的运算和维度细分,例如 “支付订单金额” ,分析时希望对它进行求和、最大值、最小值、均值等运算,这就要求这个属性值的类型应该是数值型。 以下说明不同数据类型作为细分维度和过滤条件时的使用差异: ### 维度 | 数据类型 | 维度处理方式 | 举例属性 | 查询用户数,按举例维度细分 | | ---- | --------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | 字符串 | 按离散值 | <p>商品类别<br>上报的属性值:<br>3C电器、服装、化妆品……</p> | <p>3C电器:12人<br>服装:12人<br>化妆品:18人</p> | | 数值型 | <p>按离散值<br>自定义区间分组</p> | <p>商品价格<br>上报的属性:<br>12、20、90、300……</p> | <p>按离散值:<br>12:2人<br>20:3人<br>90:13人<br>300:1人<br>按用户自定义区间的话可能是:<br>(-∞,50):5人<br>[50,200):13人<br>[200,+∞]:1人</p> | | 布尔值 | 按离散值 | <p>是否使用优惠券<br>上报的属性值:<br>true、false</p> | <p>使用了优惠券的:12人<br>没有使用优惠券的:18人</p> | | 日期时间 | <p>按分钟、小时、日、周、月、季、年<br>按时段汇总:按分钟、小时、日、周,月</p> | <p>下单时间<br>上报的属性值:<br>2017-03-12 12:12:32、<br>2018-03-15 12:12:32、<br>2018-04-12 12:12:32……</p> | <p>不按时段汇总,按月:<br>2017年3月:23人<br>2018年3月:27人<br>2018年4月:12人<br>按时段汇总,按月:<br>每年3月:50人<br>每年4月:12人</p> | | 集合 | 按集合字符串 | <p>用户爱好<br>上报的属性值:<br>[网球,摄影]、[户外,摄影]、[户外、壁球]……</p> | <p>[网球,摄影]:34人<br>[户外,摄影]:53人<br>[户外、壁球]:23人</p> | ### 条件 **字符串类型** | 操作符 | 使用场景 | 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(不包含) | 集合中不包含某个字符的值 | 用户标签不包含设计摄影 | | 有值 | 查找有属性值的数据 | 有用户标签 | | 无值 | 查找无属性值的数据 | 无用户标签 | >[info] 以上内容没有解答我的问题?[点击我进入方舟论坛去反馈](https://www.analysysdata.com/forum/index) 🚀