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

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

שלב 1: הגדרת פרויקט

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

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

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

גוף הבקשה
{
"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
פוט
משאב

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

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

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

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

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

סיכום

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

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