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

Google Health API ใช้การแสดงตัวกรองเพื่อจํากัดจุดข้อมูลที่ส่งคืนเมื่อเรียกใช้เมธอดการดึงข้อมูลมาตรฐาน โดยเฉพาะอย่างยิ่ง ตัวกรองจะใช้กับรายการต่อไปนี้

• list ปลายทาง: การค้นหาจุดข้อมูลดิบ
• reconcile ปลายทาง: การค้นหาจุดข้อมูลสตรีมที่ปรับแล้ว

คู่มือนี้จะอธิบายวิธีใช้การกรอง ไวยากรณ์และรูปแบบ และมีตัวอย่างสำหรับระเบียนแต่ละประเภท

หลักเกณฑ์การกรอง

Google Health API ใช้ตัวกรองตามมาตรฐานข้อเสนอการปรับปรุง Google API (AIP-160)

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

ระบบจะส่งตัวกรองโดยใช้สตริงการค้นหาของ URL ในพารามิเตอร์ filter เนื่องจากตัวกรองมีอักขระพิเศษ (เช่น <, >= และเครื่องหมายคำพูด) จึงต้องเข้ารหัส URL เมื่อส่งในคำขอ HTTP

เช่น คำขอที่มีตัวกรอง steps.interval.civil_start_time >= "2026-03-04T00:00:00" ควรเข้ารหัสเป็น

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time%20%3E%3D%20%222026-03-04T00%3A00%3A00%22

รูปแบบการตั้งชื่อ

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

• เส้นทางปลายทาง: ใช้ขีดกลาง (เช่น /dataTypes/body-fat)
• สตริงตัวกรอง: ใช้ขีดล่าง (เช่น body_fat)

หากคุณใช้ขีดกลางในตัวระบุตัวกรอง API จะแสดง 400 Bad Request พร้อมเหตุผลของข้อผิดพลาด INVALID_DATA_POINT_FILTER

ประเภทและฟิลด์ตัวกรอง

ฟิลด์ที่คุณใช้ในตัวกรองจะขึ้นอยู่กับประเภทระเบียนของประเภทข้อมูล ที่คุณกําลังค้นหา ตารางต่อไปนี้อธิบายฟิลด์ที่รองรับสำหรับ ประเภทระเบียนแต่ละรายการ

โอเปอเรเตอร์และกฎรูปแบบที่รองรับ

นิพจน์ตัวกรองต้องเป็นไปตามกฎการจัดรูปแบบต่อไปนี้

โอเปอเรเตอร์การเปรียบเทียบ

ระบบรองรับเฉพาะโอเปอเรเตอร์การเปรียบเทียบ 2 รายการต่อไปนี้

การใช้โอเปอเรเตอร์การเปรียบเทียบอื่นๆ (เช่น >, <= หรือ =) จะแสดงผล 400 Bad Request ที่มี INVALID_DATA_POINT_FILTER_RESTRICTION_COMPARATOR

โอเปอเรเตอร์แบบลอจิคัล

ค่าตามเวลา

ค่าตัวอักษรเวลาในนิพจน์ตัวกรองต้องใช้รูปแบบต่อไปนี้

กฎการตรวจสอบตัวกรอง

ตัวกรองมีกฎดังนี้

API จะแสดง HTTP 400 Bad Request สำหรับตัวกรองที่ไม่ถูกต้อง ตรวจสอบerror.details[].metadata.detailedReasonsเพื่อหารหัสเหตุผลของข้อผิดพลาด

ขอบเขต OAuth ที่จำเป็น

หากต้องการค้นหาจุดข้อมูลโดยใช้ตัวกรอง ผู้ใช้ที่ได้รับอนุญาตต้องให้ขอบเขต OAuth ที่เกี่ยวข้องสำหรับประเภทข้อมูลนั้น หากไม่มีขอบเขตที่จำเป็น API จะแสดงสถานะ 403 Forbidden พร้อม MISSING_OAUTH_SCOPE

