Comment enregistrer un entraînement

Ce document explique comment enregistrer un entraînement à l'aide de l'API REST de remise en forme.

Étape 1: Configurer un projet

Vous devez configurer un projet dans la console Google APIs et activer l'accès à l'API REST de Fitness, comme décrit dans la section Premiers pas.

Étape 2: Authentifiez votre application

Votre application doit authentifier les requêtes adressées à l'API Fitness à l'aide d'un jeton d'accès. Pour obtenir le jeton d'accès, votre application inclut des identifiants spécifiques au client et un champ d'application, comme décrit dans la section Autoriser les requêtes.

Étape 3: Créez une source de données

Une source de données représente une source de données de capteurs d'un certain type. Toutes les données insérées dans le magasin de remise en forme doivent être associées à une source de données. Vous pouvez créer des sources de données une seule fois et les réutiliser pour de futures sessions.

Pour créer une source de données, envoyez une requête HTTP authentifiée avec les paramètres suivants:

Méthode HTTP
POST
Ressource

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

L'ID utilisateur me fait référence à l'utilisateur dont le jeton d'accès autorise la requête.

Corps de la requête
{
"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"
}

Cette requête crée une source de données qui représente un moniteur de fréquence cardiaque fournissant des données de remise en forme de type com.google.heart_rate.bpm. Vous devez spécifier l'ID de la source de données. Il peut s'agir de n'importe quelle valeur. Dans cet exemple, l'ID de la source de données suit une convention d'attribution de noms raisonnable que vous pouvez adopter. Le composant "Appareil" est facultatif si les données ne sont générées que par une application.

Si la requête aboutit, la réponse est un code d'état 200 OK.

Pour en savoir plus sur les sources de données, consultez la documentation de référence de l'API pour la ressource Users.dataSources.

Étape 4: Ajoutez des points de données

Vous utilisez des jeux de données pour insérer des points de données dans le magasin de remise en forme. Un ensemble de données est un ensemble de points de données provenant d'une seule source de données, limités dans le temps.

Pour créer un ensemble de données et y ajouter des points, envoyez une requête HTTP authentifiée avec les paramètres suivants:

Méthode HTTP
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

L'URL inclut l'ID de la source de données, ainsi que les heures de début et de fin de l'ensemble de données en nanosecondes.

Corps de la requête
{
"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
    }
  ]
}
]
}

Cette requête crée un ensemble de données avec trois points de données de fréquence cardiaque dans un délai d'une heure pour la source de données de l'étape précédente.

Si la requête aboutit, la réponse est un code d'état 200 OK.

Pour en savoir plus sur les ensembles de données, consultez la documentation de référence de l'API pour la ressource Users.dataSources.datasets.

Générer des codes temporels valides

Dans l'exemple ci-dessus, les codes temporels sont exprimés en nanosecondes. Pour générer des horodatages valides, vous pouvez utiliser le script Python suivant:

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

Étape 5: Créez une session

Maintenant que vous avez inséré des données dans le magasin de remise en forme, vous pouvez insérer une session pour fournir des métadonnées supplémentaires pour cet entraînement. Les sessions représentent un intervalle de temps pendant lequel les utilisateurs effectuent une activité physique.

Pour créer une session pour cet entraînement, envoyez une requête HTTP authentifiée avec ces paramètres:

Méthode HTTP
PUT
Ressource

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

La propriété sessionId est arbitraire et doit être unique pour toutes les sessions associées à l'utilisateur authentifié.

Corps de la requête
{
"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
}

Choisissez un nom de session lisible et descriptif, car d'autres applications peuvent l'utiliser pour résumer la session. Les heures de début et de fin des sessions sont exprimées en millisecondes (et non en nanosecondes). Utilisez le même nom de package pour vos sessions et vos sources de données. Les données seront ainsi plus cohérentes et l'attribution de données sera associée à votre application.

L'intervalle de temps spécifié dans cette session couvre les données de fréquence cardiaque insérées précédemment. Google Fit associe donc ces points de données à cette session.

Pour en savoir plus sur les sessions, consultez la documentation de référence de l'API pour la ressource Users.sessions.

Étape 6: Créez des segments d'activité

Les segments d'activité vous permettent de représenter différentes activités au cours d'une session. Un segment d'activité est un segment de temps qui couvre une seule activité. Par exemple, si un utilisateur part pour une course d'une heure, vous pouvez créer un segment d'activité de type running (8) pour toute l'heure. Si un utilisateur s'exécute pendant 25 minutes, fait une pause de cinq secondes, puis court encore une demi-heure, vous pouvez créer trois segments d'activité consécutifs de types running, unknown et running respectivement.

Créer un segment d'activité revient à ajouter un autre point de données. Pour créer des segments d'activité, commencez par créer une source de données de segment d'activité, puis créez un ensemble de données et ajoutez-y des points de données de segment d'activité.

L'exemple suivant crée trois segments (course à pied, repos et course) dans les mêmes périodes que les relevés de fréquence cardiaque, en supposant que vous avez déjà créé une source de données de segment d'activité et que l'ID de la source de données est "raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456":

Méthode HTTP
PATCH
Ressource
https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000
Corps de la requête
{
"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
    }
  ]
}
]
}

Ces points de données de segments d'activité sont ajoutés à une source de données créée spécifiquement pour gérer les segments d'activité. Vous pouvez créer une source de données pour chaque ensemble de segments, mais vous devez en réutiliser une qui est dédiée à un type de session particulier, comme la session.

Les sessions spécifient un type d'activité, qui doit correspondre à l'activité globale de l'utilisateur. Même si un utilisateur fait une pause pendant la course, l’entraînement global est toujours une course. En général, le type d'activité de la session correspond au type de segment d'activité principal.

Utilisez le type d'activité unknown (4) pour indiquer qu'un utilisateur se repose, car vous ne savez peut-être pas ce qu'il fait: il peut être immobile ou s'étirer, boire de l'eau, etc. Si vous savez que l'utilisateur ne bouge pas, vous pouvez utiliser still (3).

Pour obtenir la liste détaillée des types d'activités, consultez Types d'activités.

Résumé

Dans ce tutoriel, vous avez créé des sources de données pour des types de données et des segments d'activité, vous avez inséré des points de données dans le magasin de remise en forme, vous avez créé des segments d'activité pour représenter les différentes activités qui ont lieu pendant un entraînement, et vous avez inséré une session qui couvre l'intégralité de l'entraînement.

Google Fit associe les données que vous avez insérées et toutes les autres données disponibles pour cet intervalle de temps à une session qui représente l'entraînement de l'utilisateur.