ابدأ عملية نقل البيانات أو تطوير تطبيق جديد اليوم. يمكن للتطبيقات التي تضم أكثر من 100 مستخدم إرسال طلبات التحقّق اعتبارًا من 30 آذار (مارس).

لضمان توفير تجربة سلسة للمستخدمين، ننصحك بالانتظار حتى نهاية مايو 2026 لإطلاق عملية الدمج رسميًا بما يتوافق مع إيقاف حسابات Fitbit القديمة نهائيًا. يُرجى العِلم أنّه من الآن وحتى نهاية شهر أيار (مايو)، قد تحدث تغييرات غير متوافقة أثناء استجابتنا لملاحظات المطوّرين.

نقاط النهاية

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

اتّفاقيات REST API

تتّبع Google Health API معايير مقترحات تحسين واجهات برمجة التطبيقات من Google (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" إلى أنّ حقلًا معيّنًا فقط في البروتوكول هو النص الأساسي.
الأفضل للاستخدام مع: العناصر المعقّدة والرسائل المتداخلة والبيانات الحسّاسة

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

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

بعد موافقة المستخدم من خلال بروتوكول OAuth 2.0 من Google، لن يتضمّن رد الرمز المميز معرّف مستخدم Fitbit أو Google. للحصول على رقم تعريف المستخدم، اتّصِل بنقطة النهاية getIdentity. getIdentity تعرض هذه السمة كلاً من معرّف المستخدم القديم في Fitbit ومعرّف المستخدم في Google.

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

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

طلب

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

الردّ

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

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

استخدِم نقطة النهاية 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"
}

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

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

ملاحظة مهمة: يختلف تنسيق معرّفات أنواع البيانات عندما يتضمّن نوع البيانات أكثر من كلمة واحدة. في نقطة نهاية، يجب أن يكون اسم نوع البيانات مكتوبًا بنمط kebab، مثل body-fat. في مَعلمة فلتر، يجب أن يكون اسم نوع البيانات بتنسيق snake case، مثل body_fat.

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

طلب

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/2515055256096816351/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 نقطة النهاية للحصول على البيانات حسب "مجموعة مصادر البيانات" في مصدر بيانات موحّد.

في ما يلي مثال على فلترة بيانات النوم التي سجّلها جهاز التتبُّع فقط لليوم التالي لتاريخ 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 نقطة النهاية لعرض مجموع نقاط البيانات استنادًا إلى فترة زمنية بالثواني، ضمن النطاق datetime استنادًا إلى الوقت الفعلي للمستخدمين (بالتوقيت العالمي المنسَّق).

عند الاتصال بنقطة النهاية rollUp، يجب تقديم نص الطلب الذي يمثّل النطاق الزمني المطلوب بالتوقيت المدني للمستخدم. على سبيل المثال:

طلب

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

{
  "range": {
    "startTime": "2026-02-17T17:00:00Z",
    "endTime": "2026-02-17T17:59:59Z"
  },
  "windowSize": "30s"
}

الردّ

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

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

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

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

طلب

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": 2,
        "day": 26
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 23,
        "minutes": 59,
        "seconds": 59,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1
}

الردّ

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "3822"
      }
    }
  ]
}

إدراج بيانات صحة مستخدم أو تعديلها

استخدِم نقطة النهاية patch لإدراج بيانات تطبيق Fitbit الخاصة بالمستخدم أو تعديلها.

في ما يلي مثال على تسجيل مستخدم لنسبة الدهون بالجسم على ميزان باسم "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-length: 329

{
  "name": "bodyFatName",
  "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/2515055256096816351/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
    }
  }
}

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

استخدِم 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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

الردّ

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

مكتبات العملاء

الروابط العامة وروابط التطبيقات

نقاط النهاية تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

اتّفاقيات REST API

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

نص الطلب

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

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

التواريخ

العناوين

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

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

طلب

الردّ

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

طلب

الردّ

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

طلب

الردّ

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

طلب

الردّ

فلترة البيانات حسب مصادر البيانات، مثل الأجهزة القابلة للارتداء

طلب

الردّ

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

طلب

الردّ

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

طلب

الردّ

إدراج بيانات صحة مستخدم أو تعديلها

طلب

الردّ

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

طلب

الردّ

نقاط النهاية