نقاط النهاية

تقدّم هذه الصفحة نظرة عامة على اصطلاحات REST API، بالإضافة إلى فهرس لمَهام Google Health API الشائعة وأمثلة على كلّ منها.

اتفاقيات REST API

تتّبع Google Health API معايير مقترحات تحسين Google API (AIP)، وتحديدًا AIP-127 (تحويل ترميز HTTP وgRPC) وAIP-131 إلى AIP-135 (الطرق العادية). تحدّد هذه المعايير كيفية ربط البيانات من رسالة بروتوكول بطلب HTTP.

مَعلمات طلب البحث

يتم استخدام معلمات طلب البحث عندما تكون البيانات جزءًا من عنوان URL. يُستخدم هذا بشكل أساسي لطلبات GET (جلب مورد) أو طلبات LIST (الفلترة/تقسيم الصفحات)، ولكنه يُستخدم أيضًا لعمليات DELETE.

  • الموضع: تتم إضافتها إلى عنوان URL بعد ?.
  • البنية: أزواج المفتاح/القيمة مفصولة بـ &.
  • الربط: يتم ربط كل حقل في رسالة الطلب ليس جزءًا من نموذج مسار عنوان URL بمَعلمة طلب بحث.
  • الاستخدام الأمثل: الأنواع البسيطة (السلاسل والأعداد الصحيحة والتعدادات) والحقول المتكرّرة.

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

مثال على البنية:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

نص الطلب

يتم استخدام نص الطلب عندما تعدّل البيانات حالة مورد أو عندما تكون كبيرة جدًا بالنسبة إلى عنوان URL. عادةً ما يكون النص تمثيلاً بتنسيق JSON للمورد نفسه. يُستخدم عادةً لعمليات POST وPATCH وPUT.

  • الموضع: داخل حمولة HTTP (غير مرئي في عنوان URL).
  • البنية: يتم تنسيقها كعنصر JSON.
  • الربط: يتم تحديده في التعليق التوضيحي google.api.http.
    • تعني السمة body: "*" أنّ الرسالة بأكملها هي نص الرسالة.
    • body: "resource_name" means only a specific field in the proto is the body.
  • الاستخدام الأمثل: الكائنات المعقّدة والرسائل المتداخلة والبيانات الحسّاسة

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

مثال على البنية:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

الحالة المختلطة

في طريقة Update المتوافقة مع AIP-134 أو عملية PATCH، يتم استخدام كليهما. يحتوي عنوان URL على اسم المورد، ويحتوي النص على بيانات المورد المعدَّلة، وتحدّد مَعلمة طلب البحث (عادةً update_mask) الحقول التي يجب تغييرها.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

نظرة سريعة على الاختلافات الرئيسية

الميزة معلمات طلب البحث نص الطلب
إرشادات AIP تُستخدَم لعمليات البحث والفلترة والقراءة. يُستخدَم لعمليات الكتابة.
مستوى العرض تظهر في سجلّ المتصفّح وسجلّات الخادم. مخفي من عنوان URL
التعقيد تقتصر على البُنى المسطّحة أو المتكرّرة. يتيح استخدام عناصر JSON المتداخلة بشكل كبير.
الترميز يجب أن يكون عنوان URL مرمَّزًا (على سبيل المثال، تصبح المسافات %20). ترميز JSON عادي

التواريخ

يتم عرض جميع التواريخ في Google Health API بالتنسيق YYYY-MM-DD. تتوافق Nutrition API مع معيار ISO-8601 لقيم التاريخ مع الشروط التالية:

  • سنة من 4 أرقام YYYY
  • قيم السنة ضمن النطاق من 0000 إلى 9999
  • لا يتم فرض قيود على تاريخ البدء وفقًا لمعيار ISO-8601 أو أي معيار آخر

العناوين

يتطلب تنفيذ نقاط نهاية Google Health API استخدام العناوين ورمز الدخول المناسبين. يُنصح باستخدام العنوان التالي لكل من طلبات GET وPOST:

Authorization: Bearer access-token
Accept: application/json

فهرس مهام واجهة برمجة التطبيقات

يقدّم هذا القسم فهرسًا لمهام Google Health API الشائعة وأمثلة على كل منها.

الحصول على رقم تعريف المستخدم في Fitbit أو Google