ตารางต่อไปนี้จะแมปขอบเขต OAuth กับประเภทข้อมูลที่ให้สิทธิ์เข้าถึงแบบอ่าน ตารางจะแสดงขอบเขตในรูปแบบที่เกี่ยวข้อง (เช่น .activity_and_fitness.readonly แสดงถึง https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly)

หากไคลเอ็นต์ได้รับขอบเขตการเขียนเท่านั้น (เช่น .activity_and_fitness.writeonly) สำหรับประเภทข้อมูลที่ขอ คุณยังคง ค้นหาจุดข้อมูลที่ไคลเอ็นต์ของคุณเองเขียนได้ ในกรณีนี้ คำขอจะถูกจำกัดโดยปริยายให้ใช้self-sourcesตระกูลแหล่งข้อมูล ดูรายละเอียดและ ข้อจำกัดของประเภทข้อมูลได้ที่ กรองตามตระกูลแหล่งข้อมูล

กรณีการใช้งานและตัวอย่าง

ตัวอย่างต่อไปนี้แสดงวิธีสร้างตัวกรองสำหรับสถานการณ์ทั่วไป

ค้นหาขั้นตอนตามช่วงเวลาจริง

ขั้นตอนการค้นหาที่บันทึกไว้ระหว่าง 2026-03-01T00:00:00Z (รวม) และ 2026-03-02T00:00:00Z (ไม่รวม)

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.start_time >= "2026-03-01T00:00:00Z"
  AND steps.interval.start_time < "2026-03-02T00:00:00Z"

ค้นหาขั้นตอนตามช่วงเวลาของพลเรือน

ขั้นตอนการค้นหาสำหรับทั้งวันในวันที่ 4 มีนาคม 2026 ตามเวลาท้องถิ่นของผู้ใช้มีดังนี้

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
  ?filter=steps.interval.civil_start_time >= "2026-03-04"
  AND steps.interval.civil_start_time < "2026-03-05"

ค้นหาไขมันร่างกายตามเวลาตัวอย่างจริง

ค้นหาการวัดไขมันร่างกายที่บันทึกไว้ตั้งแต่เดือนมีนาคม 2026 (ในเขตเวลา UTC)

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints
  ?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"

น้ำหนักการค้นหาตามเวลาตัวอย่างของพลเรือน

บันทึกน้ำหนักของคำค้นหาที่บันทึกหลังจากเวลาท้องถิ่นที่เฉพาะเจาะจง

GET https://health.googleapis.com/v4/users/me/dataTypes/weight/dataPoints
  ?filter=weight.sample_time.civil_time >= "2026-03-01T08:00:00"

ค้นหาสรุปความผันแปรของอัตราการเต้นของหัวใจรายวัน

ค้นหาสรุปรายวันของความผันแปรของอัตราการเต้นของหัวใจ (HRV) ที่บันทึกไว้ก่อน วันที่ที่ระบุ

GET https://health.googleapis.com/v4/users/me/dataTypes/daily-heart-rate-variability/dataPoints
  ?filter=daily_heart_rate_variability.date < "2026-08-15"

ค้นหาเซสชันการออกกำลังกายตามเวลาเริ่มต้นของเซสชัน

ค้นหาเซสชันการออกกำลังกายที่เกิดขึ้นในสัปดาห์ที่เฉพาะเจาะจงในเขตเวลาท้องถิ่นของผู้ใช้

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
  ?filter=exercise.interval.civil_start_time >= "2026-03-01"
  AND exercise.interval.civil_start_time < "2026-03-08"

ค้นหาเซสชันการนอนหลับตามเวลาสิ้นสุดของเซสชัน

ค้นหาบันทึกการนอนหลับตามเวลาสิ้นสุดของเซสชัน

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints
  ?filter=sleep.interval.civil_end_time >= "2026-03-04T05:00:00"
  AND sleep.interval.civil_end_time < "2026-03-04T12:00:00"

