ワークアウトを記録する方法

このドキュメントでは、Fitness REST API を使用してワークアウトを記録する方法について説明します。

ステップ 1: プロジェクトを設定する

Google API Console でプロジェクトを設定し、スタートガイドの説明のとおり、Fitness REST API へのアクセスを有効にする必要があります。

ステップ 2: アプリを認証する

アプリは、アクセス トークンを使用して Fitness API へのリクエストを認証する必要があります。アクセス トークンを取得するために、リクエストの承認で説明されているように、アプリにはクライアント固有の認証情報とアクセス スコープが含まれています。

ステップ 3: データソースを作成する

データソースは、特定のタイプのセンサーデータのソースを表します。フィットネス ストアに挿入されるデータはすべて、データソースに関連付けられている必要があります。データソースを一度作成すると、今後のセッションで再利用できます。

データソースを作成するには、次のパラメータを指定して認証済みの HTTP リクエストを送信します。

HTTP メソッド
POST
リソース

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 になります。

データソースの詳細については、API リファレンスの 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

この URL には、データソース 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
    }
  ]
}
]
}

このリクエストでは、前のステップのデータソースに対して、1 時間以内に 3 つの心拍数データポイントを含むデータセットを作成します。

リクエストが成功すると、レスポンスはステータス コード 200 OK になります。

データセットの詳細については、API リファレンスの Users.dataSources.datasets リソースをご覧ください。

有効なタイムスタンプを生成する

上記の例のタイムスタンプはナノ秒単位です。有効なタイムスタンプを生成するには、次の 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 はそれらのデータポイントをこのセッションに関連付けます。

セッションの詳細については、API リファレンスの Users.sessions リソースをご覧ください。

ステップ 6: アクティビティ セグメントを作成する

アクティビティ セグメントは、セッション内のさまざまなアクティビティを表すのに役立ちます。 アクティビティ セグメントは、1 つのアクティビティを含む時間セグメントです。たとえば、ユーザーが 1 時間のランニングに出かける場合、その 1 時間のアクティビティ セグメントをタイプ running（8）で作成できます。ユーザーが 25 分間走り、5 分間休憩した後、さらに 30 分間走った場合、それぞれ running、unknown、running タイプの 3 つの連続したアクティビティ セグメントを作成できます。

アクティビティ セグメントの作成は、他のデータポイントの追加と同じです。アクティビティ セグメントを作成するには、まずアクティビティ セグメントのデータソースを作成してから、データセットを作成して、アクティビティ セグメントのデータポイントを追加します。

次の例では、アクティビティ セグメントのデータソースをすでに作成しており、データソース ID が「raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456」であると仮定し、心拍数の測定値と同じ時間枠に 3 つのセグメント（ランニング、安静、ランニング）を作成します。

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 は、挿入されたデータとその時間間隔で利用可能なその他のデータを、ユーザーのワークアウトを表すセッションに関連付けます。