تطوير تجارب التغذية والترطيب باستخدام Google Health API

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

أنواع البيانات المتوافقة

الجدول: أنواع بيانات التغذية في Google Health API

نوع البيانات	العمليات المتاحة	النطاق
الطعام dataType: food filter parameter: food نوع السجلّ: طعام دليل التغذية	list, get	.nutrition.readonly .nutrition.writeonly
وحدة قياس الطعام dataType: food-measurement-unit filter parameter: food_measurement_unit نوع السجلّ: طعام دليل التغذية الأجهزة المتوافقة Fitbit Air Fitbit Blaze Fitbit Charge 2 Fitbit Charge 3 Fitbit Charge 4 Fitbit Ionic Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4	list, get	.nutrition.readonly .nutrition.writeonly
سجلّ شُرب الماء dataType: hydration-log filter parameter: hydration_log نوع التسجيل: جلسة التوافق مع الويب هوك	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly
سجلّ التغذية dataType: nutrition-log filter parameter: nutrition_log نوع التسجيل: جلسة دعم Webhook دليل التغذية الأجهزة المتوافقة Fitbit Air Fitbit Charge 3 Fitbit Charge 4 Fitbit Charge 5 Fitbit Charge 6 Fitbit Inspire 2 Fitbit Inspire 3 Fitbit Luxe Pixel Watch Pixel Watch 2 Pixel Watch 3 Pixel Watch 4 Fitbit Sense Fitbit Sense 2 Fitbit Versa 2 Fitbit Versa 3 Fitbit Versa 4 Fitbit Versa Lite	list, get, reconcile, rollup, dailyRollup, create, update, batchDelete	.nutrition.readonly .nutrition.writeonly

سجلّ التغذية

يمثّل سجلّ التغذية الطعام الذي سجّله المستخدم. هناك طريقتان لإنشاء سجلّ تغذية، حسب نوع الطعام:

1. الطعام الذي تم التعرّف عليه: اضبط الحقل food للإشارة إلى مورد طعام حالي. يتم ملء الحقول nutrients وenergy وenergyFromFat وtotalCarbohydrate وtotalFat وfoodDisplayName تلقائيًا من الطعام المُشار إليه. هذه هي الطريقة المفضّلة.

2. طعام مجهول الهوية: اضبط الحقل foodDisplayName يدويًا وقدِّم قيمًا لـ nutrients وenergy وenergyFromFat وtotalCarbohydrate وtotalFat. لا يمكن تعديل سجلّات التغذية التي تم إنشاؤها من طعام مجهول الهوية بعد إنشائها.

أنشِئ سجلّ تغذية يتضمّن طعامًا مجهولاً

لإنشاء إدخال في سجلّ التغذية، أرسِل طلب POST إلى نقطة النهاية nutrition-log dataPoints.

طلب

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-16T18:00:00Z",
      "endTime": "2026-06-16T18:30:00Z"
    },
    "foodDisplayName": "Grilled Chicken Breast",
    "mealType": "DINNER",
    "energy": {
      "kcal": 165
    },
    "totalCarbohydrate": {
      "grams": 0
    },
    "totalFat": {
      "grams": 3.6
    },
    "nutrients": [
      {
        "nutrient": "PROTEIN",
        "quantity": {
          "grams": 31
        }
      },
      {
        "nutrient": "SODIUM",
        "quantity": {
          "grams": 0.074
        }
      }
    ],
    "serving": {
      "amount": 1.0
    }
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/nutrition-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T18:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T18:30:00Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 18
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 18,
            "minutes": 30
          }
        }
      },
      "energy": {
        "kcal": 165
      },
      "totalCarbohydrate": {
        "grams": 0
      },
      "totalFat": {
        "grams": 3.6
      },
      "nutrients": [
        {
          "quantity": {
            "grams": 31
          },
          "nutrient": "PROTEIN"
        },
        {
          "quantity": {
            "grams": 0.074
          },
          "nutrient": "SODIUM"
        }
      ],
      "mealType": "DINNER",
      "serving": {
        "amount": 1
      },
      "foodDisplayName": "Grilled Chicken Breast"
    }
  }
}

إنشاء سجلّ تغذية يتضمّن الأطعمة التي تم التعرّف عليها

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

