نقاط النهاية

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

اتّباع معايير REST API

تتّبع Google Health API معايير مقترحات تحسين واجهات برمجة التطبيقات من Google (AIP)، وتحديدًا AIP-127 (تحويل الترميز بين HTTP وgRPC) وAIP-131 إلى AIP-135 (الطرق العادية). تحدّد هذه المعايير كيفية ربط البيانات من رسالة proto بطلب 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 لفلترة البيانات حسب الوقت المدني أو الفترة الزمنية.

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

طلب

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

طلب البيانات السابقة

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

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

  • يعرض كل نقطة نهاية الحد الأقصى لحجم الصفحة وهو 10,000 نقطة بيانات لكل صفحة.
  • تقتصر النطاقات الزمنية لطلبات البحث على ما بين 14 و90 يومًا لكل طلب.

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