สำคัญ: การสนับสนุน Fitbit Web API เดิมจะสิ้นสุดในวันที่ 30 กันยายน 2026 หลังจากวันที่นี้ API จะยังคงทำงานต่อไป แต่ Google จะไม่แก้ไขข้อบกพร่องหรือให้การสนับสนุน API อีกต่อไป ในวันที่ 30 ตุลาคม 2026 ระบบจะปิด Fitbit Web API และ API จะไม่ทำงานหรือซิงค์ข้อมูลกับผู้ใช้ Fitbit อีกต่อไป หากต้องการเข้าถึงข้อมูลของผู้ใช้ต่อไปหลังจากวันที่นี้ ให้ย้ายข้อมูลไปใช้ Google Health API ดูคำแนะนำในการย้ายข้อมูลได้ที่คำแนะนำในการย้ายข้อมูล Fitbit Web API

Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

Endpoint

หน้านี้จะแสดงภาพรวมของข้อกำหนด REST API พร้อมดัชนีของ งานทั่วไปของ Google Health API และตัวอย่างของแต่ละงาน

ข้อกำหนดของ REST API

Google Health API เป็นไปตามมาตรฐานข้อเสนอการปรับปรุง Google API (AIP) โดยเฉพาะ AIP-127 (การแปลงรหัส HTTP และ gRPC) และ AIP-131 ถึง AIP-135 (วิธีการมาตรฐาน) มาตรฐานเหล่านี้กำหนดวิธีแมปข้อมูลจากข้อความ Proto ไปยังคำขอ HTTP

พารามิเตอร์การค้นหา

ระบบจะใช้พารามิเตอร์การค้นหาเมื่อข้อมูลเป็นส่วนหนึ่งของ URL โดยหลักๆ แล้วจะใช้สำหรับคำขอ GET (ดึงข้อมูลทรัพยากร) หรือคำขอ LIST (การกรอง/การแบ่งหน้า) แต่ก็ใช้สำหรับการดำเนินการ DELETE ด้วย

ตําแหน่ง: ต่อท้าย URL หลัง ?
ไวยากรณ์: คู่คีย์-ค่าที่คั่นด้วย &
การแมป: ทุกฟิลด์ในข้อความคำขอที่ไม่ได้เป็นส่วนหนึ่งของเทมเพลตเส้นทาง URL จะได้รับการแมปกับพารามิเตอร์การค้นหา
เหมาะสำหรับ: ประเภทข้อมูลอย่างง่าย (สตริง จำนวนเต็ม Enum) และฟิลด์ที่ซ้ำ

ตัวอย่างไวยากรณ์

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" หมายความว่ามีเฉพาะฟิลด์ที่เฉพาะเจาะจงใน Proto เท่านั้นที่เป็นเนื้อหา
เหมาะสำหรับ: ออบเจ็กต์ที่ซับซ้อน ข้อความที่ซ้อนกัน และข้อมูลที่ละเอียดอ่อน

ตัวอย่างไวยากรณ์

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โอเปอเรชัน จะใช้ทั้ง 2 อย่าง 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

ดัชนีงาน API

ส่วนนี้แสดงดัชนีของงาน Google Health API ที่พบบ่อยและตัวอย่างของแต่ละงาน

รับรหัสผู้ใช้ Fitbit หรือ Google

หลังจากที่ผู้ใช้ให้ความยินยอมผ่าน Google OAuth 2.0 การตอบกลับโทเค็นจะไม่มี รหัสผู้ใช้ Fitbit หรือ Google หากต้องการรับรหัสผู้ใช้ ให้เรียกใช้getIdentityปลายทาง getIdentity แสดงทั้งรหัสผู้ใช้ Fitbit รุ่นเดิมและรหัสผู้ใช้ Google

เราขอแนะนำให้คุณเรียกใช้ปลายทาง getIdentity และจัดเก็บทั้งรหัสผู้ใช้ทันทีที่ผู้ใช้ใหม่ให้ความยินยอมผ่าน OAuth ซึ่งช่วยให้การผสานรวมของคุณเข้ากันได้ทั้งแบบย้อนหลังและแบบไปข้างหน้า

เช่น

ส่งคำขอ

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 ปลายทางสำหรับ ประเภทข้อมูลที่เฉพาะเจาะจงเพื่อรับข้อมูลระหว่างวันหรือข้อมูลแบบละเอียดที่รวบรวมตลอดทั้งวันใน ช่วงเวลาที่รองรับสำหรับประเภทข้อมูลนั้น