طلب

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"
    },
    "food": "users/me/dataTypes/food/dataPoints/food-id",
    "mealType": "LUNCH",
    "serving": {
      "amount": 1.0,
      "foodMeasurementUnit": "users/me/dataTypes/food-measurement-unit/dataPoints/food-measurement-unit-id"
    }
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/nutrition-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 12
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 12,
            "minutes": 30
          }
        }
      },
      "energy": {
        "kcal": 95
      },
      "energyFromFat": {
        "kcal": 3
      },
      "totalCarbohydrate": {
        "grams": 25
      },
      "totalFat": {
        "grams": 0.3
      },
      "nutrients": [
        {
          "quantity": {
            "grams": 4.4,
            "userProvidedUnit": "GRAM"
          },
          "nutrient": "DIETARY_FIBER"
        },
        {
          "quantity": {
            "grams": 19,
            "userProvidedUnit": "GRAM"
          },
          "nutrient": "SUGAR"
        },
        {
          "quantity": {
            "grams": 0.5,
            "userProvidedUnit": "GRAM"
          },
          "nutrient": "PROTEIN"
        }
      ],
      "mealType": "LUNCH",
      "serving": {
        "amount": 1,
        "foodMeasurementUnit": "users/me/dataTypes/food-measurement-unit/dataPoints/food-measurement-unit-id"
      },
      "food": "users/user-id/dataTypes/food/dataPoints/food-id",
      "foodDisplayName": "Apple"
    }
  }
}

ملاحظة: للحصول على معرّفات طعام صالحة، استخدِم العملية list على نوع البيانات food مع النطاق nutrition.readonly.

حذف سجلّات التغذية

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

الطلب:

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

{
  "names": [
    "users/me/dataTypes/nutrition-log/dataPoints/data-point-id"
  ]
}

حقول سجلّ التغذية

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

كمية الطاقة

تمثّل هذه السمة قياسًا للطاقة بالكيلو كالوري (kcal). لمزيد من التفاصيل، يُرجى الاطّلاع على EnergyQuantity.

{
  "kcal": 165
}

كمية الوزن

تمثّل هذه السمة قياس الوزن بالجرام. للحصول على التفاصيل، يُرجى الاطّلاع على WeightQuantity.

{
  "grams": 27.3
}

كمية العنصر الغذائي

تمثّل هذه السمة عنصرًا غذائيًا معيّنًا وكميته المقاسة. لمعرفة التفاصيل، يُرجى الاطّلاع على NutrientQuantity.

{
  "nutrient": "PROTEIN",
  "quantity": {
    "grams": 31
  }
}

قيم العناصر الغذائية

للاطّلاع على قائمة كاملة بأنواع العناصر الغذائية المتوافقة، يُرجى مراجعة Nutrient.

يتم العرض

تمثّل هذه السمة معلومات الحصة لإدخال في سجلّ التغذية. لمعرفة التفاصيل، يُرجى الاطّلاع على Serving.

{
  "amount": 1.5
}

قيم نوع الوجبة

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

طعام

الطعام هو نوع بيانات للقراءة فقط يمثّل صنف طعام في قاعدة بيانات الطعام. استخدِم العمليتَين list وget لتصفُّح الأطعمة المتاحة واسترداد معلوماتها الغذائية.

عرض الأطعمة

لإدراج الأطعمة، أرسِل طلب GET إلى نقطة النهاية food dataPoints:

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

ملاحظة: نوع البيانات food مخصّص للقراءة فقط. لا يمكنك إنشاء أصناف طعام أو تعديلها من خلال واجهة برمجة التطبيقات.

وحدة قياس الطعام

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

عرض قائمة بوحدات القياس المتاحة

لإدراج وحدات القياس المتاحة:

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

سجلّ شُرب الماء والسوائل

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

إنشاء سجلّ لترطيب الجسم

لإنشاء إدخال في سجلّ الترطيب، أرسِل طلب POST إلى نقطة النهاية hydration-log dataPoints. يتم تحويل جميع كميات الحجم إلى ملليلتر في تنسيق واجهة برمجة التطبيقات.

طلب

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

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-06-16T14:00:00Z",
      "endTime": "2026-06-16T14:00:01Z"
    },
    "amountConsumed": {
      "milliliters": 500,
      "userProvidedUnit": "FLUID_OUNCE_US"
    }
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/hydration-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "hydrationLog": {
      "interval": {
        "startTime": "2026-06-16T14:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T14:00:01Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 14
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 14,
            "seconds": 1
          }
        }
      },
      "amountConsumed": {
        "milliliters": 500,
        "userProvidedUnit": "FLUID_OUNCE_US"
      }
    }
  }
}

تعديل سجلّ شُرب الماء والسوائل

لتعديل إدخال في سجلّ الترطيب، أرسِل طلب PATCH إلى نقطة النهاية hydration-log dataPoints مع رقم تعريف نقطة البيانات.

