如何記錄運動

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

步驟 1：設定專案

您需要在 Google API 控制台中設定專案，並啟用 Fitness REST API 的存取權，如開始使用中所述。

步驟 2：驗證應用程式

應用程式必須使用存取權杖驗證傳送至 Fitness API 的要求。為了取得存取權杖，應用程式包含用戶端特定憑證及存取權範圍，如授權要求一文所述。

步驟 3：建立資料來源

資料來源代表特定類型的感應器資料來源。所有插入至健身商店的資料都必須與資料來源建立關聯。您只需建立一次資料來源，就能重複使用於日後的工作階段。

如要建立資料來源，請使用以下參數提交已驗證的 HTTP 要求：

HTTP 方法
POST
資源

https://www.googleapis.com/fitness/v1/users/me/dataSources

me User-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 方法
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 Fit 會將這些資料點與這個時段建立關聯。

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

步驟 6：建立活動區隔

活動區隔可協助您代表工作階段中的不同活動。活動區隔是包含單一活動的時間區隔。舉例來說，如果使用者跑步一小時，您可以建立整小時 running (8) 類型的活動區隔。如果使用者跑步 25 分鐘，先休息 5，再跑半小時，您就可以分別建立 running、unknown 和 running 類型的連續活動區隔。

建立活動區隔與新增任何其他資料點相同。如要建立活動區隔，請先建立活動區隔資料來源，然後建立資料集並在其中新增活動區隔資料點。

以下範例假設你已建立活動區隔資料來源，且資料來源 ID 為「raw:com.google.activity.segment:1234567890:範例 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) 表示使用者處於靜止狀態，因為您可能不知道使用者正在做什麼：他們可能仍在靜止，或是正在伸展、喝水等。如果您知道使用者並未移動，可以使用「still」 (3)。

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

摘要

在本教學課程中，您將為資料類型和活動區隔建立資料來源、在健身商店中插入資料點；建立了活動區隔來代表健身期間發生的不同活動；並且插入了涵蓋整個健身的時段。

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