Come registrare un allenamento

Questo documento descrive come registrare un esercizio utilizzando l'API REST Fitness.

Passaggio 1: configura un progetto

Devi configurare un progetto nella console API di Google e attivare l'accesso all'API REST Fitness, come descritto in Guida introduttiva.

Passaggio 2: autentica l'app

La tua app deve autenticare le richieste all'API Fitness utilizzando un token di accesso. Per ottenere il token di accesso, la tua app include credenziali specifiche del client e un ambito di accesso, come descritto in Autorizzazione delle richieste.

Passaggio 3: crea un'origine dati

Un'origine dati rappresenta una sorgente di dati di sensori di un determinato tipo. Tutti i dati inseriti nel negozio di fitness devono essere associati a un'origine dati. Puoi creare le origini dati una sola volta e riutilizzarle per sessioni future.

Per creare un'origine dati, invia una richiesta HTTP autenticata con i seguenti parametri:

Metodo HTTP
POST
Risorsa

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

L'ID utente me si riferisce all'utente il cui token di accesso autorizza la richiesta.

Corpo della richiesta
{
"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"
}

Questa richiesta crea un'origine dati che rappresenta un rilevatore della frequenza cardiaca che fornisce dati sul fitness di tipo com.google.heart_rate.bpm. Devi specificare l'ID dell'origine dati e può essere qualsiasi valore. L'ID origine dati in questo esempio segue una convenzione di denominazione ragionevole che puoi adottare. Il componente del dispositivo è facoltativo se i dati sono generati soltanto da un'app.

Se la richiesta ha esito positivo, la risposta sarà un codice di stato 200 OK.

Per ulteriori informazioni sulle origini dati, consulta il riferimento API per la risorsa Users.dataSources.

Passaggio 4: aggiungi punti dati

Si utilizzano i set di dati per inserire punti dati nel negozio di fitness. Un set di dati è una raccolta di punti dati da una singola origine dati vincolata dal tempo.

Per creare un set di dati e aggiungere punti, invia una richiesta HTTP autenticata con questi parametri:

Metodo HTTP
PATCH
Risorsa

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 include l'ID origine dati e l'ora di inizio e di fine del set di dati in nanosecondi.

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

Questa richiesta crea un set di dati con tre punti dati della frequenza cardiaca in un'ora per l'origine dati nel passaggio precedente.

Se la richiesta ha esito positivo, la risposta sarà un codice di stato 200 OK.

Per maggiori informazioni sui set di dati, consulta il riferimento API per la risorsa Users.dataSources.datasets.

Genera timestamp validi

I timestamp nell'esempio precedente sono in nanosecondi. Per generare timestamp validi, puoi usare il seguente script 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))

Passaggio 5: crea una sessione

Ora che hai inserito i dati nel negozio di fitness, puoi inserire una sessione per fornire metadati aggiuntivi per questo esercizio. Le sessioni rappresentano un intervallo di tempo durante il quale gli utenti eseguono un'attività fisica.

Per creare una sessione per questo esercizio, invia una richiesta HTTP autenticata con questi parametri:

Metodo HTTP
PUT
Risorsa

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

Il valore sessionId è arbitrario e deve essere univoco per tutte le sessioni associate all'utente autenticato.

Corpo della richiesta
{
"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
}

Scegli un nome per la sessione leggibile e descrittivo, poiché potrebbe essere utilizzato da altre app per riassumere la sessione. L'ora di inizio e l'ora di fine delle sessioni sono espresse in millisecondi (non in nanosecondi). Utilizza lo stesso nome di pacchetto per le sessioni e le origini dati. In questo modo i dati saranno più coerenti e l'attribuzione dei dati sarà collegata nuovamente alla tua app.

L'intervallo di tempo specificato in questa sessione copre i dati sulla frequenza cardiaca inseriti in precedenza, pertanto Google Fit associa questi punti dati a questa sessione.

Per ulteriori informazioni sulle sessioni, consulta il riferimento API per la risorsa Users.sessions.

Passaggio 6. Crea segmenti di attività

I segmenti attività consentono di rappresentare diverse attività all'interno di una sessione. Un segmento attività è un segmento di tempo che copre una singola attività. Ad esempio, se un utente compie un'ora di corsa, puoi creare un segmento di attività di tipo running (8) per l'intera ora. Se un utente è in esecuzione per 25 minuti, si prende una pausa per 5 e poi continua a funzionare per un'altra mezz'ora, puoi creare tre segmenti di attività consecutivi di tipo running, unknown e running rispettivamente.

La creazione di un segmento di attività equivale all'aggiunta di qualsiasi altro punto dati. Per creare segmenti di attività, devi prima creare un'origine dati per il segmento di attività, poi creare un set di dati a cui aggiungere punti dati per il segmento di attività.

L'esempio seguente crea tre segmenti (corsa, a riposo e corsa) negli stessi periodi di tempo delle letture della frequenza cardiaca, supponendo che tu abbia già creato un'origine dati per il segmento di attività e che l'ID dell'origine dati sia "raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456":

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

Questi punti dati dei segmenti di attività vengono aggiunti a un'origine dati creata appositamente per gestire segmenti di attività. Potresti creare una nuova origine dati per ogni insieme di segmenti, ma devi riutilizzarne una dedicata a un determinato tipo di sessione, ad esempio quella in esecuzione.

Le sessioni specificano un tipo di attività, che deve corrispondere all'attività complessiva in cui l'utente è coinvolto. Anche se un utente fa una pausa durante la corsa, l'esercizio generale è ancora una corsa. In generale, il tipo di attività per la sessione corrisponderà al tipo di segmento di attività dominante.

Utilizza il tipo di attività unknown (4) per indicare che un utente sta riposando, perché potresti non sapere cosa sta facendo: potrebbe essere fermo o fa stretching mentre beve acqua e così via. Se sai che l'utente non si sta muovendo, puoi utilizzare still (3).

Per un elenco dettagliato dei tipi di attività, vedi Tipi di attività.

Riepilogo

In questo tutorial hai creato origini dati per tipi di dati e segmenti di attività, hai inserito punti dati nel negozio di fitness, hai creato segmenti di attività per rappresentare le diverse attività svolte durante un esercizio e hai inserito una sessione che copre l'intero esercizio.

Google Fit associa i dati che hai inserito e qualsiasi altro dato disponibile per quell'intervallo di tempo a una sessione che rappresenta l'esercizio dell'utente.