本文件說明如何使用 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 次,然後執行了半小時,您就可以分別建立 running
、unknown
和 running
類型的三個活動區隔。
建立活動區隔與新增其他資料點相同。若要建立活動區隔,請先建立活動區隔資料來源,然後建立資料集並新增活動區隔資料點。
以下範例來建立三個心率 (跑步、休息和跑步) 和心率讀數相同的時間範圍 (假設您已建立活動區隔的資料來源,而資料來源 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 會將您插入的資料和這段時間內可用的任何其他資料,與代表使用者運動的工作階段建立關聯。