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

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

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

Webhook Notifications รองรับประเภทข้อมูลต่อไปนี้

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

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

• กิจกรรม ซึ่งครอบคลุมประเภทข้อมูลขั้นตอน ระดับความสูง ระยะทาง และชั้น
  • 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== สำหรับการตรวจสอบสิทธิ์พื้นฐาน

ใน 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 ขาออกทุกรายการด้วยคีย์ส่วนตัวโดยใช้ Tink's PublicKeySign เพื่อให้มั่นใจในความถูกต้องของการแจ้งเตือน 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 วันและกู้คืนไม่ได้

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

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

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