Como gravar um treino

Este documento descreve como registrar um treino usando a API REST Fitness.

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 seu app

Seu app precisa autenticar solicitações à 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 Como autorizar solicitações.

Etapa 3: criar uma fonte de dados

Uma fonte de dados representa uma fonte de dados do sensor de um tipo específico. Todos os dados inseridos no armazenamento de condicionamento físico precisam estar associados a uma fonte de dados. Você pode criar fontes de dados uma vez e reutilizá-las para sessões futuras.

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

Método HTTP
POST
Resource

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

O ID de 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. É necessário especificar o ID da fonte de dados, que pode ser qualquer valor. O ID da fonte de dados neste exemplo segue uma convenção de nomenclatura razoável que pode ser adotada. O componente do dispositivo é opcional se os dados forem gerados apenas por um app.

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

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

Etapa 4: adicionar pontos de dados

Você usa conjuntos de dados para inserir pontos de dados no armazenamento de condicionamento físico. Um conjunto de dados é uma coleção de pontos de uma única fonte de dados limitada por tempo.

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

Método HTTP
PATCH
Resource

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

Essa solicitação cria um conjunto de dados com três pontos de dados de frequência cardíaca em uma hora para a fonte de dados da etapa anterior.

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

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

Gerar carimbos de data/hora válidos

Os carimbos de data/hora no exemplo acima estão em nanossegundos. Para gerar carimbos de data/hora válidos, use o 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 no armazenamento de dados de condicionamento físico, insira uma sessão para fornecer outros metadados a este treino. As sessões representam um intervalo de tempo em que os usuários realizam uma atividade de condicionamento físico.

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

Método HTTP
PUT
Resource

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 de volta 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 à sessão.

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

Etapa 6: criar segmentos de atividade

Os segmentos de atividade ajudam você 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 fizer uma corrida de uma hora, você poderá criar um segmento de atividade do tipo running (8) para a hora inteira. Se um usuário correr por 25 minutos, fizer uma pausa por 5 e depois correr por mais meia hora, você poderá 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 atividade, primeiro crie uma fonte de dados de segmento de atividade. Em seguida, crie um conjunto de dados e adicione pontos de dados de segmentos de atividade a ele.

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

Método HTTP
PATCH
Resource
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 de segmentos de atividade são adicionados a uma fonte de dados criada especificamente para processar segmentos de atividade. É possível criar uma nova fonte de dados para cada conjunto de segmentos, mas reutilize uma dedicada a um tipo específico de sessão, como em execução.

As sessões especificam um tipo de atividade, que deve corresponder à atividade geral com que o usuário está engajado. Mesmo que um usuário faça uma pausa durante a corrida, o treino geral ainda será 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, caso você não saiba o que ele está fazendo: ele pode estar imóvel ou se alongando, consumindo água e assim por diante. Se você saber que o usuário não está em movimento, use ainda (3).

Para conferir 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 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 outros dados disponíveis para esse intervalo de tempo a uma sessão que representa o treino do usuário.