איך מקליטים אימון כושר

מסמך זה מתאר איך לתעד אימון באמצעות ה-API ל-REST של כושר.

שלב 1: מגדירים פרויקט

עליכם להגדיר פרויקט במסוף Google API ולהפעיל את הגישה ל-Fitness REST API, כפי שמתואר בתחילת העבודה.

שלב 2: אימות האפליקציה

האפליקציה שלך צריכה לאמת בקשות ל-Fitness API באמצעות אסימון גישה. כדי לקבל את אסימון הגישה, האפליקציה כוללת פרטי כניסה ספציפיים ללקוח והיקף גישה, כפי שמתואר במאמר הרשאות בקשות.

שלב 3: יצירת מקור נתונים

מקור נתונים מייצג מקור של נתוני חיישנים מסוג מסוים. כל הנתונים שמוסיפים לחנות הכושר צריכים להיות משויכים למקור נתונים. אפשר ליצור מקורות נתונים פעם אחת ולהשתמש בהם שוב בהפעלות עתידיות.

כדי ליצור מקור נתונים, צריך לשלוח בקשת HTTP מאומתת עם הפרמטרים הבאים:

שיטת HTTP
POST
משאב

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

מזהה המשתמש של me מתייחס למשתמש שאסימון הגישה שלו מאשר את הבקשה.

גוף הבקשה
{
"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"
}

הבקשה הזו יוצרת מקור נתונים שמייצג מוניטור דופק שמספק נתוני כושר מסוג com.google.heart_rate.bpm. צריך לציין את המזהה של מקור הנתונים, והוא יכול להיות כל ערך. מזהה מקור הנתונים בדוגמה הזו תואם למוסכמה סבירה למתן שמות שאפשר לאמץ. רכיב המכשיר הוא אופציונלי אם הנתונים נוצרים רק על ידי אפליקציה.

אם הבקשה תתבצע בהצלחה, התגובה היא קוד סטטוס 200 OK.

למידע נוסף על מקורות נתונים, עיינו בחומרי העזר של ה-API של המשאב Users.dataSources.

שלב 4: מוסיפים נקודות על הגרף

אתם משתמשים במערכי נתונים כדי להוסיף נקודות על הגרף בחנות הכושר. מערך נתונים הוא אוסף של נקודות נתונים ממקור נתונים יחיד שמוגבל על ידי זמן.

כדי ליצור מערך נתונים ולהוסיף לו נקודות, צריך לשלוח בקשת HTTP מאומתת עם הפרמטרים הבאים:

שיטת HTTP
PATCH
משאב

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

כתובת ה-URL כוללת את מזהה מקור הנתונים ואת זמני ההתחלה והסיום של מערך הנתונים בננו-שניות.

גוף הבקשה
{
"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
    }
  ]
}
]
}

הבקשה הזו יוצרת מערך נתונים עם שלוש נקודות על נתוני הדופק בשעה למקור הנתונים בשלב הקודם.

אם הבקשה תתבצע בהצלחה, התגובה היא קוד סטטוס 200 OK.

למידע נוסף על מערכי נתונים, עיינו בחומר העזר בנושא API של המשאב Users.dataSources.datasets.

יצירה של חותמות זמן תקינות

חותמות הזמן בדוגמה שלמעלה הן בננו-שניות. כדי ליצור חותמות זמן תקינות אתם יכולים להשתמש בסקריפט הבא של 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))

שלב 5: יצירת סשן

עכשיו, אחרי שהכנסת נתונים לחנות הכושר, אפשר להוסיף סשן כדי לספק מטא-נתונים נוספים לגבי האימון הזה. סשנים מייצגים מרווח זמן שבמהלכו משתמשים מבצעים פעילות כושר.

כדי ליצור סשן לאימון הזה, צריך לשלוח בקשת HTTP מאומתת עם הפרמטרים הבאים:

שיטת HTTP
PUT
משאב

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

השדה sessionId הוא שרירותי, והוא חייב להיות ייחודי לכל הסשנים שמשויכים למשתמש המאומת.

