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

ดูหลักเกณฑ์โดยละเอียดเกี่ยวกับขนาดกรอบเวลาการรวมข้อมูล กฎการจัดกลุ่ม และตัวอย่างการรวมข้อมูลได้ที่คู่มือข้อมูลรวม

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

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 ทันทีหลังจากแลกเปลี่ยนรหัสการให้สิทธิ์เพื่อดึงข้อมูลทั้ง legacyUserId และ healthUserId และยืนยันว่าบัญชี Google ของผู้ใช้ลิงก์กับ Google Health หากยังไม่ได้ลิงก์บัญชี getIdentity จะแสดงผล 400 Bad Request พร้อมเหตุผล ACCOUNT_NOT_LINKED (ดูหัวข้อจัดการบัญชี Google ที่ไม่ได้ลิงก์)

เช่น

ส่งคำขอ

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

การตอบกลับ (200 OK)

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

การตอบกลับ (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

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

ใช้ปลายทาง list สำหรับประเภทข้อมูลที่เฉพาะเจาะจงเพื่อรับข้อมูลระหว่างวันหรือข้อมูลโดยละเอียดที่รวบรวมตลอดทั้งวันในช่วงเวลาที่รองรับสำหรับประเภทข้อมูลนั้น

เช่น

ส่งคำขอ

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

คำตอบ

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

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

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

เช่น

ส่งคำขอ

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

เมื่อเรียกใช้ปลายทาง rollUp ให้ระบุเนื้อหาคำขอที่แสดงเวลาปิด-เปิดที่จำเป็น range และ windowSize (อย่างน้อย "1s") ดูหลักเกณฑ์โดยละเอียดเกี่ยวกับข้อกำหนด windowSize, การปรับความละเอียดของพื้นที่เก็บข้อมูล, กฎการจัดกลุ่ม รวมถึงตัวอย่างคำขอและการตอบกลับได้ที่รวมตามช่วงเวลาจริงในคู่มือข้อมูลรวม

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

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

ดูรายละเอียดเกี่ยวกับลักษณะการรวมข้อมูลรายวัน การจัดการเวลาพลเรือน ขีดจำกัดช่วงต่อคำขอ และตัวอย่างคำขอและการตอบกลับได้ที่หัวข้อรวมข้อมูลข้ามวันตามปฏิทินในคู่มือข้อมูลรวม

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

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

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

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

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

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

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

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

ส่งคำขอ

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-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: สำหรับปลายทางการรวมข้อมูลและ Rollup (เช่น rollUp และ dailyRollUp) ช่วงวันที่ของคำค้นหาจะถูกจำกัดตามประเภทข้อมูล ดังนี้
    • ช่วงสูงสุด 14 วันสำหรับ calories-in-heart-rate-zone, heart-rate, active-minutes และ total-calories
    • ช่วงสูงสุด 90 วันสําหรับข้อมูลสรุปประเภทอื่นๆ ทั้งหมด

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

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

การซิงค์ข้อมูลแบบแบ่งระยะ (Hot Load เทียบกับ Cold Load)

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

การแบ่งกลุ่มการค้นหาสำหรับการรวมข้อมูล

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

ใช้ประโยชน์จาก Roll-up ที่รวมไว้ล่วงหน้า

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

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

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