小米健康云开放平台用户文档
现阶段本产品只对小米生态链企业及合作伙伴正式开放.
1. 概述
小米健康云是一个构建在小米云平台之上的开放平台，它可以存储并管理用户的各种设备收集到的运动健身数据．这些数据由用户使用的各种设备收集并处理，然后通过应用程序上传到小米健康云进行存储和管理.
小米健康云的主要功能:- 能够存储来自任何可穿戴设备或者传感器的数据
- 存储的数据能够被任何应用程序访问
- 用户升级设备或者应用程序时,数据使用不受影响
- 支持用户权限管理,保护用户隐私
如果用户有一个能够采集健身运动数据的设备, 那么小米健康云的使用流程和场景如下
- 用户确定该设备能够采集到的数据种类,然后选取小米健康云已定义好的相对应的若干数据类型
- 针对每种选定的数据类型，分别创建相应的数据源(DataSource),并获得相应的数据源Id
- 采集数据并把每个数据都标记相应的数据源Id,然后上传到小米健康云
- 如果用户需要下载使用这些数据,也可以使用相应的数据源Id到小米健康云下载数据
2. 基本概念
小米健康云定义了一组概念, 这些概念用来描述数据组织格式和用户活动.
数据源(DataSource)
数据源是对用户数据的描述. 小米健康云使用数据源来标识用户上传的数据, 每个数据都必须有且只有一个数据源标识. 所以用户在上传一组数据时, 必须先创建一个数据源或者使用已有的数据源,为这组数据进行标识.同理, 用户在下载数据时,也需要指定下载哪个数据源标识的数据.
数据源从4个方面对数据进行标识- 数据源的一些基本信息: 数据源名称, 数据源类型等
- 采集数据的设备信息: 设备型号, 名称, UID等
- 上传数据的应用程序信息: 应用程序名称, 版本号等
- 数据类型信息: 对应到具体的数据类型
数据类型(DataType)
数据类型是小米健康云上传,下载以及存储的基本数据组织格式. 用户在使用小米健康云之前,必须要确定自己设备采集到的数据种类,然后选取小米健康云定义好的数据类型来组织这些数据. 接下来才能创建相应的数据源, 上传下载自己的数据.
目前用户只能使用小米健康云定义好的数据类型, 不能自定义数据类型. 如果用户确实有使用自定义数据类型的需求, 请联系我们: DevFit@xiaomi.com. 目前新的数据类型只能线下添加, 然后重新部署并发布服务.
设备(Device)
设备描述用户采集数据时的传感器设备信息, 也是原始数据来源.
应用程序(Application)
应用程序描述了创建数据源的应用程序信息, 也可以描述上传下载用户数据所使用的应用程序信息.
数据点(DataPoint)
数据点描述的是某个时刻或者某个时间间隔内,设备采集到的数据, 这些数据需要符合某个数据类型. 每个数据点都必须要有一个采集该数据时的时间戳(EndTime), 如果数据点是瞬时数据, 则不需要提供起始时间(startTime); 如果数据点表示某个时间间隔内的数据,则需要提供该间隔时段的起始时间(StartTime).
每个数据点在上传到服务器时, 都必须为其标识一个数据源Id信息，表示该数据点属于哪个数据源. 实际上, 用户在和服务器交互管理数据点时, 任何操作都必须提供数据源Id信息.
数据集(Dataset)
数据集是客户端和服务器交互操作数据点时的数据结构概念. 由于每个数据点通常都比较小, 而且数据点的采集频率比较高, 所以每采集到一个数据点就上传到服务器一次, 或者下载数据点时一个一个下载, 都会对服务器造成很大压力. 因此, 小米健康云使用数据集来组织零散的数据点, 以数据集为单位和服务器交互.
比如上传数据点时, 用户需要采集到一定数量的数据点, 然后把这些数据点组织成一个数据集, 再把这个数据集上传到服务器. 下载时也是先指定数据源信息和时间范围, 然后到服务器下载一个数据集.
3. 数据格式
该部分会详细描述各个数据格式的字段信息和组织格式.
Application - 应用程序
Application描述创建数据源的应用程序信息, 也可以描述上传下载用户数据所用的应用程序信息
| 字段名称 | 类型 | 选填 | 说明 |
|---|---|---|---|
| name | String | required | 应用程序名称. 该名称并不要求唯一, 同一用户可以在多个数据源中使用相同的应用程序名称. |
| packageName | String | optional | 应用程序的包名 |
| detailsUrl | String | optional | 回调URL, 用户可以通过该URL查看应用程序详细信息 |
| os | String | optional | 该应用程序所运行的系统平台名称, 比如安卓, iOS |
| version | String | optional | 应用程序版本号. 如果应用程序的更新影响到了数据的计算方式, 那么用户应该更新此版本号. |
DataPoint - 数据点
DataPoint是小米健康云对运动健身数据的最小存储单位, 也是数据采集单位. 每个data point表示某个时间点或时间间隔内的数据记录
| 字段名称 | 类型 | 选填 | 说明 |
|---|---|---|---|
| dataTypeName | String | required | 数据类型名称,该数据类型名称是DataType的名称,并且只能是小米健康云内置的DataType的名称,目前不支持用户自定义扩展的数据类型. |
| startTimeNanos | Long | optional | DataPoint的起始时间, timestamp类型. 有的DataType表示一个时间间隔的数据,此时需要DataPoint提供startTimeNanos, 而有的DataType表示瞬时数据, 此时不需要DataPoint提供startTimeNanos |
| endTimeNanos | Long | required | DataPoint截止时间, timestamp类型. 所有DataTypes都要求提供endTimeNanos |
| computationTimeMillis | Long | optional | DataPoint的计算时间戳, timestamp类型. 这个字段用于传输过程中的版本检查, 如果用户需要用一个DataPoint a替换小米健康云中已存在的DataPoint b. 则必须保证a的computationTimeMillis比b的computationTimeMillis新. 同时还需要保证a的computationTimeMillis必须存在, 另外如果b没有设置computationTimeMillis, 则认为其一定比a要旧. |
| modifiedTimeMillis | Long | optional | 表示datapoint最后一次被修改的时间 |
| originDataSourceId | String | optional | 如果datapoint包含在一个derived数据源的dataset中, 那么用户需要提供该字段的值, 来表明是哪个数据源最初创建了这个datapoint |
| rawTimestampNanos | Long | optional | 从设备传感器读取该data point数据时的数据, 读取raw类型数据时的时间. |
| value | Value | required | 该data point所携带的值, 可能是多个值, 取决于data point所属数据类型是一维还是多维. data point包含的value数量和类型必须和其所属的DataType保持一致. |
Dataset - 数据集
数据集是客户端和服务器交互操作数据点时的数据结构概念
| 字段名称 | 类型 | 选填 | 说明 |
|---|---|---|---|
| dataSourceId | String | required | 数据源Id, 该值为创建DataSource时返回的DataStreamId. 用户在创建DataSource后, 需要存储返回报文中的dataStreamId, 并在后面的dataset中使用该dataStreamId |
| minStartTimeNs | Long | required | 如果Dataset所包含的DataPoint有startTimeNanos, 那么该值为这个Dataset所有DataPoint的最小startTimeNanos, 否则该值为这个Dataset所有DataPoint的最小endTimeNanos |
| maxEndTimeNs | Long | required | 该值为这个Dataset所有DataPoint的最大endTimeNanos |
| nextPageToken | String | optional | 数据集的分页标识. 在一次用户请求中, 当符合条件的data point数量过多(超过1000个)时, 服务端只会在返回的dataset中填充1000个data point, 然后设置一个nextPageToken标识. 当用户继续请求后面的数据时, 需要携带这个nextPageToken作为分页标识, 服务端会依据该分页标识从下一页开始扫描数据. |
| point | DataPoint | required | 该dataset携带的数据点列表, 关于数据点的具体文档请参考DataPoint文档 |
DataSource - 数据源
<数据源是对用户数据的描述. 小米健康云使用数据源来标识用户上传的数据, 每个数据都必须有且只有一个数据源标识/p>
| 字段名称 | 类型 | 选填 | 说明 |
|---|---|---|---|
| name | String | optional | 数据源名,对于同一个用户而言,name是可以重复的. 数据源名称是人类可读的,应该有实际含义的 |
| type | Integer | required | 数据源类型,目前数据源类型只有两种:raw和derived.由于数据是通过app读取传感器设备,然后再经由该app上传到MiFitStore,所以如果app对数据进行了加工处理.那么数据源类型应该是derived,否则应该是raw. 数据源类型是枚举值:
|
| dataStreamId | String | optional | 数据源ID值,该值是由服务端生成,对于同一用户,数据源的dataStreamId是唯一的. 用户在创建数据源时,不需要提供dataStreamId.服务端在创建数据源成功后,会在返回报文中包含dataStreamId.用户应该从返回报文中获取该数据源的dataStreamId,然后在后续和该数据源的相关交互中,提供该dataStreamId. |
| dataStreamName | String | optional | 数据流名称,对于同一用户而言,数据流名称可以重复. 数据流名称对应的是采集数据的传感器的名称 |
| dataType | DataType | required | 数据源标识数据的数据类型, 具体请参考DataType文档 |
| device | Device | required | 数据源标识数据的设备信息, 具体请参考Device文档 |
| application | Application | required | 数据源标识数据的应用程序信息,具体请参考Application文档 |
DataSourceType - 数据源类型
DataSourceType描述的是应用程序是否对传感器采集的数据进行加工.传感器采集的数据是raw类型数据,这些数据需要通过app上传到MiFitStore.如果app在上传数据之前,对传感器采集到的数据进行了加工处理,那么DataSourceType应该设置为derived,否则应该为raw
| 类型值 | 类型名称 |
|---|---|
| 1 | raw |
| 2 | derived |
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有两个字段:
|
| 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个字段:
|
| 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表示测量时刻用户的体重, 单位是千克 |
Device - 设备
Device描述采集用户运动健身数据的设备信息
| 字段名称 | 类型 | 选填 |
|---|---|---|
| manufacturer | String | required |
| model | String | required |
| version | String | required |
| uid | String | required |
| type | Integer | required |
DeviceType - 设备类型
DeviceType是指采集运动健身相关数据的设备类型. 小米健康云定义了一些设备类型, 目前设备类型不支持用户自定义扩展. 对于小米健康云未定义的设备, 应该使用unknown类型. 注意: 设备类型是枚举类型.
| 类型值 | 类型名称 |
|---|---|
| 1 | unknown |
| 2 | phone |
| 3 | tablet |
| 4 | watch |
| 5 | chest_strap |
| 6 | scale |
| 7 | band |
4. SDK下载与接入使用说明
| SDK运行平台 | 发布日期 | 下载连接 | 系统版本约束 | 接入使用说明 |
|---|---|---|---|---|
| Android | 2015-07-19 | 点击下载 | 最低支持: Android2.2 | Android SDK使用说明 |
| iOS | 2015-07-19 | 点击下载 | 最低支持: iOS 5.0 | iOS SDK使用说明 |
5. FAQ
在集成使用过程中遇到任何问题, 请联系我们：DevFit@xiaomi.com. 也可以添加QQ群: 385428920, 群中会有工程师解答您的问题.