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 หรือ Epoch อื่นๆ

ส่วนหัว

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

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

ส่งคำขอ

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 นาที (ทั้งหน้าต่าง)
กลุ่มที่ 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 จะเขียนทับระเบียนที่มีอยู่

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

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

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

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