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

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

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

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

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

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

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

บัญชีบริการ IAM

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

  • ข้อมูลเข้าสู่ระบบแบบมีอายุสั้นที่สร้างขึ้นโดยอัตโนมัติ: เมื่อแนบกับสภาพแวดล้อมการดำเนินการของ Google Cloud (เช่น Compute Engine, Cloud Run หรือ Google Kubernetes Engine) บัญชีบริการจะรับและหมุนเวียนข้อมูลเข้าสู่ระบบแบบมีอายุสั้นที่ปลอดภัยโดยอัตโนมัติ ซึ่งจะช่วยลดความเสี่ยงในการจัดการและจัดเก็บ คีย์แบบคงที่ถาวร
  • หลักการให้สิทธิ์ขั้นต่ำที่สุด: บัญชีบริการจะให้ข้อมูลประจำตัวเฉพาะสำหรับเวิร์กโหลด คุณสามารถให้สิทธิ์เฉพาะที่จำเป็นต่อการจัดการปลายทางของผู้ติดตามได้ เพื่อหลีกเลี่ยงการเข้าถึงทรัพยากร Google Cloud ในวงกว้าง
  • อายุการใช้งานที่ไม่ขึ้นต่อกัน: บัญชีบริการจะทำงานโดยไม่ขึ้นอยู่กับบัญชีของผู้ใช้แต่ละราย เพื่อให้มั่นใจว่าการเปลี่ยนแปลงบุคลากรจะไม่ส่งผลต่อ ความเสถียรของการตรวจสอบสิทธิ์ในระยะยาว

สร้างบัญชีบริการ

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

  1. สร้างบัญชีบริการ: ในคอนโซล Google Cloud ให้ไปที่หน้า IAM และผู้ดูแลระบบของโปรเจ็กต์เพื่อสร้างบัญชีบริการใหม่ที่ผู้ใช้จัดการ
  2. มอบบทบาท IAM ที่จำเป็น: มอบหมายบทบาทที่เหมาะสมให้กับบัญชีบริการ ที่จำเป็นต่อการจัดการผู้ติดตามในโปรเจ็กต์ที่อยู่ในระบบคลาวด์ Google
  3. แนบบัญชีบริการกับภาระงาน: กำหนดค่าสภาพแวดล้อมที่โฮสต์ตรรกะของผู้สมัครใช้บริการให้ทำงานเป็นบัญชีบริการใหม่ ซึ่งจะช่วยให้โค้ดแอปพลิเคชัน (เช่น ไลบรารีของไคลเอ็นต์ Google API) ตรวจหาและใช้ข้อมูลเข้าสู่ระบบแบบมีอายุสั้นของบัญชีบริการโดยอัตโนมัติได้ เมื่อเรียกใช้ projects.subscribers REST API

บทบาท CPE

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

  • อ่าน Google Health API
  • ผู้แก้ไข Google Health API
  • ผู้ดูแลระบบ Google Health API

ดูข้อมูลเพิ่มเติมเกี่ยวกับบทบาทและสิทธิ์ IAM ของ Google Health API

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

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

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

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

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

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

ใน 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": {
    "secret": "Bearer example-secret-token"
  }
}

การตอบกลับ

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

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

ใช้ปลายทาง 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",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "totalSize": 1
}

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

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

คุณอัปเดตฟิลด์ได้โดยระบุupdateMaskพารามิเตอร์การค้นหาและเนื้อหาคำขอ updateMask ต้องมีรายการชื่อฟิลด์ที่คั่นด้วยคอมมาซึ่งคุณต้องการอัปเดต โดยใช้รูปแบบ Camel Case สำหรับชื่อฟิลด์ (เช่น endpointUri) เนื้อหาคำขอต้องมีออบเจ็กต์ Subscriber บางส่วน ที่มีค่าใหม่สำหรับฟิลด์ที่คุณต้องการอัปเดต ระบบจะอัปเดตเฉพาะฟิลด์ที่ระบุ ใน 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",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ]
}

ลบผู้ติดตาม

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

ส่งคำขอ

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

การตอบกลับ

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

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

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 สำเร็จแล้ว

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

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

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

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

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

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

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

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

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

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

เมื่อข้อมูลของผู้ใช้มีการเปลี่ยนแปลงสำหรับประเภทข้อมูลที่สมัครใช้บริการ 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-08T01: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
    });
});

การยืนยันลายเซ็น