بعد أن يمنح المستخدم موافقته من خلال Google OAuth 2.0، لن يتضمّن الرمز المميّز للاستجابة رقم تعريف المستخدم في Fitbit أو Google. يجب طلب نقطة النهاية getIdentity فورًا بعد تبادل رمز التفويض لاسترداد كل من legacyUserId وhealthUserId والتحقّق من أنّ حساب المستخدم على Google مرتبط بـ Google Health. إذا لم يكن الحساب مرتبطًا بعد، ستعرض واجهة برمجة التطبيقات getIdentity القيمة 400 Bad Request مع السبب ACCOUNT_NOT_LINKED (يُرجى الاطّلاع على التعامل مع حسابات Google غير المرتبطة).

على سبيل المثال:

طلب

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

الردّ (200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

الردّ (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

الحصول على بيانات مفصّلة أو بيانات على مدار اليوم يتم جمعها خلال يوم واحد

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

على سبيل المثال:

طلب

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

الردّ

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

الحصول على عرض تسوية لبيانات الفواصل الزمنية

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

للحصول على معلومات أساسية حول سبب إنشاء الأجهزة المتصلة لفترات متداخلة ومقارنة تشغيلية بين list وreconcile، يُرجى الاطّلاع على دليل إدارة البيانات.

يقارن المثال التالي بين استجابة list (التي تعرض كلا السجلَّين المتداخلَين) وreconcile (التي تحلّ التعارض من خلال عرض السجلّ الموثوق) لمستخدم لديه جلستان تدريبيتان متداخلتان:

قائمة أولية

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

تمت التسوية

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

تعمل التسوية على حلّ الجلسات المتعارضة من خلال إزالة التكرار واختيار السجلّ الموثوق به بدلاً من إنشاء اتحاد زمني اصطناعي (مثل 11:00:00Z إلى 11:50:00Z). تعرض الاستجابة التي تمت تسويتها نقطة البيانات الفائزة (7797422996486764704) مع الفاصل الزمني الأصلي المسجَّل (11:20:00Z إلى 11:50:00Z)، مع الحفاظ على سلامة القياسات والمقاييس التي تم قياسها في تلك الجلسة.

تصفية البيانات

لاسترداد مجموعات فرعية محدّدة من سجلّات نقاط البيانات التي تتطابق مع معايير مثل فترة زمنية أو تاريخ أو وقت رصد، استخدِم نقطة النهاية list أو reconcile مع مَعلمة filter.

للحصول على إرشادات مفصّلة وقواعد التنسيق وأخطاء التحقّق وأمثلة على طلبات البحث، يُرجى الاطّلاع على دليل فلترة البيانات.

الفلترة حسب مجموعة مصادر البيانات

لعزل البيانات أو تجميعها من أنواع معيّنة من المصادر (على سبيل المثال، الأجهزة المادية القابلة للارتداء مقابل الإدخالات اليدوية)، استخدِم المَعلمة dataSourceFamily.

للحصول على إرشادات مفصّلة ومعرفة العائلات المتوافقة والاطّلاع على أمثلة على الطلبات والردود لـ reconcile وrollUp وdailyRollUp، يُرجى الاطّلاع على الفلترة حسب عائلة مصدر البيانات في دليل فلترة البيانات.

فلترة البيانات حسب وقت بدء مدني لفترة زمنية

استخدِم نقطة النهاية list مع مَعلمة filter لفلترة البيانات حسب التوقيت المدني أو فترة زمنية.

على سبيل المثال:

طلب

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

الردّ

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

فلترة البيانات حسب الوقت الفعلي لملاحظة العيّنة

استخدِم نقطة النهاية list مع مَعلمة filter لفلترة البيانات حسب الوقت الفعلي لملاحظة العيّنة.

على سبيل المثال:

طلب

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

الردّ

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

الفلترة والتجميع حسب مجموعة مصادر البيانات

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

تتوافق نقاط النهاية reconcile وrollUp وdailyRollUp مع المَعلمة dataSourceFamily. تعتمد آلية تمرير المعرّفات على نقطة النهاية:

نقطة النهاية (طريقة HTTP) الآلية
reconcile (GET) مرِّر dataSourceFamily كمَعلمة طلب بحث في عنوان URL.
rollUp (POST) مرِّر dataSourceFamily كحقل في نص طلب JSON.
dailyRollUp (POST) مرِّر dataSourceFamily كحقل في نص طلب JSON.

مجموعات مصادر البيانات المتوافقة

يوضّح الجدول التالي قيم dataSourceFamily المسموح بها:

Option الوصف
users/me/dataSourceFamilies/all-sources القيمة التلقائية تعرض هذه السمة نقاط البيانات التي تمت تسويتها في جميع مصادر بيانات الطرف الأول (1P) والطرف الثالث (3P) المسجّلة. سيتم عرض بيانات التطبيقات الخارجية من خلال هذا الخيار (مثل الخطوات التي تم تتبُّعها باستخدام الساعة الذكية + الخطوات التي تم تتبُّعها باستخدام التطبيقات الخارجية + الخطوات التي تم تتبُّعها باستخدام الهاتف الجوّال + الخطوات التي تم تتبُّعها يدويًا).
users/me/dataSourceFamilies/google-wearables تشمل البيانات التي تسجّلها أجهزة التتبُّع من Google وFitbit (مثل أجهزة التتبُّع القابلة للارتداء من Fitbit وساعة Pixel Watch). لا يشمل ذلك البيانات المسجَّلة يدويًا والبيانات المقدَّرة من الهاتف. استخدِم هذا الخيار عندما يتطلّب التكامل بيانات قياس عن بُعد أولية لأدوات الاستشعار يتم تسجيلها مباشرةً من خلال الأجهزة القابلة للارتداء.
users/me/dataSourceFamilies/google-sources ويشمل ذلك مصادر الطرف الأول من Google وFitbit. ويشمل ذلك سجلّات أجهزة التتبُّع المادية والبيانات من Health Connect وأي إدخالات يدوية يتم تسجيلها من خلال تطبيقات الطرف الأول (مثل تطبيق Fitbit أو Google Fit).

للحصول على مصدر بيانات تمّت تسويته من مجموعة مصادر بيانات معيّنة، يمكنك استدعاء نقطة النهاية reconcile باستخدام مَعلمة طلب البحث dataSourceFamily.

على سبيل المثال، يجلب طلب الاسترداد باستخدام GET التالي بيانات النوم التي سجّلها جهاز التتبُّع لليوم التالي لـ ‎2026-03-03:

طلب

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

الردّ

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

لتجميع نقاط البيانات على مدار حجم نافذة معيّن يقتصر على مجموعة مصادر بيانات معيّنة، يمكنك استدعاء نقطة النهاية rollUp وتمرير الحقل dataSourceFamily في نص طلب JSON.

يستعلم طلب POST التالي عن عدد خطوات المشي خلال اليوم على فترات زمنية كل ساعة (3600s)، ويتم تجميعها حصريًا من الأجهزة القابلة للارتداء:

طلب

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

الردّ

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

لتجميع نقاط البيانات اليومية لعائلة مصدر معيّنة، يمكنك استدعاء نقطة النهاية dailyRollUp وتمرير الحقل dataSourceFamily في نص الطلب.

على سبيل المثال، يحتسب الطلب التالي الإحصاءات اليومية لخطوات المستخدم، بما في ذلك جميع مصادر Google وFitbit التابعة للطرف الأول (الأجهزة القابلة للارتداء والإدخالات اليدوية):

طلب

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

الردّ

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

تجميع نقاط البيانات على مدار فترة زمنية

استخدِم نقطة النهاية rollUp لعرض مجموع نقاط البيانات استنادًا إلى نافذة بالثواني (windowSize)، على مدار نطاق datetime في الوقت الفعلي للمستخدم (بالتوقيت العالمي المنسق).

عند طلب نقطة النهاية rollUp، يجب تقديم نص الطلب الذي يمثّل الوقت المطلوب للإغلاق والفتح range وwindowSize (على الأقل "1s"). للحصول على إرشادات مفصّلة حول متطلبات windowSize ومواءمة دقة التخزين وقواعد التجميع وأمثلة على الطلبات والردود، يُرجى الاطّلاع على التجميع على فترات زمنية فعلية في دليل البيانات المجمّعة.

تجميع البيانات على مدار يوم واحد أو عدة أيام

استخدِم نقطة النهاية dailyRollUp لتجميع البيانات على مدار يوم واحد أو عدة أيام (windowSizeDays). قدِّم الوقت المدني المغلق والمفتوح range للفترة الزمنية المطلوبة في نص الطلب. استنادًا إلى نوع البيانات، تعرض نقطة النهاية إما المجموع أو المتوسط لكل نافذة.

للاطّلاع على تفاصيل حول سلوك التجميع اليومي، والتعامل مع التوقيت المدني، وحدود النطاق لكل طلب، وأمثلة على الطلبات والردود، يُرجى الاطّلاع على التجميع على مدار أيام التقويم في دليل البيانات المجمّعة.

تعديل البيانات الصحية لمستخدم

استخدِم نقطة النهاية patch لتعديل البيانات الصحية للمستخدم.

تعدّل نقطة النهاية patch سجلاً حاليًا استنادًا إلى المعرّف المحدّد في عنوان URL للطلب. يُرجى تقديم معرّف نقطة بيانات تم إدراجها سابقًا. تستبدل واجهة برمجة التطبيقات السجلّ الحالي.

يمكن أيضًا تعديل الطوابع الزمنية لفترة نقطة البيانات (startTime وendTime) من قِبل مالك السجلّ أو نشرها من منصات المصدر مثل Health Connect. لمعرفة التفاصيل حول قابلية تعديل الطابع الزمني، يُرجى الاطّلاع على دليل إدارة البيانات. للاطّلاع على مثال على تعديل الطوابع الزمنية للفواصل الزمنية، يُرجى مراجعة تعديل الطوابع الزمنية للفواصل الزمنية للبيانات الحالية.

حالات استخدام معرّف نقطة البيانات

يُعدّ معرّف نقطة البيانات ضروريًا في السيناريوهات التالية:

  • التعديلات المستهدَفة: لتعديل قياس معيّن، يجب تقديم معرّفه في طلب patch.
  • عمليات الحذف: يتيح الاحتفاظ بالمعرّف لتطبيقك حذف السجلّ لاحقًا باستخدام نقطة النهاية batchDelete.

في ما يلي مثال على مستخدم يعدّل قراءة نسبة الدهون بالجسم على ميزان يُسمى "HumanScale" من شركة "Scales R Us". قراءة نسبة الدهون الجديدة في الجسم للمستخدم هي %20 في ‎2026-03-10:

طلب

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

تعديل الطوابع الزمنية للفواصل الزمنية للبيانات الحالية

لتعديل الطوابع الزمنية للفواصل الزمنية (startTime وendTime في حمولات REST JSON، أو start_time وend_time في gRPC) لنقطة بيانات حالية، أرسِل طلب PATCH إلى معرّف الموارد المنتظم (URI) لمورد نقطة البيانات. يمكن فقط للمنشئ الأصلي أو مالك السجل تعديل حقوله. لا يمكن للتطبيقات تعديل نقاط البيانات التي لم تنشئها.

للحصول على معلومات أساسية حول قابلية تغيير الطابع الزمني والتحديثات الواردة من Health Connect وآثار التخزين المؤقت، يُرجى الاطّلاع على دليل إدارة البيانات.

يوضّح المثال التالي تطبيقًا مالكًا يعدّل الطوابع الزمنية للفواصل الزمنية لسجلّ ترطيب حالي باستخدام نقطة النهاية patch:

طلب

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

تسجيل صنف طعام

لتسجيل صنف طعام، أرسِل طلب POST إلى نقطة النهاية nutrition-log dataPoints. يحتوي نص الطلب على DataPoint مع عنصر nutritionLog. لمزيد من المعلومات، يُرجى الاطّلاع على دليل التغذية.

على سبيل المثال:

طلب

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

حذف البيانات الصحية للمستخدم

استخدِم طريقة batchDelete لحذف مصفوفة من بيانات تطبيق Fitbit الخاصة بالمستخدم.

إليك مثال على مستخدم سجّل سابقًا نسبة الدهون بالجسم على ميزان، ولكنه يريد حذف السجلّ. باستخدام user-id وdata-point-id من إجراء الإدراج الأصلي:

طلب

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

العثور على معلومات الجهاز

استخدِم نقطة النهاية list لاسترداد قائمة الأجهزة المقترنة بحساب مستخدم. ويشمل ذلك معلومات طراز الجهاز (deviceVersion) وآخر مرة تمت فيها مزامنته مع تطبيق Google Health للأجهزة الجوّالة (lastSyncTime).

تُعدّ معلومات إعدادات القائمة والمزامنة مفيدة لتحديد مشاكل المزامنة وحلّها أو جلب البيانات السابقة منذ آخر عملية مزامنة.

على سبيل المثال:

طلب

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

الردّ

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

الاستعلام عن البيانات السابقة

من المزايا الأساسية لواجهة Google Health API هي إمكانية تتبُّع أداء المستخدم ومراقبة مؤشراته الحيوية على مدار فترات زمنية طويلة. يمكنك الاستعلام عن بيانات المستخدم منذ بداية تسجيلها، إذ لا تفرض واجهة برمجة التطبيقات أي قيود على كمية البيانات السابقة التي يمكن لتطبيقك استخدامها.

ومع ذلك، لا تزال طلبات البحث عن البيانات السابقة تخضع لحدود المعدّل العادية. لإدارة استقرار النظام ومنع الحمولات الزائدة، تستخدم Google Health API ميزة التقسيم التلقائي للصفحات مع أحجام صفحات خاصة بنقاط النهاية. يُرجى ملاحظة الحدود والسلوكيات التالية:

  • تقسيم البيانات تلقائيًا على عدّة صفحات: إذا طلبت بيانات تغطي فترة زمنية طويلة، ستعرض واجهة برمجة التطبيقات الصفحة الأولى من النتائج فقط، وذلك حتى الحد الأقصى لحجم الصفحة لنقطة النهاية هذه، بالإضافة إلى nextPageToken. يجب استخدام nextPageToken لطلب الصفحات اللاحقة.
  • أحجام الصفحات المتغيّرة: تعتمد حدود الحد الأقصى على نقطة النهاية ونوع البيانات. بالنسبة إلى معظم أنواع البيانات، يبلغ الحد الأقصى لأحجام الصفحات 10,000. ومع ذلك، بالنسبة إلى أنواع معيّنة من البيانات، مثل exercise وsleep، يتم تحديد الحد الأقصى لحجم الصفحة التلقائي بـ 25. على سبيل المثال، إذا طلب أحد العملاء جميع بيانات النوم لآخر 10 سنوات، ستعرض واجهة برمجة التطبيقات 25 جلسة نوم فقط في الصفحة الأولى.
  • القيود المفروضة على النطاق الزمني لعمليات التجميع: بالنسبة إلى نقاط النهاية الخاصة بتجميع البيانات ودمجها (مثل rollUp وdailyRollUp)، يتم فرض قيود على النطاقات الزمنية لطلبات البحث استنادًا إلى نوع البيانات:
    • الحد الأقصى للنطاق هو 14 يومًا لكل من calories-in-heart-rate-zone وheart-rate وactive-minutes وtotal-calories.
    • نطاق أقصى يبلغ 90 يومًا لجميع أنواع بيانات الإحصاءات المجمّعة الأخرى

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

لضمان الأداء الأمثل وتجنُّب أخطاء واجهة برمجة التطبيقات، اتّبِع هذه الإرشادات عند الاستعلام عن البيانات السابقة:

مزامنة البيانات على مراحل (التشغيل على الساخن مقابل التشغيل على البارد)

  • التحميل الأوّلي "الساخن": يمكنك جلب وعرض بيانات آخر 7 إلى 14 يومًا فقط خلال تسلسل التحميل الأساسي. يضمن ذلك أن يرى المستخدمون البيانات على الفور بدون انتظار طلبات البحث الطويلة.
  • التحميل "البارد" في الخلفية: يمكنك تفويض استرداد البيانات السابقة إلى قائمة انتظار غير متزامنة ذات أولوية أقل أو عملية في الخلفية بعد عرض واجهة المستخدم الأساسية.

تقسيم طلبات البحث للتجميع

  • بما أنّ نقاط النهاية الخاصة بالتجميع والتجميع اليومي تفرض حدًا أقصى للنطاق الزمني (14 أو 90 يومًا حسب نوع البيانات)، عليك تقسيم طلبات البحث الكبيرة الخاصة بالتجميعات السابقة إلى فترات زمنية أصغر ومتسلسلة ضمن هذه الحدود.
  • يمكنك تجميع هذه الطلبات الفرعية أو ترتيبها بشكل آمن للامتثال لحدود التزامن والحفاظ على مؤشرات تقدّم واجهة المستخدم بشكل ثابت.

الاستفادة من عمليات التجميع المُسبقة

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

معالجة الأخطاء بمرونة (عمليات إعادة المحاولة الذكية)

  • يجب تنفيذ معالجة صارمة لتأجيل المحاولة بشكل أسي عند مواجهة حدود معدّل الطلبات (429 Too Many Requests) ومهلة بوابة الخادم (504 Gateway Timeout). لا تُعِد محاولة إرسال حمولات كبيرة وفاشلة على الفور. تؤدي عمليات إعادة المحاولة الفورية إلى زيادة ازدحام الخلفية وتفاقم تدهور النظام.
السابق
مكتبات العملاء
التالي
الفلاتر