ค้นหาคลื่นไฟฟ้าหัวใจตามเวลาเริ่มต้น

ค้นหาการบันทึก ECG โดยเริ่มจากจุดเวลา UTC จริง โปรดทราบว่า การค้นหา ECG รองรับเฉพาะ>=การเปรียบเทียบstart_timeต่อไปนี้

GET https://health.googleapis.com/v4/users/me/dataTypes/electrocardiogram/dataPoints
  ?filter=electrocardiogram.interval.start_time >= "2026-03-10T12:00:00Z"

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

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

ปลายทาง list, reconcile, rollUp และ dailyRollUp รองรับพารามิเตอร์ dataSourceFamily ทั้งหมด กลไกการส่งผ่านจะขึ้นอยู่กับปลายทาง ดังนี้

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

ตารางต่อไปนี้อธิบายค่า dataSourceFamily ที่รองรับ

หากไม่มีจุดข้อมูลใดตรงกับตระกูลแหล่งข้อมูลที่ขอ การตอบกลับจะเป็น รายการที่ว่างเปล่าแทนที่จะเป็นข้อผิดพลาด

ขอบเขตแบบเขียนอย่างเดียวและแหล่งที่มาของตัวเอง

ผู้โทรที่ได้รับขอบเขตการเขียนเท่านั้น (เช่น .activity_and_fitness.writeonly) สำหรับประเภทข้อมูลที่ขอจะอ่านข้อมูลที่ตนเองเขียนได้ และอ่านได้เฉพาะข้อมูลนั้น

• คำขอที่ไม่มีพารามิเตอร์ dataSourceFamily อย่างชัดเจน หรือมี dataSourceFamily ตั้งค่าเป็น users/me/dataSourceFamilies/self-sources จะถูกจำกัดโดยนัยเป็น self-sources
• การขอแหล่งข้อมูลอื่นๆ (เช่น all-sources, google-wearables หรือ google-sources) ที่มีขอบเขตการเขียนเท่านั้นจะล้มเหลวโดยมีข้อผิดพลาด 403 Forbidden (PERMISSION_DENIED)

ข้อจำกัดของประเภทข้อมูลในปลายทางรายการ

ในlistปลายทาง (users.dataTypes.dataPoints.list) ระบบไม่รองรับการกรองตาม dataSourceFamily สำหรับประเภทข้อมูล sleep, food และ food-measurement-unit

• การตั้งค่า dataSourceFamily ใน list สำหรับ sleep, food หรือ food-measurement-unit จะล้มเหลวพร้อมข้อผิดพลาด 400 Bad Request (INVALID_ARGUMENT)
• การเรียก list สำหรับประเภทข้อมูลเหล่านี้เมื่อได้รับขอบเขตการเขียนเท่านั้น (ซึ่ง การจำกัดเป็น self-sources จะแสดงโดยขอบเขตของผู้เรียก) จะล้มเหลว พร้อมข้อผิดพลาด 403 Forbidden (PERMISSION_DENIED)
• หากต้องการกรองsleepจุดข้อมูลตามdataSourceFamily ให้ใช้reconcileปลายทาง แทน

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

หากต้องการแสดงจุดข้อมูลดิบที่ไคลเอ็นต์ของคุณเขียนขึ้นเองสำหรับผู้ใช้ ให้เรียกใช้list ปลายทางโดยตั้งค่าพารามิเตอร์การค้นหา dataSourceFamily เป็น users/me/dataSourceFamilies/self-sources

ตัวอย่างเช่น คำขอ GET ต่อไปนี้จะแสดงรายการการวัด body-fat แบบดิบ ที่ไคลเอ็นต์ที่เรียกใช้เขียนขึ้นโดยเริ่มตั้งแต่วันที่ 2026-03-01

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints
  ?dataSourceFamily=users/me/dataSourceFamilies/self-sources
  &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ปลายทางด้วยพารามิเตอร์การค้นหา 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"
      }
    }
  ]
}