如何記錄運動

本文說明如何使用 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 遵循合理的命名慣例 可以採用如果資料只會由應用程式產生，則裝置元件為選用項目。

如果要求成功，回應會是 200 OK 狀態碼。

如要進一步瞭解資料來源，請參閱 Users.dataSources 資源。

步驟 4：新增資料點

您可以使用資料集，在健身儲存庫中插入資料點。資料集是受時間限制的單一資料來源所提供的資料點集合。

如要建立資料集並新增路線點，請提交經過驗證的 HTTP 要求，並附上以下參數：

HTTP 方法
PATCH
資源

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 Fit 會將這些資料點與這個工作階段建立關聯。

如要進一步瞭解工作階段，請參閱 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 方法
PATCH
資源
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
    }
  ]
}
]
}

這些活動區隔資料點會新增至專門用來處理活動區隔的資料來源。您可以為每個區隔建立新的資料來源，但 請重複使用特定類型的工作階段 (例如跑步)

工作階段會指定活動類型，而該類型應與使用者參與的整體活動相符。即便使用者在跑步時休息，整個運動仍會進行。一般來說，工作階段的活動類型會與主要活動區隔類型相符。

使用 unknown (4) 活動類型表示使用者還在靜止狀態，因為您可能並非 例如瞭解使用者的活動 (例如靜止不動或喝水等等)。如果發生以下情況： 知道使用者未移動，可以使用 still (3)。

如需詳細的活動類型清單，請參閱「活動類型」。

摘要

在本教學課程中，您建立了資料類型和活動區隔的資料來源。您已插入 複製到健身商店您建立了活動區隔來代表 運動期間發生的活動；成功插入了涵蓋整個工作階段的 訓練。

Google Fit 會將您插入的資料和該時間間隔可用的任何其他資料，與代表使用者健身活動的工作階段建立關聯。