หมายเหตุ: เมื่ออุปกรณ์ที่เชื่อมต่อซิงค์กัน อัลกอริทึมในอุปกรณ์จะจัดกลุ่มข้อมูลการวัดและส่งอีกครั้ง และอัปโหลดบันทึกใหม่ที่มีขอบเขตทับซ้อนกัน หากต้องการเรียกข้อมูลช่วงเวลาที่ซ้ำกันออกและปรับให้ตรงกัน โปรดดูรับมุมมองที่ปรับให้ตรงกันของข้อมูลช่วงเวลา ดูข้อมูลเบื้องต้น เกี่ยวกับการซิงค์อุปกรณ์ที่เชื่อมต่อและการเปรียบเทียบการทำงานระหว่าง list กับ reconcile ได้ที่ คู่มือการจัดการข้อมูล

เช่น

ส่งคำขอ

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 ปลายทาง ปลายทาง reconcile จะขจัดช่วงเวลาที่ซ้ำซ้อนโดยอัตโนมัติในกลุ่มการซิงค์ และอุปกรณ์บันทึกหลายเครื่อง โดยจะแสดงสตรีมที่ต่อเนื่องและเชื่อถือได้ ซึ่งเหมาะสำหรับการแสดงไทม์ไลน์กิจกรรมและการคำนวณระยะเวลา

หากต้องการทราบข้อมูลพื้นฐานเกี่ยวกับสาเหตุที่อุปกรณ์ที่เชื่อมต่อสร้างช่วงที่ทับซ้อนกันและการเปรียบเทียบการทำงานระหว่าง list กับ reconcile โปรดดูคู่มือการจัดการข้อมูล

ตัวอย่างต่อไปนี้เปรียบเทียบการตอบกลับของ list (ซึ่งแสดงทั้งระเบียนที่ทับซ้อนกัน) กับ reconcile (ซึ่งแก้ไขความขัดแย้งโดยแสดงระเบียนที่เชื่อถือได้) สำหรับผู้ใช้ที่มีเซสชันการออกกำลังกาย 2 รายการที่ทับซ้อนกัน

รายการดิบ

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 เพื่อกรองข้อมูลตามเวลาพลเรือน หรือช่วงเวลา

สำคัญ: รูปแบบ ของตัวระบุประเภทข้อมูลจะแตกต่างกันเมื่อประเภทข้อมูลมีคำมากกว่า 1 คำ ในปลายทาง ชื่อประเภทข้อมูลต้องอยู่ในรูปแบบ Kebab Case เช่น 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/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 ที่รองรับ

