如何記錄運動活動

本文件說明如何使用 Fitness REST API 記錄運動。

步驟 1:設定專案

您必須在 Google API 控制台中設定專案,並啟用 Fittness 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 Fit 會將這些資料點與這個工作階段建立關聯。

如要進一步瞭解工作階段,請參閱 Users.sessions 資源的 API 參考資料。

步驟 6:建立活動區隔

活動區隔可讓您在工作階段中呈現不同的活動。 活動區隔是指涵蓋單一活動的時間區隔。舉例來說,如果使用者要執行 1 小時,您可以為整個小時建立 running (8) 類型的活動區隔。如果使用者執行了 25 分鐘,休息了 5 次,然後執行了半小時,您就可以分別建立 runningunknownrunning 類型的三個活動區隔。

建立活動區隔與新增其他資料點相同。若要建立活動區隔,請先建立活動區隔資料來源,然後建立資料集並新增活動區隔資料點。

以下範例來建立三個心率 (跑步、休息和跑步) 和心率讀數相同的時間範圍 (假設您已建立活動區隔的資料來源,而資料來源 ID 為「quot;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
    }
  ]
}
]
}

這些活動區隔資料點會新增至專為處理活動區隔而建立的資料來源。您可以為每一組區隔建立新的資料來源,但必須重複使用特定工作階段類型專屬的資料來源。

工作階段會指定活動類型,該類型應與使用者參與的整體活動相符。 即使使用者在跑步時休息片刻,整體運動仍然是跑步。一般來說,工作階段的活動類型會與主要活動區隔類型相符。

使用「不明」 (4) 活動類型來表示使用者處於靜止狀態,因為您可能不知道使用者正在執行什麼動作:可能是靜止、長時間延展、飲用水等。如果您知道使用者未移動,可以使用靜態 (3)。

如需活動類型的詳細清單,請參閱活動類型

摘要

在這個教學課程中,您建立了資料類型和活動區隔的資料來源;您已將資料點插入健身儲存庫;您建立的活動區隔代表在運動期間進行的不同活動;並且插入了涵蓋整個運動的工作階段。

Google Fit 會將您插入的資料和這段時間內可用的任何其他資料,與代表使用者運動的工作階段建立關聯。