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

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

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

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

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

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

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

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

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

שיטת HTTP
פרסום
משאב

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
תיקון
משאב

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, ואז רץ למשך מחצית נוספת לשעה, אפשר ליצור שלושה פלחי פעילות עוקבים מסוגים running, unknown ו-running בהתאמה.

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

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

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