كيفية تسجيل تمرين

يوضّح هذا المستند كيفية تسجيل تمرين باستخدام واجهة برمجة تطبيقات Fitness REST.

الخطوة 1: إعداد مشروع

يجب إعداد مشروع في وحدة التحكم في واجهة Google API وتفعيل إمكانية الوصول إلى واجهة برمجة تطبيقات Fitbit REST، كما هو موضّح في البدء.

الخطوة 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.

لمزيد من المعلومات حول مصادر البيانات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات الخاص بمورد 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.

للمزيد من المعلومات حول مجموعات البيانات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات الخاص بمورد 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 نقاط البيانات هذه بهذه الجلسة.

للمزيد من المعلومات عن الجلسات، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات الخاص بمورد Users.sessions.

الخطوة 6: إنشاء شرائح النشاط

تساعدك شرائح النشاط على تمثيل أنشطة مختلفة ضمن الجلسة. شريحة النشاط هي شريحة زمنية تغطي نشاطًا واحدًا. على سبيل المثال، إذا بدأ المستخدم الجري لمدة ساعة واحدة، يمكنك إنشاء شريحة نشاط من النوع running (8) للساعة بأكملها. إذا ركض المستخدم لمدة 25 دقيقة، ثم أخذ استراحة لمدة 5 دقائق، ثم نفذ نصف ساعة أخرى، يمكنك إنشاء ثلاث شرائح نشاط متتالية من الأنواع running وunknown وrunning على التوالي.

إنشاء شريحة نشاط مماثل لإضافة أي نقطة بيانات أخرى. لإنشاء شرائح النشاط، عليك أولاً إنشاء مصدر بيانات لشرائح النشاط، ثم إنشاء مجموعة بيانات وإضافة نقاط بيانات شريحة النشاط إليها.

ينشئ المثال التالي ثلاث شرائح (الجري والراحة والركض) في نفس الإطارات الزمنية مثل قراءات معدل ضربات القلب، على افتراض أنك أنشأت بالفعل مصدر بيانات قطاع من النشاط وأن رقم تعريف مصدر البيانات هو "raw:com.google.activity.segment:1234567890:مثال 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
    }
  ]
}
]
}

تتم إضافة نقاط بيانات شرائح النشاط هذه إلى مصدر بيانات تم إنشاؤه خصيصًا للتعامل مع شرائح النشاط. يمكنك إنشاء مصدر بيانات جديد لكل مجموعة من الشرائح، لكن عليك إعادة استخدام مصدر بيانات مخصّص لنوع معيّن من الجلسات، مثل الجري.

تحدد الجلسات نوع النشاط، والذي يجب أن يتطابق مع النشاط العام الذي يشارك فيه المستخدم. حتى إذا أخذ المستخدم استراحة أثناء الجري، فلا يزال التمرين الكلي جريًا. بشكل عام، سيتطابق نوع النشاط للجلسة مع نوع شريحة النشاط السائد.

استخدِم نوع النشاط غير معروف (4) للإشارة إلى أنّ المستخدم يستريح، لأنّك قد لا تعرف ما يفعله المستخدم: قد يكون لا يزال ساكنًا أو يمارس رياضة التمدد أو شرب الماء أو غير ذلك. إذا كنت تعرف أنّ المستخدم لا يتحرك، يمكنك استخدام الخيار لا يزال (3).

للحصول على قائمة مفصّلة بأنواع الأنشطة، يمكنك الاطّلاع على أنواع الأنشطة.

ملخّص

في هذا البرنامج التعليمي، أنشأت مصادر بيانات لأنواع البيانات وقطاعات الأنشطة، وأدرجت نقاط بيانات في مخزن بيانات اللياقة البدنية، وأنشأت شرائح نشاط لتمثيل الأنشطة المختلفة التي تجري أثناء التمرين، وأدرجت جلسة تغطي التمرين بالكامل.

يربط Google Fit البيانات التي أدرجتها وأي بيانات أخرى متاحة لتلك الفترة الزمنية بالجلسة التي تمثّل تمارين المستخدم.