طلب

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

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-06-16T10:00:00Z",
      "endTime": "2026-06-16T10:00:01Z"
    },
    "amountConsumed": {
      "milliliters": 500
    }
  }
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/user-id/dataTypes/hydration-log/dataPoints/data-point-id",
    "dataSource": {
      "recordingMethod": "UNKNOWN",
      "application": {
        "googleWebClientId": "google-web-client-id"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "hydrationLog": {
      "interval": {
        "startTime": "2026-06-16T10:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T10:00:01Z",
        "endUtcOffset": "0s",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 10
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 6,
            "day": 16
          },
          "time": {
            "hours": 10,
            "seconds": 1
          }
        }
      },
      "amountConsumed": {
        "milliliters": 500
      }
    }
  }
}

حذف سجلّات شرب الماء

لحذف إدخال واحد أو أكثر في سجلّ الترطيب، أرسِل طلب POST إلى طريقة batchDelete.

طلب

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

{
  "names": [
    "users/me/dataTypes/hydration-log/dataPoints/data-point-id"
  ]
}

الردّ

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.BatchDeleteDataPointsResponse",
    "dataPoints": [
      {
        "name": "users/user-id/dataTypes/hydration-log/dataPoints/data-point-id",
        "dataSource": {
          "recordingMethod": "UNKNOWN",
          "application": {
            "googleWebClientId": "google-web-client-id"
          },
          "platform": "GOOGLE_WEB_API"
        },
        "hydrationLog": {
          "interval": {
            "startTime": "2026-06-16T14:00:00Z",
            "startUtcOffset": "0s",
            "endTime": "2026-06-16T14:00:01Z",
            "endUtcOffset": "0s",
            "civilStartTime": {
              "date": {
                "year": 2026,
                "month": 6,
                "day": 16
              },
              "time": {
                "hours": 14
              }
            },
            "civilEndTime": {
              "date": {
                "year": 2026,
                "month": 6,
                "day": 16
              },
              "time": {
                "hours": 14,
                "seconds": 1
              }
            }
          },
          "amountConsumed": {
            "milliliters": 500,
            "userProvidedUnit": "FLUID_OUNCE_US"
          }
        }
      }
    ]
  }
}

تحذير: طلبات HTTP DELETE المباشرة إلى معرّفات الموارد المنتظمة (URI) لنقاط البيانات الفردية (مثل DELETE https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/<data-point-id>) غير متاحة وتعرض الخطأ 404 Not Found. يجب إجراء جميع عمليات الحذف باستخدام طريقة batchDelete.

حقول سجلّ شُرب الماء والسوائل

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

كمية الحجم

تمثّل هذه السمة قياسًا للحجم بالملليلتر. للحصول على التفاصيل، يُرجى الاطّلاع على VolumeQuantity.

{
  "milliliters": 250,
  "userProvidedUnit": "MILLILITER"
}

قيم وحدات الحجم

للحصول على قائمة كاملة بوحدات الحجم المتوافقة، يُرجى الاطّلاع على VolumeUnit. تشمل القيم الشائعة MILLILITER وLITER وCUP_US وFLUID_OUNCE_US.

الإرشادات

• استخدِم الطعام الذي تم التعرّف عليه إن أمكن. تعبئ واجهة برمجة التطبيقات الحقول الغذائية تلقائيًا، مما يقلل من الأخطاء ويضمن الاتساق مع قاعدة بيانات الأغذية.
• لا يمكن تعديل سجلّات التغذية التي تم إنشاؤها من طعام مجهول بعد إنشائها. إذا كنت بحاجة إلى تصحيح سجلّ طعام مجهول الهوية، احذِفه وأنشئ سجلّاً جديدًا.
• على عكس سجلّات التغذية الغذائية المجهولة المصدر، فإنّ إدخالات سجلّ الترطيب قابلة للتغيير بالكامل ويمكن تعديلها بعد إنشائها باستخدام طلب PATCH.
• تستخدم جميع كميات العناصر الغذائية في مصفوفة nutrients الغرام كوحدة قياس.
• يستخدم الحقلان energy وenergyFromFat الكيلو كالوري (kcal) كوحدة قياس.
• تحوّل واجهة برمجة التطبيقات جميع كميات السوائل وتخزّنها بالملليلتر. يُستخدم حقل userProvidedUnit الاختياري في VolumeQuantity فقط للعرض الموجّه للمستخدمين من جهة العميل.
• تؤدي طلبات HTTP DELETE المباشرة إلى نقاط بيانات hydration-log الفردية إلى عرض 404 Not Found. استخدِم طريقة batchDelete لإزالة إدخالات الموارد هذه.
• تستخدم سجلّات شرب الماء فاصلاً زمنيًا قصيرًا حيث يمثّل startTime وendTime الفترة الزمنية التي تم فيها استهلاك السائل.