本文档介绍如何使用 Fitness REST API 记录锻炼。
第 1 步:设置项目
您需要在 Google API 控制台中设置一个项目,并激活对 Fitness REST API 的访问权限,如使用入门中所述。
第 2 步:对您的应用进行身份验证
您的应用需要使用访问令牌对向 Fitness API 发出的请求进行身份验证。为了获取访问令牌,您的应用需要包含客户端专用凭据和访问权限范围,如向请求授权中所述。
第 3 步:创建数据源
数据源表示特定类型的传感器数据源。插入健身存储区的所有数据都必须与数据源相关联。您只需创建一次数据源,便可在以后的会话中重复使用。
如需创建数据源,请使用以下参数提交经过身份验证的 HTTP 请求:
- HTTP 方法
- 发布
- 资源
https://www.googleapis.com/fitness/v1/users/me/dataSources
me
用户 ID 是指通过访问令牌向请求授权的用户。- 请求正文
{ "name": "example-fit-heart-rate", "dataStreamId": "raw:com.google.heart_rate.bpm:1234567890:Example Fit:example-fit-hrm-1:123456", "dataType": { "field": [{ "name": "bpm", "format": "floatPoint" }], "name": "com.google.heart_rate.bpm" }, "application": { "packageName": "com.example.fit.someapp", "version": "1.0" }, "device": { "model": "example-fit-hrm-1", "version": "1", "type": "watch", "uid": "123456", "manufacturer":"Example Fit" }, "type": "raw" }
此请求会创建一个表示心率监测器的数据源,该监测器会提供 com.google.heart_rate.bpm
类型的健身数据。您必须指定数据源的 ID,此 ID 可以是任何值。此示例中的数据源 ID 遵循合理的命名惯例,您可以采用该惯例。如果数据仅由应用生成,则设备组件是可选的。
如果请求成功,响应将是 200 OK
状态代码。
如需详细了解数据源,请参阅 Users.dataSources
资源的 API 参考文档。
第 4 步:添加数据点
您可以使用数据集在健身存储区中插入数据点。数据集是来自单个数据源的数据点的集合,时间限定。
如需创建数据集并为其添加点,请使用以下参数提交经过身份验证的 HTTP 请求:
- HTTP 方法
- 补丁
- 资源
https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.heart_rate.bpm:1234567890:Example%20Fit:example-fit-hrm-1:123456/datasets/1411053997000000000-1411057556000000000该网址包含数据源 ID 以及数据集的开始和结束时间(以纳秒为单位)。
- 请求正文
{ "minStartTimeNs": 1411053997000000000, "maxEndTimeNs": 1411057556000000000, "dataSourceId": "raw:com.google.heart_rate.bpm:1234567890:Example Fit:example-fit-hrm-1:123456", "point": [ { "startTimeNanos": 1411053997000000000, "endTimeNanos": 1411053997000000000, "dataTypeName": "com.google.heart_rate.bpm", "value": [ { "fpVal": 78.8 } ] }, { "startTimeNanos": 1411055000000000000, "endTimeNanos": 1411055000000000000, "dataTypeName": "com.google.heart_rate.bpm", "value": [ { "fpVal": 89.1 } ] }, { "startTimeNanos": 1411057556000000000, "endTimeNanos": 1411057556000000000, "dataTypeName": "com.google.heart_rate.bpm", "value": [ { "fpVal": 62.45 } ] } ] }
此请求会为上一步中的数据源创建一个包含三个心率数据点的数据集。
如果请求成功,响应将是 200 OK
状态代码。
如需详细了解数据集,请参阅 Users.dataSources.datasets
资源的 API 参考文档。
生成有效的时间戳
上例中的时间戳以纳秒为单位。如需生成有效的时间戳,可以使用以下 Python 脚本:
from datetime import datetime, timedelta import calendar def date_to_nano(ts): """ Takes a datetime object and returns POSIX UTC in nanoseconds """ return calendar.timegm(ts.utctimetuple()) * int(1e9) if __name__ == '__main__': print 'Current time is %d' % date_to_nano(datetime.now()) print 'Time 1 hour ago was %d' % date_to_nano(datetime.now() + timedelta(hours=-1))
第 5 步:创建会话
现在,您已将数据插入健身存储区,接下来可以插入时段来为此锻炼活动提供其他元数据。时段表示用户进行某项健身活动的时间间隔。
如需为此锻炼创建时段,请使用以下参数提交经过身份验证的 HTTP 请求:
- HTTP 方法
- PUT
- 资源
https://www.googleapis.com/fitness/v1/users/me/sessions/sessionId
sessionId 是任意的,并且对于与经过身份验证的用户关联的所有会话必须是唯一的。
- 请求正文
{ "id": "example-fit-1411053997", "name": "Example Fit Run on Sunday Afternoon", "description": "Example Fit Running Session", "startTimeMillis": 1411053997000, "endTimeMillis": 1411057556000, "application": { "name": "Foo Example App", "version": "1.0" }, "activityType": 8 }
选择简单易懂的描述性会话名称,因为其他应用可能会使用该名称来总结会话。会话的开始和结束时间均以毫秒(而非纳秒)为单位。为会话和数据源使用相同的软件包名称;这样可以使数据更加一致,并确保数据归因能够链接回您的应用。
本次课程中指定的时间间隔涵盖之前插入的心率数据,因此 Google 健身会将这些数据点与本次课程相关联。
如需详细了解会话,请参阅 Users.sessions
资源的 API 参考文档。
第 6 步:创建活动细分
活动细分可帮助您表示会话中的不同活动。
活动细分是涵盖单个活动的时间细分。例如,如果用户跑步一小时,您可以针对这个小时创建一个类型为 running
(8) 的活动细分。如果用户跑步 25 分钟,休息 5 分钟,然后再跑步半小时,您可以分别创建三个连续的活动细分,类型为 running
、unknown
和 running
。
创建活动细分与添加任何其他数据点一样。要创建活动细分,请先创建一个活动细分数据源,然后创建数据集并为其添加活动细分数据点。
以下示例在与心率读数相同的时间范围内创建三个细分(跑步、休息和跑步),假设您已经创建了一个活动细分数据源,并且数据源 ID 为“raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456”:
- HTTP 方法
- 补丁
- 资源
https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000- 请求正文
{ "minStartTimeNs": 1411053997000000000, "maxEndTimeNs": 1411057556000000000, "dataSourceId": "raw:com.google.activity.segment:1234567890", "point": [ { "startTimeNanos": 1411053997000000000, "endTimeNanos": 1411053997000000000, "dataTypeName": "com.google.activity.segment", "value": [ { "intVal": 8 } ] }, { "startTimeNanos": 1411055000000000000, "endTimeNanos": 1411055000000000000, "dataTypeName": "com.google.activity.segment", "value": [ { "intVal": 4 } ] }, { "startTimeNanos": 1411057556000000000, "endTimeNanos": 1411057556000000000, "dataTypeName": "com.google.activity.segment", "value": [ { "intVal": 8 } ] } ] }
系统会将这些活动细分数据点添加到专为处理活动细分而创建的数据源。您可以为每组细分创建新的数据源,但应该重复使用特定于特定类型的会话(如跑步)的数据源。
会话指定活动类型,该类型应与用户参与的整体活动一致。即使用户在跑步时休息一下,整体锻炼活动仍然是跑步。一般来说,会话的活动类型将与主要活动细分类型相匹配。
使用 activity 类型 unknown (4) 表示用户正在休息,因为您可能不知道用户正在做什么:他们可能在静止、拉伸、喝水等等。如果知道用户没有移动,则可以使用静止 (3)。
有关活动类型的详细列表,请参阅活动类型。
摘要
在本教程中,您创建了数据类型和活动细分的数据源;将数据点插入了健身存储区;创建了活动细分来表示锻炼期间进行的不同活动;您插入了一个涵盖整个锻炼的时段。
Google 健身会将您插入的数据以及该时间间隔内可用的任何其他数据与代表用户锻炼情况的时段关联起来。