开放平台v1 v2三方升级v3指南

受众

目前使用华米V1/V2开放平台接入的第三方原生app或网站。

华米V1/V2开放平台只支持使用小米账号登录华米app的用户。随着2017年6月份小米运动app3.0的上线，小米运动app也同时支持使用微信账号登录的用户。因为微信账号的普遍性和便利性，使用微信账号登录小米运动的用户正在快速增加。目前只有华米V3开放平台支持获取使用微信账号登录小米运动app的用户数据。
V3版的API可以支持更多的应用场景。而且即将推出V1/V2版本没有的主动推送功能。之后还计划支持 GraphQL的接口。
华米开放平台V3是基于业界标准OAuth 2.0构建的平台，授权接口标准，用户和三方都容易理解。
后续华米只会在V3平台上增加新的数据和功能，V1/V2平台会逐渐停止维护直至停止服务。

小米ID: 使用小米账号登录/授权的情况下，V1由小米方，V2由华米方，返回的userId，均为小米账号ID。
华米ID: 华米为每位用户分配的唯一ID。每一个使用小米账号登录的用户会对应一个唯一的华米ID；每一个使用微信登录的用户也会有一个对应的唯一的华米ID。一个华米用户可以绑定一个小米账号、同时也绑定一个微信账号，用户可以任意使用这两种登录方式，都对应到同一个华米ID。
华米开放平台V1: 直接通过在小米开放平台注册app，获取小米access_token来访问数据的版本
华米开放平台V2: 通过华米给定地址https://openapi.mi-ae.cn/xiaomiLogin.json来进行授权的版本
华米开放平台V3: 通过华米给定地址https://user.huami.com，或者https://users-cn.huami.com进行授权，或通过集成授权sdk拉起小米运动app进行授权的方式

其中1和2因为可能涉及到Native App的升级，需要尽快开始着手。

❗	如果有在Native App中直接调用华米开放平台V1/V2版本的情况，步骤3也需要尽快展开

💡	使用新的授权接入方式后获取的access_token可以用来访问V1和V2的接口。V1中的token传递参数为hm_access_token，V2中的token传递参数为appToken，将获取到的access_token值传入这两个参数即可

如果有在服务端存储中使用V1/V2授权过程中获得的小米ID标识用户的情况，则需要将其转换为华米ID。我们提供了在线的ID转化接口，包括单个转换和批量转换，以便第三方实时/批量转换ID。ID转换的API接口请参见华米ID转换API

🔥	请不要在小米运动服务的高峰期调用批量转换接口。批量转换的时间请在每天00:00-5:00和12:00-17:00进行。如果是新用户的单个ID实时转换，因为量一般不会很大，可以在任何时间进行。目前单个ID转化的流量上限为100次/秒

使用V3版本的开放平台，需要将老的V1/V2的接入方式转换为V3的接入方式，分为下面几种情况

1, 转换华米ID。在用户流量低的时间段，停服，通过API进行小米ID→华米ID的批量转换。如果服务代码中有任何接收老版本app上传的小米ID的入口，通过调用ID转化API进行实时转换，上线更改后的服务代码。通过这两步，可以保证存量和新的用户都使用华米ID来标识

2, 在新版本的app中更改接入方式。如果需要向服务端传递华米用户的ID，使用获取的access_token调用用户基本信息接口API。该API的返回的userId字段即为华米ID

❗	V1的三方在转换接入方式时需要使用小米的access_token来转换华米v3的access_token来避免用户重新授权。转换的API请参见 https://huamitech.github.io/rest-api/api-token.html [小米access_token换华米access_token]。另外V1的三方需要提供在小米开放平台注册的appId

💡	如果在步骤1中已经有从小米ID转化为华米ID的逻辑，在app传递华米ID的情况下，则不需要进行转换

3, 在服务端转换华米API为V3版本

💡	V2的三方之前获取的appToken可以复用，可以传递到V3 API的Authorzation header中。这样的支持是为了避免让V2的三方已经授权的用户再次授权

如果遇到问题，请在 Issues 中提出，我们会尽快答复。

常见问题请参见 FAQ