So zeichnest du ein Training auf

In diesem Dokument wird beschrieben, wie du ein Training mit der Fitness REST API aufzeichnest.

Schritt 1: Projekt einrichten

Sie müssen ein Projekt in der Google API Console einrichten und den Zugriff auf die Fitness REST API aktivieren, wie unter Erste Schritte beschrieben.

Schritt 2: Anwendung authentifizieren

Deine App muss Anfragen an die Fitness API mithilfe eines Zugriffstokens authentifizieren. Um das Zugriffstoken zu erhalten, umfasst Ihre Anwendung clientspezifische Anmeldedaten und einen Zugriffsbereich, wie unter Anfragen autorisieren beschrieben.

Schritt 3: Datenquelle erstellen

Eine Datenquelle stellt eine Quelle von Sensordaten eines bestimmten Typs dar. Alle in den Fitnessspeicher eingefügten Daten müssen einer Datenquelle zugeordnet sein. Sie können Datenquellen einmal erstellen und für zukünftige Sitzungen wiederverwenden.

Um eine Datenquelle zu erstellen, senden Sie eine authentifizierte HTTP-Anfrage mit folgenden Parametern:

HTTP-Methode
POST
Ressource

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

Die Nutzer-ID me bezieht sich auf den Nutzer, dessen Zugriffstoken die Anfrage autorisiert.

Anfragetext
{
"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"
}

Durch diese Anfrage wird eine Datenquelle erstellt, die einen Herzfrequenzmesser darstellt, der Fitnessdaten vom Typ com.google.heart_rate.bpm bereitstellt. Sie müssen die ID der Datenquelle angeben. Sie kann ein beliebiger Wert sein. Für die Datenquellen-ID in diesem Beispiel folgt eine sinnvolle Namenskonvention, die Sie übernehmen können. Die Gerätekomponente ist optional, wenn die Daten nur von einer App generiert werden.

Wenn die Anfrage erfolgreich ist, wird der Statuscode 200 OK zurückgegeben.

Weitere Informationen zu Datenquellen finden Sie in der API-Referenz für die Ressource Users.dataSources.

Schritt 4: Datenpunkte hinzufügen

Sie verwenden Datasets, um Datenpunkte im Fitnessspeicher einzufügen. Ein Dataset ist eine zeitlich begrenzte Sammlung von Datenpunkten aus einer einzelnen Datenquelle.

Wenn Sie ein Dataset erstellen und Punkte hinzufügen möchten, senden Sie eine authentifizierte HTTP-Anfrage mit den folgenden Parametern:

HTTP-Methode
PATCH
Ressource

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

Die URL enthält die Datenquellen-ID sowie die Start- und Endzeiten des Datensatzes in Nanosekunden.

Anfragetext
{
"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
    }
  ]
}
]
}

Diese Anfrage erstellt für die Datenquelle im vorherigen Schritt ein Dataset mit drei Herzfrequenz-Datenpunkten innerhalb einer Stunde.

Wenn die Anfrage erfolgreich ist, wird der Statuscode 200 OK zurückgegeben.

Weitere Informationen zu Datasets finden Sie in der API-Referenz für die Ressource Users.dataSources.datasets.

Gültige Zeitstempel generieren

Die Zeitstempel im obigen Beispiel werden in Nanosekunden angegeben. Zum Generieren gültiger Zeitstempel können Sie das folgende Python-Skript verwenden:

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))

Schritt 5: Sitzung erstellen

Nachdem Sie nun Daten in den Fitnessspeicher eingefügt haben, können Sie eine Sitzung einfügen, um zusätzliche Metadaten für dieses Training bereitzustellen. Sitzungen stellen ein Zeitintervall dar, in dem Nutzer eine Fitnessaktivität durchführen.

Reichen Sie eine authentifizierte HTTP-Anfrage mit folgenden Parametern ein, um eine Sitzung für dieses Training zu erstellen:

HTTP-Methode
PUT
Ressource

https://www.googleapis.com/fitness/v1/users/me/sessions/sessionId

Der sessionId ist beliebig und muss für alle Sitzungen, die dem authentifizierten Nutzer zugeordnet sind, eindeutig sein.

