Como gravar um treino

Este documento descreve como registrar um treino usando a API REST do Google Fit.

Etapa 1: configurar um projeto

Você precisa configurar um projeto no Console de APIs do Google e ativar o acesso à API REST do Google Fit, conforme descrito em Como começar.

Etapa 2: autenticar o app

Seu app precisa autenticar solicitações para a API Fitness usando um token de acesso. Para receber o token de acesso, o app inclui credenciais específicas do cliente e um escopo de acesso, conforme descrito em Autorizar solicitações.

Etapa 3: criar uma fonte de dados

Uma fonte de dados representa uma fonte de dados de sensores de um tipo específico. Todos os dados inseridos na loja de fitness precisam ser associados a uma fonte de dados. Você pode criar fontes de dados uma vez e reutilizá-las em sessões futuras.

Para criar uma fonte de dados, envie uma solicitação HTTP autenticada com estes parâmetros:

Método HTTP
POST
Recurso

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

O ID do usuário me se refere ao usuário cujo token de acesso autoriza a solicitação.

Corpo da solicitação
{
"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"
}

Essa solicitação cria uma fonte de dados que representa um monitor de frequência cardíaca que fornece dados de condicionamento físico do tipo com.google.heart_rate.bpm. Você precisa especificar o ID da fonte de dados pode ser qualquer valor. O ID da fonte de dados neste exemplo segue uma convenção de nomenclatura razoável que você pode adotar. O componente do dispositivo é opcional se os dados forem gerados somente por um app.

Se a solicitação for bem-sucedida, a resposta será um código de status 200 OK.

Para obter mais informações sobre fontes de dados, consulte a referência da API para a Users.dataSources.

Etapa 4: adicionar pontos de dados

Você usa conjuntos de dados para inserir pontos de dados na loja física. Um conjunto de dados é uma coleção de dados pontos de uma única fonte de dados, delimitados por tempo.

Para criar um conjunto de dados e adicionar pontos a ele, envie uma solicitação HTTP autenticada com estas parâmetros:

Método HTTP
PATCH
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

O URL inclui o ID da fonte de dados e os horários de início e término do conjunto de dados em nanossegundos.

Corpo da solicitação
{
"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 solicitação cria um conjunto de dados com três pontos de dados de frequência cardíaca em uma hora para os dados fonte na etapa anterior.

Se a solicitação for bem-sucedida, a resposta será um código de status 200 OK.

Para obter mais informações sobre conjuntos de dados, consulte a referência da API para a Users.dataSources.datasets.

Gerar carimbos de data/hora válidos

Os carimbos de data/hora do exemplo acima estão em nanossegundos. Para gerar carimbos de data/hora válidos, use script Python a seguir:

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

Etapa 5: criar uma sessão

Agora que você inseriu dados na loja de fitness, é possível inserir uma sessão para fornecer metadados adicionais para esse treino. As sessões representam um intervalo de tempo em que os usuários para realizar uma atividade física.

Para criar uma sessão para este treino, envie uma solicitação HTTP autenticada com estes parâmetros:

Método HTTP
PUT
Recurso

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

O sessionId é arbitrário e precisa ser exclusivo para todas as sessões associadas ao usuário autenticado.

Corpo da solicitação
{
"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
}

Escolha um nome de sessão que seja legível e descritivo, já que pode ser usado por outros apps para resumir a sessão. Os horários de início e término das sessões são em milissegundos, não em nanossegundos. Use o mesmo nome de pacote para suas sessões e fontes de dados. Isso torna os dados mais consistentes e garante que a atribuição de dados seja vinculada ao seu app.

O intervalo de tempo especificado nesta sessão abrange os dados de frequência cardíaca inseridos anteriormente, portanto O Google Fit associa esses pontos de dados a esta sessão.

Para mais informações sobre sessões, consulte a referência da API do recurso Users.sessions.

Etapa 6: criar segmentos de atividades

Os segmentos de atividades ajudam a representar diferentes atividades em uma sessão. Um segmento de atividade é um segmento de tempo que abrange uma única atividade. Por exemplo, se um usuário para uma corrida de uma hora, crie um segmento de atividade do tipo running (8) para o uma hora inteira. Se um usuário correr por 25 minutos, fizer uma pausa por 5 e depois correr por mais um hora, é possível criar três segmentos de atividade consecutivos dos tipos running, unknown e running, respectivamente.

Criar um segmento de atividade é o mesmo que adicionar qualquer outro ponto de dados. Para criar segmentos de atividades, primeiro crie uma fonte de dados de segmento de atividades, depois crie um conjunto de dados e adicione pontos de dados de segmento de atividades a ele.

O exemplo a seguir cria três segmentos (em execução, em repouso e em execução) nos mesmos períodos como as leituras de frequência cardíaca, supondo que você já criou um segmento de atividade fonte de dados e o ID dela seja "raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456":

Método HTTP
PATCH
Recurso
https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000
Corpo da solicitação
{
"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
    }
  ]
}
]
}

Esses pontos de dados do segmento de atividade são adicionados a uma fonte de dados criada especificamente para lidar com segmentos de atividade. Você pode criar uma nova fonte de dados para cada conjunto de segmentos, mas reutilize uma dedicada a um tipo específico de sessão, como a corrida.

As sessões especificam um tipo de atividade que deve corresponder à atividade geral em que o usuário está engajado. Mesmo que um usuário faça uma pausa durante a corrida, o treino ainda é uma corrida. Em geral, o tipo de atividade da sessão corresponde ao tipo de segmento de atividade dominante.

Use o tipo de atividade unknown (4) para indicar que um usuário está descansando, já que você pode não saber o que ele está fazendo: ele pode estar parado, se alongando, bebendo água e assim por diante. Se você sabe que o usuário não está se mexendo, você pode usar still (3).

Para uma lista detalhada dos tipos de atividade, consulte Tipos de atividade.

Resumo

Neste tutorial, você criou fontes de dados para tipos de dados e segmentos de atividade, inseriu pontos de dados no armazenamento de dados de condicionamento físico, criou segmentos de atividade para representar as diferentes atividades que ocorrem durante um treino e inseriu uma sessão que abrange todo o treino.

O Google Fit associa os dados que você inseriu e todos os outros dados disponíveis para esse intervalo de tempo com uma sessão que representa o treino do usuário.