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

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

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

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

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