เพื่อให้มั่นใจในความถูกต้องของการแจ้งเตือน Webhook ระบบจะลงนามเพย์โหลด JSON ดิบของการแจ้งเตือน Webhook ขาออกทุกรายการด้วยคีย์ส่วนตัวโดยใช้ PublicKeySign ของ Tink โดยระบุลายเซ็นที่เข้ารหัส Base64 ในส่วนหัว GOOGLE-HEALTH-API-SIGNATURE HTTP ในการขอ ระบบจะหมุนเวียนคีย์การลงนามเหล่านี้โดยอัตโนมัติทุกๆ 30 วัน และจะเผยแพร่ชุดคีย์สาธารณะอย่างเป็นทางการที่เกี่ยวข้องเป็นไฟล์ JSON ที่ URL ถาวร https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json

วิธียืนยันลายเซ็น

การใช้ Tink (แนะนํา): นักพัฒนาแอปสามารถยืนยันลายเซ็นได้โดยใช้ PublicKeyVerify Primitive ของ Tink ดึงข้อมูลชุดคีย์สาธารณะจาก URL ถาวร สร้างอินสแตนซ์ Primitive ของ PublicKeyVerify ด้วยชุดคีย์ และยืนยันส่วนหัวGOOGLE-HEALTH-API-SIGNATUREที่ถอดรหัสแล้วกับเพย์โหลด JSON ของ Webhook ดิบ

การยืนยันด้วยตนเอง (ไม่ใช้ Tink): หากนักพัฒนาแอปเลือกที่จะไม่ใช้ Tink ก็สามารถยืนยันลายเซ็นด้วยตนเองได้โดยทำตามขั้นตอนต่อไปนี้

  1. ถอดรหัส Base64 ของส่วนหัว GOOGLE-HEALTH-API-SIGNATURE เพื่อแยก คำนำหน้า Tink ขนาด 5 ไบต์ (ซึ่งมีคำนำหน้าเวอร์ชันขนาด 1 ไบต์และ keyId ขนาด 4 ไบต์) ออกจากลายเซ็นที่เข้ารหัส DER จริง
  2. ดึงชุดคีย์ JSON จาก https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json
  3. ค้นหาคีย์ที่ตรงกับ keyId ที่แยกวิเคราะห์แล้วและถอดรหัส Base64 ของฟิลด์ค่า ซึ่งมี Protocol Buffer ของ EcdsaPublicKey ที่ซีเรียลไลซ์แล้ว
  4. แยกพิกัด x และ y แบบ Big-Endian (แท็ก Protobuf 3 และ 4) จาก เพย์โหลดไบนารีนี้
  5. สร้างอินสแตนซ์คีย์สาธารณะ ECDSA P-256 มาตรฐานในไลบรารีวิทยาการเข้ารหัสที่ติดตั้งมา โดยใช้พิกัด x และ y ที่แยกออกมา
  6. ยืนยันเพย์โหลด JSON ของเว็บฮุกดิบกับลายเซ็น DER ที่แยกออกมา โดยใช้อัลกอริทึม SHA-256

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

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

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

ข้อผิดพลาดที่พบบ่อย

รหัสข้อผิดพลาด ข้อความ คำอธิบาย คำแนะนำ
400 คำขอไม่ถูกต้อง หมายเลขโปรเจ็กต์ในชื่อทรัพยากรไม่ถูกต้อง เมื่อลบหรืออัปเดตผู้ติดตามโดยใช้รหัสโปรเจ็กต์ที่อยู่ในระบบคลาวด์ของ Google ใน URL ของคำขอแทนหมายเลขโปรเจ็กต์ ซึ่งมีผลกับการสมัครใช้บริการ Webhook โดยใช้ปลายทาง projects.subscribers ใช้หมายเลขโปรเจ็กต์ Google Cloud ใน URL ของคำขอ ไม่ใช่รหัสโปรเจ็กต์
403 ต้องห้าม ผู้โทรไม่มีสิทธิ์ เมื่อสร้างหรือแสดงรายชื่อผู้ติดตามโดยใช้รหัสโปรเจ็กต์ Google Cloud ใน URL ของคำขอแทนหมายเลขโปรเจ็กต์ ซึ่งใช้กับการสมัครใช้บริการ Webhook โดยใช้ปลายทาง projects.subscribers ใช้หมายเลขโปรเจ็กต์ Google Cloud ใน URL ของคำขอ ไม่ใช่รหัสโปรเจ็กต์

ก่อนหน้า
Universal Link และ App Link
ถัดไป
การแก้ปัญหา