如何录制锻炼

本文档介绍了如何使用 Fitness REST API 记录锻炼。

第 1 步:设置项目

您需要在 Google API 控制台中设置项目并激活对 Fits 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 遵循您可以采用的合理命名惯例。如果数据仅由应用生成,则设备组件是可选的。

如果请求成功,则响应为 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 方法
输入
资源

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 分钟,然后又运行 0.5 个小时,您可以分别创建 3 个类型为 runningunknownrunning 的连续活动细分。

创建活动细分的方法与添加任何其他数据点相同。如需创建活动细分,请先创建活动细分数据源,然后创建数据集并向其中添加活动细分数据点。

以下示例在心率读数相同的时间范围内创建三个细分(跑步、休息和跑步),假设您已创建活动细分数据源,并且数据源 ID 为“raw:com.google.activity.section: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 类型将与主要的 Activity 细分类型匹配。

使用活动类型 unknown (4) 表示用户正在休息,因为您可能不知道用户正在做什么:他们可能静止不动,或者拉伸、饮水等。如果您知道用户没有移动,则可以使用 (3)。

有关活动类型的详细列表,请参阅活动类型

总结

在本教程中,您为数据类型和活动细分创建了数据源;在健身数据存储区中插入了数据点;创建了代表锻炼期间不同活动的活动细分,并插入了一个涵盖整个健身过程的会话。

Google 健身会将您插入的数据以及该时间段内的任何其他可用数据与代表用户健身的时段相关联。