ตัวเลือก	คำอธิบาย
`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 ปลายทางเพื่อแสดงผล การรวมจุดข้อมูลตามกรอบเวลาเป็นวินาทีในช่วงdatetime ตามเวลาจริงของผู้ใช้ (ใน UTC)

เมื่อเรียกใช้ปลายทาง rollUp ให้ระบุเนื้อหาของคำขอที่แสดงถึง ช่วงเวลาที่จำเป็นและ windowSize โปรดทราบข้อกำหนดต่อไปนี้สำหรับ windowSize

ขนาดหน้าต่างขั้นต่ำ: ระยะเวลา windowSize ต้องยาวอย่างน้อย 1 วินาที ("1s") ระบบจะปฏิเสธระยะเวลาที่ต่ำกว่า 1 วินาที ระยะเวลา 0 หรือระยะเวลาติดลบ พร้อมด้วย 400 Bad Request (INVALID_ROLLUP_WINDOW)
การจัดแนวความละเอียดของพื้นที่เก็บข้อมูล: เลือก windowSize ที่เท่ากับหรือมากกว่า ความละเอียดของพื้นที่เก็บข้อมูลพื้นฐานของประเภทข้อมูล (เช่น "60s" สำหรับช่วงเวลาก้าว 1 นาที) เพื่อหลีกเลี่ยงการกระจายข้อมูลรวมที่ไม่สม่ำเสมอในกลุ่มย่อย โปรดดูรายละเอียดที่ ขนาดหน้าต่างการสรุปและความละเอียดของพื้นที่เก็บข้อมูลพื้นฐาน

ตัวอย่างเช่น หากต้องการสรุปจำนวนก้าวในช่วงเวลา 1 นาที (60s) ให้ทำดังนี้

ส่งคำขอ

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": "60s"
}

คำตอบ

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:56:00Z",
      "steps": {
        "countSum": "72"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:55:00Z",
      "steps": {
        "countSum": "85"
      }
    },
...
  ]
}

รวมข้อมูลในวันเดียวหรือหลายวัน

ควรใช้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"
      }
    }
  ]
}

การจัดกลุ่มเมื่อช่วงไม่ใช่จำนวนทวีคูณของขนาดหน้าต่าง

หากช่วงที่ขอไม่ใช่จำนวนเท่าที่แน่นอนของ windowSize (หรือ windowSizeDays) ระบบจะตัดกลุ่มสุดท้ายตามลำดับเวลาที่ จุดสิ้นสุดบนของช่วง และจะครอบคลุมระยะเวลาที่สั้นกว่าขนาดหน้าต่าง API จะยอมรับคำขอของคุณโดยไม่มีการแก้ไข และจะไม่ปัดเศษ เปลี่ยนเวลา หรือประมาณค่าข้อมูล

API จะใช้การหารแบบปัดเศษขึ้นเพื่อคำนวณจำนวนช่วงการรวบรวมทั้งหมด เพื่อให้ครอบคลุมช่วงที่ขอทั้งหมด

Number of windows = ceiling(Range duration / Window size)

โดยแต่ละกลุ่มจะเริ่มต้นตามลำดับจากจุดเริ่มต้นของช่วง หากการเพิ่ม หน้าต่างขนาดเต็มอีกหน้าต่างหนึ่งจะขยายเวลาออกไปเกินเวลาสิ้นสุดที่คุณขอ ระบบจะตัด (จำกัด) หน้าต่างสุดท้ายที่เวลาสิ้นสุดของช่วง

วิธีการทำงานของการจัดกลุ่ม

เมื่อขอการสรุปที่มีช่วงที่หารไม่ได้ API จะใช้กฎต่อไปนี้

การจัดกลุ่มจะเริ่มต้นที่จุดเริ่มต้นของช่วงที่คุณขอ (range.startTime หรือ range.start) และดำเนินการต่อไปตามขนาดหน้าต่าง (windowSize หรือ windowSizeDays)
กลุ่มข้อมูลตามลำดับเวลาสุดท้ายจะยึดตามจุดสิ้นสุดของช่วงที่คุณขอ (range.endTime หรือ range.end) ซึ่งหมายความว่ากลุ่มข้อมูลนี้จะครอบคลุมระยะเวลาที่สั้นกว่าขนาดหน้าต่างที่ขอ
ออบเจ็กต์ RollupDataPoint หรือ DailyRollupDataPoint ที่แสดงผล จะระบุการประทับเวลาเริ่มต้นและสิ้นสุดของตัวเองอย่างชัดเจน ซึ่งคุณสามารถใช้ เพื่อตรวจสอบระยะเวลาจริงของที่เก็บข้อมูลที่ถูกตัดทอน
เนื่องจาก API จะแสดงข้อมูลการสะสมตามลำดับเวลาแบบย้อนกลับ (ใหม่สุด ก่อน) บัคเก็ตตามลำดับเวลาสุดท้าย (ซึ่งเป็นบัคเก็ตที่ถูกตัดทอน) จึงปรากฏเป็นองค์ประกอบแรก (index 0) ในรายการที่แสดงผล

สถานการณ์: ช่วง 12 นาทีที่มีกรอบเวลา 5 นาที

สมมติว่าไคลเอ็นต์ขอการรวมในช่วง 12 นาทีโดยมี 5 นาที windowSize

range.startTime: 10:00:00
range.endTime: 10:12:00 (ระยะเวลารวม: 12 นาที)
windowSize: 5 minutes

เนื่องจาก 12 นาทีไม่ใช่จำนวนเท่าของ 5 นาที (12 = 5 * 2 + 2) API จึงยอมรับคำขอและคำนวณจำนวนช่วงเวลาเป็น ceiling(12 / 5) = 3

ซึ่งจะสร้างกลุ่มตามลำดับเวลา 3 กลุ่มต่อไปนี้

กลุ่มที่ 1: [10:00:00, 10:05:00) — ระยะเวลา: 5 นาที (ทั้งหน้าต่าง)
Bucket 2: [10:05:00, 10:10:00) — ระยะเวลา: 5 นาที (ทั้งหน้าต่าง)
Bucket 3 (ตัดทอน): [10:10:00, 10:12:00) — ระยะเวลา: 2 นาที (ตัดทอนที่ range.endTime)

ผลกระทบต่อมูลค่ารวม

เนื่องจากระยะเวลาของช่วงสุดท้ายสั้นลง เมตริกแบบสะสม (เช่น ผลรวมหรือจำนวนก้าว) จึงจะต่ำกว่าในที่เก็บข้อมูลที่ถูกตัดออกเพียงเพราะระยะเวลาที่สั้นลง

หากผู้ใช้เดินด้วยอัตราการก้าวที่สม่ำเสมอ 100 ก้าวต่อนาทีตลอดช่วง 12 นาทีนี้

กลุ่มที่ 1 (10:00–10:05): 500 ก้าว (5 นาที × 100 ก้าว/นาที)
กลุ่มที่ 2 (10:05–10:10): 500 ก้าว (5 นาที × 100 ก้าว/นาที)
กลุ่มที่ 3 (10:10–10:12): 200 ก้าว (2 นาที × 100 ก้าว/นาที)

หมายเหตุ: จำนวนก้าวที่ต่ำกว่าที่ 200 ก้าวในกลุ่มที่ 3 เป็นเพราะระยะเวลา 2 นาที ของหน้าต่างที่ถูกตัด ไม่ใช่กิจกรรมของผู้ใช้ลดลง เมื่อ พล็อตหรือแสดงข้อมูลนี้ ให้วิเคราะห์และปรับค่าการนับโดยใช้ ระยะเวลาที่ชัดเจนของแต่ละกลุ่มเพื่อหลีกเลี่ยงการแสดงกิจกรรมของผู้ใช้ที่ลดลงอย่างทำให้เข้าใจผิด

ตัวอย่างการตอบกลับจาก API ที่แสดงการเรียงลำดับ

เนื่องจาก API แสดงผลลัพธ์ตามลำดับเวลาย้อนหลัง บัคเก็ตที่ ถูกตัดทอนจึงปรากฏเป็นองค์ประกอบแรกในรายการที่แสดงผล

{
  "rollupDataPoints": [
    {
      "startTime": "2026-08-20T10:10:00Z",
      "endTime": "2026-08-20T10:12:00Z",
      "steps": {
        "countSum": "200"
      }
    },
    {
      "startTime": "2026-08-20T10:05:00Z",
      "endTime": "2026-08-20T10:10:00Z",
      "steps": {
        "countSum": "500"
      }
    },
    {
      "startTime": "2026-08-20T10:00:00Z",
      "endTime": "2026-08-20T10:05:00Z",
      "steps": {
        "countSum": "500"
      }
    }
  ]
}

ขนาดหน้าต่างการสรุปและระดับความละเอียดของพื้นที่เก็บข้อมูลพื้นฐาน

แม้ว่าปลายทาง rollUp จะยอมรับ windowSize ใดก็ตามที่ 1 วินาทีขึ้นไป แต่ข้อมูลประเภทต่างๆ จะบันทึกและคงการวัดที่อัตราการสุ่มตัวอย่างหรือระยะเวลาช่วงที่แตกต่างกันในที่เก็บข้อมูลพื้นฐาน ตัวอย่างเช่น โดยปกติแล้ว ระบบจะบันทึกเมตริกกิจกรรมทางกายภาพที่วัดได้จากอุปกรณ์สวมใส่ เช่น steps, distance, active-minutes และ active-energy-burned ทุกๆ 1 นาที (60s)

เมื่อรวบรวมประเภทข้อมูลช่วง rollUpปลายทางจะวางจุดข้อมูลที่บันทึกแต่ละจุด ลงในที่เก็บที่มีstartTimeของจุดข้อมูล API จะไม่แบ่งส่วน แทรกค่า หรือกระจายข้อมูลช่วงเวลาไปยังที่เก็บข้อมูลช่วงเวลาย่อย

หากคุณระบุ windowSize ที่เล็กกว่าช่วงเวลาการจัดเก็บข้อมูลพื้นฐาน (เช่น ขอหน้าต่าง 10 วินาทีสําหรับ steps ที่จัดเก็บในช่วงเวลา 1 นาที)

กลุ่มย่อยแรกที่ตรงกับ startTime ของช่วงเวลา (เช่น 10:00:00 ถึง 10:00:10) จะได้รับจำนวนสะสมทั้งนาที (เช่น จำนวนก้าวทั้งหมด 100 ก้าวที่บันทึกไว้ในนาทีนั้น)
ส่วนถังย่อยที่เหลือภายในนาทีเดียวกันนั้น (10:00:10 ถึง 10:00:20, 10:00:20 ถึง 10:00:30 และอื่นๆ) จะไม่ได้รับจุดข้อมูลเนื่องจากไม่มีช่วงเวลาใดเริ่มต้นภายในช่วงเวลาเหล่านั้น

ซึ่งส่งผลให้ข้อมูล "ผันผวน" โดยที่ค่าของทั้งช่วงเวลาจะกระจุกตัว อยู่ในหน้าต่างย่อยแรก

หากต้องการรับข้อมูลรวมที่มีการกระจายอย่างสม่ำเสมอและมีความหมาย ให้ตั้งค่า windowSize เป็นระยะเวลาที่เท่ากับหรือมากกว่าความละเอียดของพื้นที่เก็บข้อมูลพื้นฐานของ ประเภทข้อมูลเป้าหมายเสมอ (เช่น 60s หรือมากกว่าสำหรับ steps) ดูความละเอียดของพื้นที่เก็บข้อมูลและหน้าต่างการสะสมขั้นต่ำที่แนะนำสำหรับแต่ละประเภทข้อมูลได้ในข้อมูลอ้างอิงประเภทข้อมูล Google Health API

อัปเดตข้อมูลสุขภาพของผู้ใช้

ใช้patchปลายทางเพื่ออัปเดตข้อมูลสุขภาพของผู้ใช้

ปลายทาง patch จะอัปเดตระเบียนที่มีอยู่ตามตัวระบุ ที่ระบุใน URL ของคำขอ ระบุตัวระบุของจุดข้อมูลที่แทรกก่อนหน้านี้ API จะเขียนทับระเบียนที่มีอยู่

เจ้าของบันทึกยังอัปเดตการประทับเวลาช่วงของจุดข้อมูล (startTime และ endTime) ได้ด้วย หรืออาจมีการส่งต่อจากแพลตฟอร์มต้นทาง เช่น Health Connect ดูรายละเอียดเกี่ยวกับการเปลี่ยนแปลงการประทับเวลาได้ที่คู่มือการจัดการข้อมูล ดูตัวอย่างการอัปเดตการประทับเวลาช่วงเวลาได้ที่ อัปเดตการประทับเวลาช่วงเวลาสำหรับข้อมูลที่มีอยู่

กรณีที่ควรใช้ตัวระบุจุดข้อมูล

ตัวระบุจุดข้อมูลมีความสำคัญในสถานการณ์ต่อไปนี้

การอัปเดตที่กำหนดเป้าหมาย: หากต้องการอัปเดตการวัดผลที่เฉพาะเจาะจง ให้ระบุตัวระบุในการขอ patch
การลบ: การเก็บตัวระบุไว้จะช่วยให้แอปพลิเคชันของคุณลบ ระเบียนได้ในภายหลังโดยใช้batchDeleteปลายทาง

ต่อไปนี้เป็นตัวอย่างที่ผู้ใช้อัปเดตค่าไขมันร่างกายบนเครื่องชั่ง ที่ชื่อ "HumanScale" จากบริษัท "Scales R Us" ค่าการอ่านค่าไขมันร่างกายใหม่ของผู้ใช้คือ 20% สำหรับวันที่ 10-03-2026:

ส่งคำขอ

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 คือความสามารถในการติดตามประสิทธิภาพของผู้ใช้และตรวจสอบค่าสำคัญด้านสุขภาพของผู้ใช้เป็นระยะเวลานาน คุณสามารถค้นหาข้อมูลของผู้ใช้ได้ย้อนหลังเท่าที่ระบบบันทึกไว้ โดย API จะไม่จำกัด จำนวนข้อมูลย้อนหลังที่แอปพลิเคชันของคุณ ใช้ได้

อย่างไรก็ตาม การค้นหาข้อมูลย้อนหลังยังคงอยู่ภายใต้ ขีดจํากัดอัตรามาตรฐาน Google Health API ใช้การแบ่งหน้าอัตโนมัติที่มี ขนาดหน้าเฉพาะปลายทางเพื่อจัดการความเสถียรของระบบและ ป้องกันไม่ให้มีเพย์โหลดมากเกินไป โปรดทราบขอบเขตและลักษณะการทำงานต่อไปนี้

การแบ่งหน้าอัตโนมัติ: หากคุณค้นหาช่วงข้อมูลที่ยาว API จะแสดงเฉพาะผลลัพธ์หน้าแรกจนถึงขีดจำกัดขนาดหน้าสำหรับปลายทางนั้น พร้อมกับ nextPageToken คุณต้องใช้ nextPageToken เพื่อขอหน้าเว็บถัดไป
ขนาดหน้าเว็บที่เปลี่ยนแปลงได้: ขีดจํากัดการจํากัดความถี่จะขึ้นอยู่กับปลายทาง และประเภทข้อมูล สำหรับข้อมูลส่วนใหญ่ ขนาดหน้าเว็บจะจำกัดไว้ที่ 10,000 รายการ อย่างไรก็ตาม สำหรับข้อมูลบางประเภท เช่น exercise และ sleep ขนาดหน้าเว็บเริ่มต้นและสูงสุดจะจำกัดไว้ที่ 25 เช่น หากไคลเอ็นต์ขอข้อมูลการนอนหลับทั้งหมดในช่วง 10 ปีที่ผ่านมา API จะยังคงแสดงเซสชันการนอนหลับเพียง 25 รายการในหน้าแรก
ข้อจำกัดของช่วงวันที่สะสม: สำหรับปลายทางการสะสมและการรวบรวมข้อมูล (เช่น rollUp และ dailyRollUp) ระบบจะจำกัดช่วงวันที่ของการค้นหา ตามประเภทข้อมูล ดังนี้
- ช่วงสูงสุด 14 วันสำหรับ calories-in-heart-rate-zone, heart-rate, active-minutes และ total-calories
- ช่วงสูงสุด 90 วันสําหรับข้อมูลการสรุปประเภทอื่นๆ ทั้งหมด

การดึงข้อมูลทั้งชุดจะต้องมีการแบ่งหน้าตามลำดับหน้า ทั้งนี้ขึ้นอยู่กับปริมาณข้อมูลย้อนหลังที่แอปพลิเคชันของคุณต้องการ โปรดคำนึงถึงเรื่องนี้เมื่อออกแบบกระบวนการซิงค์ข้อมูลของแอปพลิเคชัน

โปรดทําตามหลักเกณฑ์ต่อไปนี้เมื่อ ค้นหาข้อมูลย้อนหลังเพื่อให้มั่นใจว่าประสิทธิภาพจะดีที่สุดและหลีกเลี่ยงข้อผิดพลาดของ API

การซิงค์ข้อมูลแบบเป็นระยะ (การโหลดแบบร้อนเทียบกับการโหลดแบบเย็น)

การโหลด "ด่วน" ครั้งแรก: ดึงและแสดงเฉพาะข้อมูลในช่วง 7-14 วันล่าสุด ในลําดับการโหลดหลัก ซึ่งจะช่วยให้ผู้ใช้เห็นข้อมูลได้ทันทีโดยไม่ต้องรอการค้นหาที่ใช้เวลานาน
การโหลด "เย็น" ในเบื้องหลัง: มอบหมายการดึงข้อมูลย้อนหลังที่เก่ากว่า ไปยังคิวแบบไม่พร้อมกันที่มีลำดับความสำคัญต่ำกว่าหรือกระบวนการเบื้องหลัง หลังจากแสดงผล UI หลักแล้ว

การแบ่งคำค้นหาเพื่อการรวม

เนื่องจากปลายทางแบบสรุปและแบบสรุปรายวันบังคับใช้ช่วงวันที่สูงสุด (14 หรือ 90 วัน ขึ้นอยู่กับประเภทข้อมูล) คุณจึงต้องแบ่ง คําค้นหาการรวบรวมข้อมูลย้อนหลังขนาดใหญ่ออกเป็นช่วงเวลาที่เล็กลงและต่อเนื่อง ภายในขีดจํากัดเหล่านี้
จัดกลุ่มหรือจัดลำดับคำค้นหาย่อยเหล่านี้อย่างปลอดภัยเพื่อไม่ให้เกินขีดจำกัดการทำงานพร้อมกัน และรักษาตัวบ่งชี้ความคืบหน้าของ UI ให้คงที่

ใช้การสรุปข้อมูลที่รวบรวมไว้ล่วงหน้า

ปรับโครงสร้างแดชบอร์ดภาพรวมและแผนภูมิแนวโน้มเพื่อใช้ปลายทางแบบสรุปที่รวบรวมไว้ล่วงหน้า (เช่น DailyRollUpDataPoints) ซึ่งจะช่วยลดค่าใช้จ่ายในการคำนวณที่แบ็กเอนด์และเวลาในการโอนข้อมูลผ่านเครือข่ายไปยังไคลเอ็นต์ได้อย่างมาก

การจัดการข้อผิดพลาดที่ยืดหยุ่น (การลองใหม่แบบอัจฉริยะ)

ใช้การจัดการ Exponential Backoff อย่างเข้มงวดเมื่อพบขีดจำกัดอัตรา (429 Too Many Requests) และระยะหมดเวลาของเกตเวย์เซิร์ฟเวอร์ (504 Gateway Timeout) อย่าลองส่งเพย์โหลดขนาดใหญ่ที่ล้มเหลวซ้ำทันที การลองใหม่ทันทีจะเพิ่มความหนาแน่นของแบ็กเอนด์และทำให้ระบบเสื่อมถอยลง

ไลบรารีของไคลเอ็นต์

ตัวกรอง

Endpoint จัดทุกอย่างให้เป็นระเบียบอยู่เสมอด้วยคอลเล็กชัน บันทึกและจัดหมวดหมู่เนื้อหาตามค่ากำหนดของคุณ

ข้อกำหนดของ REST API

พารามิเตอร์การค้นหา

เนื้อความของคำขอ

กรณีไฮบริด

ความแตกต่างที่สำคัญโดยย่อ

วันที่

ส่วนหัว

ดัชนีงาน API

รับรหัสผู้ใช้ Fitbit หรือ Google

ส่งคำขอ

คำตอบ

รับข้อมูลระหว่างวันหรือข้อมูลโดยละเอียดที่รวบรวมตลอดทั้งวัน

ส่งคำขอ

คำตอบ

ดูข้อมูลช่วงเวลาที่ปรับแล้ว

รายการดิบ

ปรับยอดแล้ว

ข้อมูลตัวกรอง

กรองตามตระกูลแหล่งข้อมูล

กรองข้อมูลตามเวลาเริ่มต้นของช่วงเวลา

ส่งคำขอ

คำตอบ

กรองข้อมูลตามเวลาจริงของการสังเกตตัวอย่าง

ส่งคำขอ

คำตอบ

กรองและรวมตามตระกูลแหล่งข้อมูล

ตระกูลแหล่งข้อมูลที่รองรับ

ส่งคำขอ

คำตอบ

ส่งคำขอ

คำตอบ

ส่งคำขอ

คำตอบ

รวมจุดข้อมูลในช่วงระยะเวลาหนึ่ง

ส่งคำขอ

คำตอบ

รวมข้อมูลในวันเดียวหรือหลายวัน

ส่งคำขอ

คำตอบ

การจัดกลุ่มเมื่อช่วงไม่ใช่จำนวนทวีคูณของขนาดหน้าต่าง

วิธีการทำงานของการจัดกลุ่ม

สถานการณ์: ช่วง 12 นาทีที่มีกรอบเวลา 5 นาที

ผลกระทบต่อมูลค่ารวม

ตัวอย่างการตอบกลับจาก API ที่แสดงการเรียงลำดับ

ขนาดหน้าต่างการสรุปและระดับความละเอียดของพื้นที่เก็บข้อมูลพื้นฐาน

อัปเดตข้อมูลสุขภาพของผู้ใช้

กรณีที่ควรใช้ตัวระบุจุดข้อมูล

ส่งคำขอ

คำตอบ

อัปเดตการประทับเวลาช่วงเวลาสำหรับข้อมูลที่มีอยู่

ส่งคำขอ

คำตอบ

บันทึกรายการอาหาร

ส่งคำขอ

คำตอบ

ลบข้อมูลสุขภาพของผู้ใช้

ส่งคำขอ

คำตอบ

ค้นหาข้อมูลอุปกรณ์

ส่งคำขอ

คำตอบ

ค้นหาข้อมูลย้อนหลัง

การซิงค์ข้อมูลแบบเป็นระยะ (การโหลดแบบร้อนเทียบกับการโหลดแบบเย็น)

การแบ่งคำค้นหาเพื่อการรวม

ใช้การสรุปข้อมูลที่รวบรวมไว้ล่วงหน้า

การจัดการข้อผิดพลาดที่ยืดหยุ่น (การลองใหม่แบบอัจฉริยะ)

Endpoint