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

Google Health API ช่วยให้แอปพลิเคชันของคุณรับการแจ้งเตือนแบบเรียลไทม์ได้เมื่อข้อมูลสุขภาพของผู้ใช้มีการเปลี่ยนแปลง โดยเซิร์ฟเวอร์ของคุณจะได้รับเว็บฮุคคำขอ HTTPS POST ทันทีที่ข้อมูลพร้อมใช้งานใน 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 Cloud ให้กับบัญชีบริการ
  3. แนบบัญชีบริการกับเวิร์กโหลด: กำหนดค่าสภาพแวดล้อมที่โฮสต์ตรรกะของผู้ติดตามให้ทำงานเป็นบัญชีบริการใหม่ ซึ่งจะช่วยให้โค้ดแอปพลิเคชัน (เช่น ไลบรารีของไคลเอ็นต์ Google API) ตรวจหาและใช้ข้อมูลเข้าสู่ระบบแบบชั่วคราวของบัญชีบริการโดยอัตโนมัติเมื่อเรียกใช้ REST API projects.subscribers

บทบาท 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: หมายเลขโปรเจ็กต์ที่สร้างบัญชีบริการเว็บฮุค
  • 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== สำหรับการตรวจสอบสิทธิ์แบบ Basic

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

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

หากผู้ติดตามได้รับการกำหนดค่าด้วย subscription_create_policy เป็น MANUAL สำหรับประเภทข้อมูลที่เฉพาะเจาะจง คุณต้องสร้างและจัดการการสมัครใช้บริการสำหรับผู้ใช้แต่ละรายอย่างชัดเจน การสมัครใช้บริการจะลิงก์ผู้ใช้ที่เฉพาะเจาะจงกับปลายทางของผู้ติดตามสำหรับชุดประเภทข้อมูลที่กำหนด นักพัฒนาแอปสามารถใช้ 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
    });
});

แนวทางปฏิบัติแนะนำ

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

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

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

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

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

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

การยืนยันด้วยตนเอง (ไม่ต้องใช้ 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 ของคำขอแทนหมายเลขโปรเจ็กต์ ซึ่งใช้กับการสมัครใช้บริการเว็บฮุคโดยใช้ปลายทาง projects.subscribers ใช้หมายเลขโปรเจ็กต์ Google Cloud ใน URL ของคำขอ ไม่ใช่รหัสโปรเจ็กต์
403 ต้องห้าม ผู้เรียกไม่มีสิทธิ์ เมื่อสร้างหรือแสดงรายการผู้ติดตามโดยใช้รหัสโปรเจ็กต์ Google Cloud ใน URL ของคำขอแทนหมายเลขโปรเจ็กต์ ซึ่งใช้กับการสมัครใช้บริการเว็บฮุคโดยใช้ปลายทาง projects.subscribers ใช้หมายเลขโปรเจ็กต์ Google Cloud ใน URL ของคำขอ ไม่ใช่รหัสโปรเจ็กต์

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