Cómo grabar un entrenamiento

En este documento, se describe cómo registrar un entrenamiento con la API de REST de Fitness.

Importante: Para conocer las prácticas recomendadas a la hora de administrar datos del usuario, consulta Uso responsable de Google Fit.

Paso 1: Configura un proyecto

Debes configurar un proyecto en la Consola de API de Google y activar el acceso a la API de REST de Fitness, como se describe en Comenzar.

Paso 2: Autentica tu app

Tu app debe autenticar solicitudes a la API de Fitness mediante un token de acceso. Para obtener el token de acceso, tu app incluye credenciales específicas del cliente y un alcance de acceso, como se describe en Autoriza solicitudes.

Paso 3: Cree una fuente de datos

Una fuente de datos representa una fuente de datos de sensores de un tipo en particular. Todos los datos insertados en la tienda de entrenamiento deben estar asociados con una fuente de datos. Puedes crear fuentes de datos una vez y reutilizarlas para sesiones futuras.

Para crear una fuente de datos, envía una solicitud HTTP autenticada con estos parámetros:

Método HTTP

PUBLICAR

Recurso

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

El ID del usuario me hace referencia al usuario cuyo token de acceso autoriza la solicitud.

Cuerpo de la solicitud

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

Esta solicitud crea una fuente de datos que representa un monitor de ritmo cardíaco que proporciona datos de entrenamiento de tipo com.google.heart_rate.bpm. Debes especificar el ID de la fuente de datos, y puede ser cualquier valor. El ID de la fuente de datos de este ejemplo sigue una convención de nombres razonable que puedes adoptar. El componente del dispositivo es opcional si solo una app genera los datos.

Si la solicitud es exitosa, la respuesta es un código de estado 200 OK.

Para obtener más información sobre las fuentes de datos, consulta la referencia de la API del recurso Users.dataSources.

Paso 4: Agrega datos

Usa conjuntos de datos para insertar datos en la tienda de entrenamiento. Un conjunto de datos es una colección de datos de una sola fuente de datos limitada por el tiempo.

Para crear un conjunto de datos y agregarle puntos, envía una solicitud HTTP autenticada con estos parámetros:

Método HTTP

TRANSMITIR

Recurso

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

La URL incluye el ID de la fuente de datos y las horas de inicio y finalización del conjunto de datos en nanosegundos.

Cuerpo de la solicitud

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

Esta solicitud crea un conjunto de datos con tres datos de ritmo cardíaco dentro de una hora para la fuente de datos en el paso anterior.

Nota: Para los datos que tienen varios valores (como ubicación), el orden de los valores debe coincidir con la definición del tipo de datos.

Si la solicitud es exitosa, la respuesta es un código de estado 200 OK.

Para obtener más información sobre los conjuntos de datos, consulta la referencia de la API del recurso Users.dataSources.datasets.

Genera marcas de tiempo válidas

Las marcas de tiempo del ejemplo anterior están en nanosegundos. Para generar marcas de tiempo válidas, puedes usar la siguiente secuencia de comandos de 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))

Paso 5: Crea una sesión

Ahora que insertaste datos en la tienda de entrenamiento, puedes insertar una sesión a fin de proporcionar metadatos adicionales para este entrenamiento. Las sesiones representan un intervalo durante el cual los usuarios realizan una actividad de entrenamiento.

A fin de crear una sesión para este entrenamiento, envía una solicitud HTTP autenticada con estos parámetros:

Método HTTP

PUT

Recurso

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

sessionId es arbitrario y debe ser único para todas las sesiones asociadas con el usuario autenticado.

Cuerpo de la solicitud

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

Elige un nombre de sesión que sea legible y descriptivo, ya que otras apps pueden usarlo para resumir la sesión. Las horas de inicio y finalización de las sesiones se expresan en milisegundos (no en nanosegundos). Usa el mismo nombre de paquete para tus sesiones y fuentes de datos; esto hace que los datos sean más coherentes y garantiza que la atribución de datos se vincule a tu app.

El intervalo de tiempo especificado en esta sesión abarca los datos de ritmo cardíaco que se insertaron antes, por lo que Google Fit asocia esos datos con esta sesión.

Para obtener más información sobre las sesiones, consulta la referencia de la API para el recurso Users.sessions.

Paso 6: Crea segmentos de actividad

Los segmentos de actividad lo ayudan a representar diferentes actividades dentro de una sesión. Un segmento de actividad es un segmento de tiempo que cubre una sola actividad. Por ejemplo, si un usuario realiza una ejecución de una hora, puedes crear un segmento de actividad de tipo running (8) para la hora completa. Si un usuario ejecuta durante 25 minutos, se toma un descanso de 5 y luego se ejecuta durante otra media hora, puedes crear tres segmentos de actividad consecutivos de los tipos running, unknown y running, respectivamente.

Crear un segmento de actividad es lo mismo que agregar cualquier otro dato. Para crear segmentos de actividad, primero crea una fuente de datos de segmentos de actividad y, luego, crea un conjunto de datos y agrégale datos.

En el siguiente ejemplo, se crean tres segmentos (en ejecución, en reposo y en ejecución) en los mismos períodos que las lecturas de ritmo cardíaco, suponiendo que ya creaste una fuente de datos de segmento de actividad y que el ID de fuente de datos es "raw:com.google.activity.segment:1234567890:Ejemplo de ajuste:example-fit-hrm-1:123456":

Método HTTP

TRANSMITIR

Recurso

https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000

Cuerpo de la solicitud

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

Estos datos se agregan a una fuente de datos que se creó específicamente para controlar segmentos de actividad. Puedes crear una fuente de datos nueva para cada conjunto de segmentos, pero debes volver a usar una dedicada a un tipo particular de sesión, como la ejecución.

Las sesiones especifican un tipo de actividad, que debe coincidir con la actividad general en la que participa el usuario. Incluso si un usuario se toma un descanso mientras corre, el entrenamiento general sigue siendo una carrera. En general, el tipo de actividad de la sesión coincidirá con el tipo de segmento de actividad dominante.

Usa el tipo de actividad desconocido (4) para indicar que un usuario está en reposo, ya que es posible que no sepas lo que hace: puede estar quieto, estirar o beber agua, etc. Si sabes que el usuario no se mueve, puedes usar till (3).

Para obtener una lista detallada de los tipos de actividad, consulta Tipos de actividad.

Resumen

En este instructivo, creaste fuentes de datos para tipos de datos y segmentos de actividad, insertaste datos en la tienda de entrenamiento, creaste segmentos de actividad para representar las diferentes actividades que se realizan durante un entrenamiento y también insertaste una sesión que cubre todo el entrenamiento.

Google Fit asocia los datos que insertaste y cualquier otro dato disponible para ese intervalo de tiempo con una sesión que representa el entrenamiento del usuario.