גוף הבקשה
{
"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
}

בחרו שם תיאורי וקריא לבני אדם, מכיוון שאפליקציות אחרות עשויות להשתמש בו לסיכום הפגישה. זמני ההתחלה והסיום של סשנים הם באלפיות שנייה (לא בננו-שניות). להשתמש באותו שם חבילה בביקורים ובמקורות הנתונים. כך הנתונים יהיו עקביים יותר ותבטיחו ששיוך הנתונים יקשר בחזרה לאפליקציה.

מרווח הזמן שצוין בפעילות זו מכסה את נתוני הדופק שנוספו קודם, כך ש-Google Fit משייכת את נקודות הנתונים האלה לפעילות הזו.

למידע נוסף על סשנים, עיינו בחומר העזר בנושא API של המשאב Users.sessions.

שלב 6: יצירת פלחי פעילות

פלחי פעילות עוזרים לייצג פעילויות שונות במסגרת סשן. פלח פעילות הוא מקטע זמן שמכסה פעילות יחידה. לדוגמה, אם משתמש יוצא לריצה של שעה, אפשר ליצור פלח פעילות מסוג running (8) לכל השעה. אם משתמש רץ במשך 25 דקות, יוצא להפסקה למשך 5 ואז רץ עוד חצי שעה, אפשר ליצור 3 פלחי פעילות ברצף מהסוגים running, unknown ו-running בהתאמה.

היצירה של פלח פעילות זהה להוספה של כל נקודה אחרת על הגרף. כדי ליצור פלחי פעילות, קודם צריך ליצור מקור נתונים של פלח פעילות ואז ליצור מערך נתונים ולהוסיף לו נקודות נתונים של פלחי הפעילות.

הדוגמה הבאה יוצרת שלושה פלחים (ריצה, מנוחה וריצה) באותם פרקי זמן כמו נתוני הדופק, בהנחה שכבר יצרתם מקור נתונים של פלח פעילות ומזהה מקור הנתונים הוא "raw:com.google.activity.segment:1234567890:Example Fit:example-fit-hrm-1:123456":

שיטת HTTP
PATCH
משאב
https://www.googleapis.com/fitness/v1/users/me/dataSources/
raw:com.google.activity.segment:1234567890/datasets/1411053997000000000-1411057556000000000
גוף הבקשה
{
"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
    }
  ]
}
]
}

נקודות הנתונים של פלחי הפעילות האלו מתווספות למקור נתונים שנוצר במיוחד לצורך טיפול בפלחי פעילות. אפשר ליצור מקור נתונים חדש לכל קבוצה של פלחים, אבל צריך להשתמש שוב במקור שמיועד לסוג מסוים של סשן, למשל ריצה.

סשנים מציינים את סוג הפעילות, שאמור להתאים לפעילות הכוללת שבה המשתמש מעורב. גם אם משתמש יוצא להפסקה בזמן ריצה, האימון הכולל הוא עדיין ריצה. באופן כללי, סוג הפעילות בסשן יהיה תואם לסוג פלח הפעילות הדומיננטי.

כדאי להשתמש בסוג הפעילות unknown (4) על מנת לציין שהמשתמש נח, כי אולי אתם לא יודעים מה המשתמש עושה: יכול להיות שהוא דומם, מתמתח, שותה מים וכו'. אם יודעים שהמשתמש לא זז, אפשר להשתמש ב-still (3).

רשימה מפורטת של סוגי פעילות זמינה במאמר סוגי פעילות.

סיכום

במדריך הזה יצרתם מקורות נתונים לסוגי נתונים ולפלחי פעילות, הוספתם נקודות נתונים לחנות הכושר, יצרתם פלחי פעילות כדי לייצג את הפעילויות השונות שמתרחשות במהלך האימון. הזנתם סשן שמכסה את כל האימון.

Google Fit משייכת את הנתונים שהוספתם וכל מידע אחר שזמין לאותו מרווח זמן לסשן שמייצג את האימון של המשתמש.