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

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

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

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

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

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

  • กิจกรรม ซึ่งครอบคลุมประเภทข้อมูลขั้นตอน ระดับความสูง ระยะทาง และชั้น
    • 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: หมายเลขโปรเจ็กต์ที่สร้างบัญชีบริการ Webhook
  • subscriberId: ตัวระบุที่ไม่ซ้ำกันที่คุณระบุสำหรับผู้ติดตาม รหัสนี้ต้องมีความยาวระหว่าง 4 ถึง 36 อักขระ และตรงกับนิพจน์ทั่วไป ([a-z]([a-z0-9-]{2,34}[a-z0-9]))
  • endpointUri: URL ปลายทางสำหรับการแจ้งเตือน Webhook
  • 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 ต้องมีรายการที่คั่นด้วยคอมมาของชื่อช่องที่คุณต้องการอัปเดต โดยใช้การเขียนแบบ 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 เป็นผู้จัดการการสมัครใช้บริการอัตโนมัติ และคุณจะแสดงรายการหรือลบการสมัครใช้บริการแต่ละรายการไม่ได้ โดยระบบจะนำการสมัครใช้บริการออกก็ต่อเมื่อลบผู้ติดตามหลักเท่านั้น

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

หากผู้ติดตามได้รับการกำหนดค่าด้วย 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
    });
});

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

ระบบจะลงชื่อเพย์โหลด JSON ดิบของการแจ้งเตือน Webhook ขาออกทุกรายการด้วยคีย์ส่วนตัวโดยใช้ PublicKeySign ของ Tink เพื่อให้มั่นใจในความถูกต้องของการแจ้งเตือน Webhook โดยระบุลายเซ็นที่เข้ารหัส 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 ของ 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 ช่องค่า ซึ่งมีบัฟเฟอร์โปรโตคอล EcdsaPublicKey ที่ซีเรียลไลซ์แล้ว
  4. แยกพิกัด x และ y แบบ Big-Endian (แท็ก Protobuf 3 และ 4) ออกจากเพย์โหลดไบนารีนี้
  5. สร้างอินสแตนซ์คีย์สาธารณะ ECDSA P-256 มาตรฐานในไลบรารีวิทยาการเข้ารหัสลับในตัวโดยใช้พิกัด x และ y ที่แยกออกมา
  6. ยืนยันเพย์โหลด JSON ของ Webhook ดิบกับลายเซ็น 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
ถัดไป
การแก้ปัญหา