การสมัครใช้บริการเว็บฮุค

การติดตามจะพร้อมให้บริการเร็วๆ นี้

Google Health API ช่วยให้แอปพลิเคชันของคุณได้รับการแจ้งเตือนแบบเรียลไทม์ เมื่อข้อมูลสุขภาพของผู้ใช้มีการเปลี่ยนแปลง แทนที่จะสำรวจการเปลี่ยนแปลง เซิร์ฟเวอร์ของคุณจะได้รับคำขอ HTTPS POST (Webhook) ทันทีที่มีข้อมูลใน Google Health API

ประเภทข้อมูลที่รองรับ

ระบบรองรับการแจ้งเตือน Webhook สำหรับประเภทข้อมูลต่อไปนี้

• ขั้นตอน
• ระดับความสูง
• ระยะทาง
• ชั้น
• น้ำหนัก
• การนอนหลับ

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

• กิจกรรม ซึ่งครอบคลุมประเภทข้อมูลจำนวนก้าว ความสูง ระยะทาง และชั้น
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
  • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
• ตัวชี้วัดสุขภาพซึ่งครอบคลุมประเภทข้อมูลน้ำหนัก
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
  • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
• การนอนหลับ ซึ่งครอบคลุมประเภทข้อมูลการนอนหลับต่อไปนี้
  • https://www.googleapis.com/auth/googlehealth.sleep
  • https://www.googleapis.com/auth/googlehealth.sleep.readonly

จัดการผู้ติดตาม

คุณต้องลงทะเบียนผู้ติดตามซึ่งแสดงถึงปลายทางการแจ้งเตือนของแอปพลิเคชันก่อนจึงจะรับการแจ้งเตือนได้ คุณจัดการผู้ติดตามได้โดยใช้ REST API ที่มีอยู่ที่ projects.subscribers

ปลายทางของผู้ติดตามต้องใช้ HTTPS (TLSv1.2+) และเข้าถึงได้แบบสาธารณะ ในระหว่างการสร้างและการอัปเดตผู้ติดตาม Google Health API จะดำเนินการตรวจสอบเพื่อยืนยันว่าคุณเป็นเจ้าของ URI ของปลายทาง หากยืนยันไม่สำเร็จ การดำเนินการสร้างและอัปเดตผู้ติดตามจะล้มเหลวพร้อมกับFailedPreconditionException

สร้างผู้ติดตาม

หากต้องการลงทะเบียนผู้ติดตามใหม่สำหรับโปรเจ็กต์ ให้ใช้ปลายทาง create คุณต้องระบุข้อมูลต่อไปนี้

• endpointUri: URL ปลายทางสำหรับการแจ้งเตือนผ่านเว็บฮุค
• subscriberConfigs: ประเภทข้อมูลที่คุณต้องการรับการแจ้งเตือน และนโยบายการสมัครใช้บริการสำหรับแต่ละประเภท
• endpointAuthorization: กลไกการให้สิทธิ์สำหรับปลายทาง ซึ่งต้องมี authorization_token ที่คุณระบุ ระบบจะส่งค่าของ authorization_token ในส่วนหัว Authorization พร้อมกับข้อความแจ้งเตือนแต่ละรายการ คุณสามารถใช้โทเค็นนี้เพื่อยืนยันว่าคำขอขาเข้ามาจาก Google Health API เช่น คุณตั้งค่า authorization_token เป็น Bearer R4nd0m5tr1ng123 สำหรับการตรวจสอบสิทธิ์ Bearer หรือ Basic dXNlcjpwYXNzd29yZA== สำหรับการตรวจสอบสิทธิ์พื้นฐานได้
• subscriberId: ตัวระบุที่ไม่ซ้ำกันซึ่งคุณระบุสำหรับ ผู้ติดตาม รหัสนี้ต้องมีความยาวระหว่าง 4 ถึง 36 อักขระ และตรงกับ นิพจน์ทั่วไป ([a-z]([a-z0-9-]{2,34}[a-z0-9]))

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

ส่งคำขอ

POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
  "endpointUri": "https://myapp.com/webhooks/health",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorization_token": "Bearer example-secret-token"
  }
}

การตอบกลับ

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

แสดงรายการผู้ติดตาม

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

ส่งคำขอ

GET https://health.googleapis.com/v4/projects/project-id/subscribers

การตอบกลับ

