现阶段本产品只对小米生态链企业及合作伙伴正式开放.
1. 概述
小米健康云是一个构建在小米云平台之上的开放平台，它可以存储并管理用户的各种设备收集到的运动健身数据．这些数据由用户使用的各种设备收集并处理，然后通过应用程序上传到小米健康云进行存储和管理.
小米健康云的主要功能:
能够存储来自任何可穿戴设备或者传感器的数据
存储的数据能够被任何应用程序访问
用户升级设备或者应用程序时,数据使用不受影响
支持用户权限管理,保护用户隐私
如果用户有一个能够采集健身运动数据的设备, 那么
小米健康云的使用流程和场景如下
用户确定该设备能够采集到的数据种类,然后选取小米健康云已定义好的相对应的若干数据类型
针对每种选定的数据类型，分别创建相应的数据源(
DataSource
),并获得相应的数据源Id
采集数据并把每个数据都标记相应的数据源Id,然后上传到小米健康云
如果用户需要下载使用这些数据,也可以使用相应的数据源Id到小米健康云下载数据
2. 基本概念
小米健康云定义了一组概念, 这些概念用来描述数据组织格式和用户活动.
数据源是对用户数据的描述. 小米健康云使用数据源来标识用户上传的数据, 每个数据都必须有且只有一个数据源标识. 所以用户在上传一组数据时, 必须先创建一个数据源或者使用已有的数据源,为这组数据进行标识.同理, 用户在下载数据时,也需要指定下载哪个数据源标识的数据.
数据源从4个方面对数据进行标识
数据源的一些基本信息: 数据源名称, 数据源类型等
采集数据的设备信息: 设备型号, 名称, UID等
上传数据的应用程序信息: 应用程序名称, 版本号等
数据类型信息: 对应到具体的数据类型
数据类型是小米健康云上传,下载以及存储的基本数据组织格式. 用户在使用小米健康云之前,必须要确定自己设备采集到的数据种类,然后选取小米健康云定义好的数据类型来组织这些数据. 接下来才能创建相应的数据源, 上传下载自己的数据.
目前用户只能使用小米健康云定义好的数据类型, 不能自定义数据类型. 如果用户确实有使用自定义数据类型的需求, 请联系我们:
[email protected]
. 目前新的数据类型只能线下添加, 然后重新部署并发布服务.
设备描述用户采集数据时的传感器设备信息, 也是原始数据来源.
应用程序描述了创建数据源的应用程序信息, 也可以描述上传下载用户数据所使用的应用程序信息.
数据点描述的是某个时刻或者某个时间间隔内,设备采集到的数据, 这些数据需要符合某个数据类型. 每个数据点都必须要有一个采集该数据时的时间戳(EndTime), 如果数据点是瞬时数据, 则不需要提供起始时间(startTime); 如果数据点表示某个时间间隔内的数据,则需要提供该间隔时段的起始时间(StartTime).
每个数据点在上传到服务器时, 都必须为其标识一个数据源Id信息，表示该数据点属于哪个数据源. 实际上, 用户在和服务器交互管理数据点时, 任何操作都必须提供数据源Id信息.
数据集是客户端和服务器交互操作数据点时的数据结构概念. 由于每个数据点通常都比较小, 而且数据点的采集频率比较高, 所以每采集到一个数据点就上传到服务器一次, 或者下载数据点时一个一个下载, 都会对服务器造成很大压力. 因此, 小米健康云使用数据集来组织零散的数据点, 以数据集为单位和服务器交互.
比如上传数据点时, 用户需要采集到一定数量的数据点, 然后把这些数据点组织成一个数据集, 再把这个数据集上传到服务器. 下载时也是先指定数据源信息和时间范围, 然后到服务器下载一个数据集.
3. 数据格式
该部分会详细描述各个数据格式的字段信息和组织格式.
Application - 应用程序
Application描述创建数据源的应用程序信息, 也可以描述上传下载用户数据所用的应用程序信息
optional
DataPoint的起始时间, timestamp类型. 有的DataType表示一个时间间隔的数据,此时需要DataPoint提供startTimeNanos, 而有的DataType表示瞬时数据, 此时不需要DataPoint提供startTimeNanos
endTimeNanos
required
DataPoint截止时间, timestamp类型. 所有DataTypes都要求提供endTimeNanos
computationTimeMillis
optional
DataPoint的计算时间戳, timestamp类型. 这个字段用于传输过程中的版本检查, 如果用户需要用一个DataPoint a替换小米健康云中已存在的DataPoint b. 则必须保证a的computationTimeMillis比b的computationTimeMillis新. 同时还需要保证a的computationTimeMillis必须存在, 另外如果b没有设置computationTimeMillis, 则认为其一定比a要旧.
modifiedTimeMillis
optional
表示datapoint最后一次被修改的时间
originDataSourceId
String
optional
如果datapoint包含在一个derived数据源的dataset中, 那么用户需要提供该字段的值, 来表明是哪个数据源最初创建了这个datapoint
rawTimestampNanos
optional
从设备传感器读取该data point数据时的数据, 读取raw类型数据时的时间.
value
Value
required
该data point所携带的值, 可能是多个值, 取决于data point所属数据类型是一维还是多维. data point包含的value数量和类型必须和其所属的DataType保持一致.
String
required
数据源Id, 该值为创建DataSource时返回的DataStreamId. 用户在创建DataSource后, 需要存储返回报文中的dataStreamId, 并在后面的dataset中使用该dataStreamId
minStartTimeNs
required
如果Dataset所包含的DataPoint有startTimeNanos, 那么该值为这个Dataset所有DataPoint的最小startTimeNanos, 否则该值为这个Dataset所有DataPoint的最小endTimeNanos
maxEndTimeNs
required
该值为这个Dataset所有DataPoint的最大endTimeNanos
nextPageToken
String
optional
数据集的分页标识. 在一次用户请求中, 当符合条件的data point数量过多(超过1000个)时, 服务端只会在返回的dataset中填充1000个data point, 然后设置一个nextPageToken标识. 当用户继续请求后面的数据时, 需要携带这个nextPageToken作为分页标识, 服务端会依据该分页标识从下一页开始扫描数据.
point
DataPoint
required
该dataset携带的数据点列表, 关于数据点的具体文档请参考
DataPoint
文档
Integer
required
数据源类型,目前数据源类型只有两种:raw和derived.由于数据是通过app读取传感器设备,然后再经由该app上传到MiFitStore,所以如果app对数据进行了加工处理.那么数据源类型应该是derived,否则应该是raw. 数据源类型是枚举值:
在创建数据源的时候,应该提供其枚举整型值,而非字符串, 具体请参考
DataSourceType
文档
dataStreamId
String
optional
数据源ID值,该值是由服务端生成,对于同一用户,数据源的dataStreamId是唯一的.
用户在创建数据源时,不需要提供dataStreamId.服务端在创建数据源成功后,会在返回报文中包含dataStreamId.用户应该从返回报文中获取该数据源的dataStreamId,然后在后续和该数据源的相关交互中,提供该dataStreamId.
dataStreamName
String
optional
数据流名称,对于同一用户而言,数据流名称可以重复. 数据流名称对应的是采集数据的传感器的名称
dataType
DataType
required
数据源标识数据的数据类型, 具体请参考
DataType
文档
device
Device
required
数据源标识数据的设备信息, 具体请参考
Device
文档
application
Application
required
数据源标识数据的应用程序信息,具体请参考
Application
文档
DataType - 数据类型
DataType定义了数据被收集, 存储和使用的schema. DataType只是用来定义数据被收集, 存储和展示的格式, 并不定义数据如何被收集和展示.
小米健康云提供了丰富的数据类型, 同一种类数据可以用不同数据类型来表示, 这取决于数据如何展示. 例如: 数据类型com.xiaomi.micloud.fit.step_count.delta表示两次读取之间的走路步数(新增的步数); 而数据类型com.google.step_count.cumulative表示从开始起的总步数.
每种数据类型可包含若干个数据字段(每个字段就是一个field), 并且根据字段数量可分为一维数据类型和多维数据类型. 一维数据类型只包含一个字段; 而多维数据类型(比如表示位置的location类型, 就有latitude, longitude和accuracy等多个字段)的每个字段都代表一个维度. 同一数据类型的每个字段都有一个唯一名称, 字段也定义了数据的格式(int, float).
数据类型也可以分为瞬时值类型和非瞬时值类型, 瞬时值数据类型指某个时间点采集的数据, 而非瞬时值数据类型表示某个时间段采集的数据. 瞬时值数据类型对应的data point只需要设置endTime, 而不需要设置startTime; 非瞬时值数据类型对应的data point需要同时设置startTime和endTime.
数据类型名称
数据类型描述
TYPE_ACTIVITY_SAMPLE
(com.xiaomi.micloud.fit.activity.sample)
瞬时值, 多维数据类型
每个data point代表当前activity的瞬时样本值, 该data point有两个字段:
-
activity: 一个表示activity类型的整数值(每个activity类型都用一个整数常量来表示)
-
confidence: 是一个介于0.0-100.0之间的float值. 如果这个confidence未知, 那么可以使用一个负数来表示该字段的值
如果同一时刻多个activity被探测到, 并且每个activity有不同的confidence值, 那么可以使用多个data points来表示. 这些data point使用相同的timestamp, 但是值不相同
TYPE_ACTIVITY_SEGMENT
(com.xiaomi.micloud.fit.activity.segment)
非瞬时值, 一维数据类型
每个data point代表一个持续的时间间隔和一个activity整数值
一个activity的多个data points的起止时间不能有重叠, 但是可以不连续. 如果两个activities同时发生, 最显著的那个被选择, 另一个被舍弃.
TYPE_BASAL_METABOLIC_RATE
(com.xiaomi.micloud.fit.calories.bmr)
瞬时值, 一维数据类型
每个data point表示用户休息时, 能量消耗的基础代谢率. 单位是 kcal/day(千卡/天)
TYPE_BODY_FAT_PERCENTAGE
(com.xiaomi.micloud.fit.body.fat.percentage)
瞬时值, 一维数据类型
每个data point表示一次测试结果. 该测量结果表示人体总脂肪量和身体重量之间的比值
TYPE_CALORIES_EXPENDED
(com.xiaomi.micloud.fit.calories.expended)
非瞬时值，一维数据类型
每个data point表示该数据点起止时间间隔内消耗的卡路里的数量, 单位是千卡. 该数据值是float类型.
startTime和endTime都需要赋值, 表示所消耗卡路里的时间间隔
TYPE_CYCLING_PEDALING_CADENCE
(com.xiaomi.micloud.fit.cycling.cadence)
瞬时值, 一维数据类型
每个data point表示针对骑自行车时蹬踏速率的一次瞬时测量, 这个速率是每分钟的曲柄转速.
TYPE_CYCLING_PEADING_CUMULATIVE
(com.xiaomi.micloud.fit.cycling.pedaling.cumulative)
非瞬时值, 一维数据类型
每个data point表示从计数开始到当前时间的脚踏板旋转数. 当使用这个数据类型时, 每次旋转都可以被计算多次, 因为每个data point的值都是单调递增的. 如果想要计算某个时间间隔内的旋转数, 应该使用间隔时间截止时刻的值减去间隔时间开始时刻的值
注意: 在实际操作中, 数据源有可能会重置count为0. 如果可行的话, 数据源在创建data point时, 应该把data point的startTime设置成本次开始计数时的时间点. 相应的, 如果某个data point的值是0, 这也就表明此时计数被重置了
TYPE_CYCLING_WHEEL_REVOLUTION
(com.xiaomi.micloud.fit.cycling.wheel_revolution.cumulative)
非瞬时值, 一维数据类型
每个data point表示从计数开始到当前时间的车轮旋转数, 具体细节请参考TYPE_CYCLING_PEADING_CUMULATIVE
TYPE_CYCLING_WHEEL_RPM
(com.xiaomi.micloud.fit.cycling.wheel.revolutions)
瞬时值, 一维数据类型
每个data point表示针对骑自行车时车轮旋转速率的一次瞬时测量, 这个速率是每分钟的车轮旋转次数
TYPE_DISTANCE_DELTA
(com.xiaomi.micloud.fit.distance.delta)
非瞬时值, 一维数据类型
每个data point表示从上一次读取到现在所经过的距离, 单位是米. 某个时间段内走过的距离可以通过计算该时间段内所有data points的值来获得.
data point的startTime是该段距离开始时的时间, 该data point的startTime必须等于或者大于前一个data point的endTime
TYPE_HEART_RATE_BPM
(com.xiaomi.micloud.fit.heart_rate.bpm)
瞬时值, 一维数据类型
每个data point表示一次心跳的瞬时测量值, 该值是测量时刻往前一分钟的心跳数
TYPE_HEIGHT
(com.xiaomi.micloud.fit.height)
瞬时值, 一维数据类型
每个data point表示用户身高的一次测量值, 单位是米
TYPE_LOCATION_SAMPLE
(com.xiaomi.micloud.fit.location.sample)
瞬时值, 多维数据类型
每个data point表示测量瞬间用户所在的位置, 该data point有4个字段:
-
latitude: 表示纬度的float值, 单位是度
-
longitude: 表示经度的float值, 单位是度
-
accuracy: 表示精度的float值, 单位是米
-
altitude: 表示海拔高度的float值, 单位是米. 大多数移动设备在提供海拔信息时, 测量的海拔数据会有25米左右的偏差. 所以为了提高精度, 可以使用多次测量的平均值; 或者使用另一个可以精确测量海拔高度的数据源,. 如果海拔信息不能检测到, 可以不设置该字段
TYPE_LOCATION_TRACK
(com.xiaomi.micloud.fit.location.track)
非瞬时值, 多维数据类型
每个data point表示一个track的一部分, 这个data point可能没有精确的时间戳
它的字段和TYPE_LOCATION_SAMPLE是一样的. 二者的区别是: location.sample拥有精确的时间戳, 而location.track拥有的是不精确的一个时间间隔. location.sample表示某个时间点用户所在的位置, 而location.track表示某个时间间隔期间, 用户所在的位置. 对于location.track来说, startTime必须设置, 即使它的startTime和endTime是一样的
location.track可以用于记录用户在某次活动过程中的运动轨迹
TYPE_POWER_SAMPLE
(com.xiaomi.micloud.fit.power.sample)
瞬时值, 一维数据类型
每个data point表示对功率的一次瞬时测量, 单位是瓦特. 字段值是float型
TYPE_SPEED
(com.xiaomi.micloud.fit.speed)
瞬时值, 一维数据类型
每个data point表示一个地面上的瞬时速率, 单位是米/秒. 该值表示速度的标量值, 所以不可能是负值
TYPE_STEP_COUNT_CADENCE
(com.xiaomi.micloud.fit.step.count.cadence)
瞬时值, 一维数据类型
每个data point表示对步频的一次测量值, 该步频是指每分钟的步数.
步频是针对两只脚的和, 如果某个传感器只能测量一只脚的步频, 那么data point的值应该是这个传感器测量值的两倍
TYPE_STEP_COUNT_DELTA
(com.xiaomi.micloud.fit.step.count.delta)
非瞬时值, 一维数据类型
每个data point表示从上次测量时刻到本次测量时刻之间, 走路的步数. 在使用这个数据类型时, 每一步只能被计算一次, 只要把一个时间段内的数据都加在一起, 就能很容易计算出这个时间段内走路的总步数
例如, 某个人一共走了5步, 做了3次测量. 测量值有可能是[1，2，2]
startTime和endTime都需要设置, startTime必须小于或者等于endTime
TYPE_WEIGHT
(com.xiaomi.micloud.fit.weight)
瞬时值, 一维数据类型
每个data point表示测量时刻用户的体重, 单位是千克