Anfragetext
{
"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
}

Wählen Sie einen Sitzungsnamen, der für Menschen lesbar und aussagekräftig ist, da er von anderen Anwendungen möglicherweise verwendet wird, um die Sitzung zusammenzufassen. Die Start- und Endzeiten für Sitzungen werden in Millisekunden (nicht Nanosekunden) angegeben. Verwenden Sie für Ihre Sitzungen und Ihre Datenquellen denselben Paketnamen. Dadurch werden die Daten einheitlicher und die Datenattribution wird wieder mit Ihrer App verknüpft.

Das in dieser Sitzung angegebene Zeitintervall deckt die zuvor eingefügten Herzfrequenzdaten ab. Google Fit verknüpft diese Datenpunkte daher mit dieser Sitzung.

Weitere Informationen zu Sitzungen finden Sie in der API-Referenz für die Ressource Users.sessions.

Schritt 6: Aktivitätssegmente erstellen

Mithilfe von Aktivitätssegmenten können Sie verschiedene Aktivitäten innerhalb einer Sitzung darstellen. Ein Aktivitätssegment ist ein Zeitsegment, das eine einzelne Aktivität abdeckt. Wenn ein Nutzer beispielsweise eine einstündige Laufzeit durchführt, können Sie ein Aktivitätssegment vom Typ running (8) für die gesamte Stunde erstellen. Wird ein Nutzer 25 Minuten lang ausgeführt, fünfmal eine Pause und dann noch eine halbe Stunde, können Sie drei aufeinanderfolgende Aktivitätssegmente vom Typ running, unknown bzw. running erstellen.

Ein Aktivitätssegment wird genau wie ein anderer Datenpunkt erstellt. Um Aktivitätssegmente zu erstellen, müssen Sie zuerst eine Datenquelle für Aktivitätssegmente erstellen, dann ein Dataset erstellen und diesem Aktivitätssegmentdatenpunkte hinzufügen.

Im folgenden Beispiel werden drei Segmente (Laufen, Ruhe und Laufen) mit denselben Zeiträumen wie die Herzfrequenzmesswerte erstellt, vorausgesetzt, Sie haben bereits eine Datenquelle für ein Aktivitätssegment erstellt und die Datenquellen-ID lautet „raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456“:

HTTP-Methode
PATCH
Ressource
https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000
Anfragetext
{
"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
    }
  ]
}
]
}

Die Datenpunkte der Aktivitätssegmente werden einer Datenquelle hinzugefügt, die speziell zur Verarbeitung von Aktivitätssegmenten erstellt wurde. Sie können für jeden Satz von Segmenten eine neue Datenquelle erstellen, sollten aber eine für einen bestimmten Sitzungstyp (z. B. Laufen) wiederverwenden.

Sitzungen geben einen Aktivitätstyp an, der der Gesamtaktivität des Nutzers entsprechen sollte. Auch wenn ein Nutzer beim Laufen eine Pause macht, ist das gesamte Training trotzdem ein Lauf. Im Allgemeinen entspricht der Aktivitätstyp der Sitzung dem dominanten Aktivitätssegmenttyp.

Verwenden Sie den Aktivitätstyp unbekannt (4), um anzuzeigen, dass sich ein Nutzer ausruht, da Sie möglicherweise nicht wissen, was der Nutzer tut: Möglicherweise befindet er sich still oder trinkt Wasser usw. Wenn Sie wissen, dass sich der Nutzer nicht bewegt, können Sie still (3) verwenden.

Eine ausführliche Liste der Aktivitätstypen finden Sie unter Aktivitätstypen.

Zusammenfassung

In dieser Anleitung haben Sie Datenquellen für Datentypen und Aktivitätssegmente erstellt, Datenpunkte in den Fitnessspeicher eingefügt, Aktivitätssegmente zur Darstellung der verschiedenen Aktivitäten während eines Trainings erstellt und eine Sitzung eingefügt, die das gesamte Training abdeckt.

Google Fit verknüpft die von dir eingegebenen Daten und alle anderen für dieses Zeitintervall verfügbaren Daten einer Sitzung, die das Training des Nutzers darstellt.