{
  "subscribers": [
    {
      "name": "projects/project-id/subscribers/subscriber-id",
      "endpointUri": "https://myapp.com/webhooks/health",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

อัปเดตผู้ติดตาม

ใช้patchปลายทาง เพื่ออัปเดตสมาชิกในโปรเจ็กต์ ช่องที่อัปเดตได้คือ endpointUri, subscriberConfigs และ endpointAuthorization

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

หากคุณอัปเดต endpointUri หรือ endpointAuthorization ระบบจะทำการยืนยันอุปกรณ์ปลายทาง โปรดดูรายละเอียดในหัวข้อการยืนยันอุปกรณ์ปลายทาง

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

ส่งคำขอ

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

การตอบกลับ

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/new-webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

การยืนยันปลายทาง

Google Health API จะดำเนินการจับมือยืนยันแบบ 2 ขั้นตอนที่จำเป็นทุกครั้งที่คุณสร้างผู้ติดตามหรืออัปเดตการกำหนดค่าปลายทาง (endpointUri หรือendpointAuthorization) เพื่อให้มั่นใจถึงความปลอดภัยและความน่าเชื่อถือของการนำส่งการแจ้งเตือน กระบวนการนี้จะดำเนินการแบบซิงโครนัสระหว่างการเรียก API บริการจะส่งคำขอ POST อัตโนมัติ 2 รายการไปยัง URI ของปลายทาง โดยใช้ User-Agent Google-Health-API-Webhooks-Verifier พร้อมกับเนื้อหา JSON {"type": "verification"}

• การแฮนด์เชคที่ได้รับอนุญาต: คำขอแรกจะส่งพร้อมกับส่วนหัว Authorization ที่กำหนดค่าไว้ เซิร์ฟเวอร์ของคุณต้องตอบกลับด้วยสถานะ 200 OK หรือ 201 Created
• การท้าทายที่ไม่ได้รับอนุญาต: คำขอที่ 2 จะส่งโดยไม่มีข้อมูลเข้าสู่ระบบ เซิร์ฟเวอร์ของคุณต้องตอบกลับด้วยสถานะ 401 Unauthorized หรือ 403 Forbidden

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

การหมุนเวียนคีย์

หากต้องการหมุนเวียนคีย์สำหรับ endpointAuthorization ให้ทำตามขั้นตอนต่อไปนี้

1. กำหนดค่าปลายทางให้ยอมรับทั้งendpointAuthorization ค่าเก่าและค่าใหม่
2. อัปเดตการกำหนดค่าผู้ติดตามด้วยค่า endpointAuthorization ใหม่ โดยใช้คำขอ patch ที่มี ?updateMask=endpointAuthorization
3. กำหนดค่าปลายทางให้ยอมรับเฉพาะค่า endpointAuthorization ใหม่ หลังจากยืนยันว่าขั้นตอนที่ 2 สำเร็จแล้ว

ลบผู้ติดตาม

ใช้delete ปลายทางเพื่อนำสมาชิกออกจากโปรเจ็กต์ เมื่อลบแล้ว ผู้ติดตาม จะไม่ได้รับการแจ้งเตือนอีกต่อไป

ส่งคำขอ

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

การตอบกลับ

ระบบจะแสดงเนื้อหาการตอบกลับที่ว่างเปล่าพร้อมสถานะ HTTP `200 OK` หากลบสำเร็จ

{}

การสมัครใช้บริการของผู้ใช้

Google Health API ช่วยให้คุณจัดการการสมัครใช้บริการของผู้ใช้ได้อย่างมีประสิทธิภาพ ซึ่งจะช่วยลดความจำเป็นในการลงทะเบียนด้วยตนเองในระหว่างการเตรียมความพร้อมผู้ใช้งานใหม่

การสมัครใช้บริการอัตโนมัติ

เราขอแนะนำให้ใช้การสมัครใช้บริการอัตโนมัติ หากต้องการเปิดใช้ฟีเจอร์นี้ ให้ตั้งค่า subscriptionCreatePolicy เป็น AUTOMATIC ใน subscriberConfigs สำหรับ ประเภทข้อมูลที่เฉพาะเจาะจง dataTypes ที่คุณระบุด้วยนโยบาย AUTOMATIC จะเป็นประเภทข้อมูลเดียวกันกับที่ Google Health API ส่งการแจ้งเตือน หากผู้ใช้ให้ความยินยอมของผู้ใช้สำหรับประเภทข้อมูลเหล่านั้นด้วย

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

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

การสมัครใช้บริการด้วยตนเอง

หากต้องการจัดการการสมัครใช้บริการสำหรับผู้ใช้แต่ละรายด้วยตนเอง ให้ตั้งค่า subscriptionCreatePolicy เป็น MANUAL ใน subscriberConfigs นโยบายนี้จะทำให้ระบบไม่สร้างการสมัครใช้บริการของผู้ใช้โดยอัตโนมัติ ระบบจะใช้ฟังก์ชันนี้ในอนาคตเมื่อมี API สำหรับจัดการการสมัครใช้บริการด้วยตนเอง พร้อมให้บริการ เราขอแนะนำให้ใช้AUTOMATIC การติดตามจนกว่า API เหล่านี้จะพร้อมใช้งาน

การแจ้งเตือน

เมื่อข้อมูลของผู้ใช้มีการเปลี่ยนแปลงสำหรับประเภทข้อมูลที่สมัครใช้บริการ Google Health API จะส่งคำขอ HTTPS POST ไปยัง URL ปลายทางของผู้สมัครใช้บริการ

รูปแบบการแจ้งเตือน

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

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-0B01:29:00Z",
          "endTime": "2026-03-08T01:34:00Z"
        },
        "civilDateTimeInterval": {
          "startDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 29
            }
          },
          "endDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 34
            }
          }
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-03-07T17:29:00",
          "endTime": "2026-03-07T17:34:00"
        }
      }
    ]
  }
}

