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

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

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

عليك إعداد مشروع في وحدة تحكّم واجهة برمجة تطبيقات Google وتفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات 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.

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

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

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

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

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

ملخّص

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

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