ฟิลด์ operation จะระบุประเภทการเปลี่ยนแปลงที่ทริกเกอร์การแจ้งเตือน

• UPSERT: ส่งเมื่อมีการเพิ่มหรือแก้ไขข้อมูล
• DELETE: ส่งเมื่อผู้ใช้ลบข้อมูล หรือเมื่อระบบนำข้อมูลออกเนื่องจาก เหตุการณ์ในระบบ เช่น ผู้ใช้เพิกถอนสิทธิ์หรือลบบัญชี

เราขอแนะนำให้สร้างตรรกะการจัดการการแจ้งเตือนให้เป็นแบบ Idempotent โดยเฉพาะสำหรับการดำเนินการ UPSERT เนื่องจากความพยายามอีกครั้งอาจทำให้ระบบส่งการแจ้งเตือนที่ซ้ำกัน

ฟิลด์ clientProvidedSubscriptionName เป็นตัวระบุที่ไม่ซ้ำกัน สำหรับ การติดตามที่มีMANUALนโยบาย ฟิลด์นี้จะมีชื่อการติดตามที่คงอยู่ซึ่งนักพัฒนาแอปเป็นผู้ระบุเมื่อสร้างการติดตาม ซึ่งจะให้รหัสที่เสถียรสำหรับการจัดการการสมัครใช้บริการด้วยตนเอง สำหรับการสมัครใช้บริการที่สร้างขึ้นด้วยนโยบาย AUTOMATIC Google Health API จะสร้างและกำหนดตัวระบุที่ไม่ซ้ำกัน (UUID แบบสุ่ม) ให้กับฟิลด์นี้โดยอัตโนมัติสำหรับแต่ละการแจ้งเตือน การรวม clientProvidedSubscriptionName สำหรับทั้งนโยบายแบบกำหนดเองและแบบอัตโนมัติ จะช่วยให้มั่นใจได้ว่ารูปแบบเพย์โหลดการแจ้งเตือนจะสอดคล้องกันใน การสมัครใช้บริการทุกประเภท

healthUserId คือตัวระบุ Google Health API สำหรับผู้ใช้ที่มี การเปลี่ยนแปลงข้อมูล หากแอปพลิเคชันรองรับผู้ใช้หลายราย คุณอาจได้รับการแจ้งเตือนสำหรับผู้ใช้ที่ให้ความยินยอมแก่แอปพลิเคชัน เมื่อได้รับ การแจ้งเตือน ให้ใช้ healthUserId เพื่อระบุข้อมูลของผู้ใช้รายใดที่มีการเปลี่ยนแปลง เพื่อให้คุณใช้ข้อมูลเข้าสู่ระบบ OAuth ของผู้ใช้เพื่อค้นหาข้อมูลได้

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

ตอบกลับการแจ้งเตือน

เซิร์ฟเวอร์ของคุณต้องตอบกลับการแจ้งเตือนด้วยรหัสสถานะ HTTP 204 No Content ทันที ประมวลผลเพย์โหลดการแจ้งเตือนแบบไม่พร้อมกันหลังจากส่งการตอบกลับเพื่อหลีกเลี่ยงการหมดเวลา หาก Google Health API ได้รับรหัสสถานะอื่นๆ หรือคำขอหมดเวลา ระบบจะลองส่งการแจ้งเตือนอีกครั้งในภายหลัง

ตัวอย่าง Node.js (Express)

app.post('/webhook-receiver', (req, res) => {
    // 1. Immediately acknowledge the notification
    res.status(204).send();

    // 2. Process the data asynchronously in the background
    const notification = req.body;
    setImmediate(() => {
        console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
        // Trigger your data retrieval logic here
    });
});

สถานะผู้ติดตามและการกู้คืน

หากปลายทางของผู้ติดตามไม่พร้อมใช้งานหรือแสดงรหัสสถานะข้อผิดพลาด (รหัสอื่นที่ไม่ใช่ 204) Google Health API จะจัดเก็บการแจ้งเตือนที่รอดำเนินการไว้ไม่เกิน 7 วัน และจะลองส่งอีกครั้งโดยใช้ Exponential Backoff

เมื่ออุปกรณ์ปลายทางกลับมาออนไลน์และตอบกลับด้วย 204 แล้ว API จะส่งข้อความที่ค้างไว้ซึ่งจัดเก็บไว้โดยอัตโนมัติ ระบบจะทิ้งการแจ้งเตือนที่เก่ากว่า 7 วันและกู้คืนไม่ได้