การทำงานกับข้อมูลใน Google Health API มีวงจรหลักคือการซิงค์ข้อมูล ระหว่างที่เก็บข้อมูล Google Health API ในระบบคลาวด์กับแอปหรือ ที่เก็บข้อมูลแบ็กเอนด์ของคุณเอง อย่างไรก็ตาม วงจรนี้อาจมีรูปแบบที่แตกต่างกันไปตามปัจจัยต่างๆ ดังนี้
- คุณกำลังเขียนข้อมูลไปยัง Google Health API ใช่ไหม อ่านอย่างเดียวใช่ไหม หรือทั้งสองอย่าง
- ที่เก็บข้อมูลของคุณอยู่ในเครื่องในแอปหรืออุปกรณ์ใช่ไหม หรือในระบบคลาวด์ของคุณเอง
- คุณต้องการซิงค์ข้อมูล Google Health API ระหว่างแอปของผู้ใช้กับ อุปกรณ์ที่สวมใส่ได้ไหม คุณซิงค์อุปกรณ์บ่อยแค่ไหน
- คุณกำลังทำงานกับข้อมูลประเภทใด การนับคะแนนพื้นฐาน หน่วยวัด อนุกรมที่มีอัตราการสุ่มตัวอย่างแตกต่างกัน
- คุณวางแผนที่จะอ่านข้อมูลขณะที่แอปทำงานอยู่ในเบื้องหลังหรือไม่
- คุณวางแผนที่จะใช้ข้อมูลย้อนหลังที่บันทึกไว้ก่อนที่แอปจะได้รับสิทธิ์จากผู้ใช้หรือไม่
หากต้องการทำความเข้าใจว่าทุกอย่างทำงานร่วมกันอย่างไร โปรดดูวงจรการซิงค์ของ Google Health API วงจรการใช้งานนี้มี 2 เวอร์ชัน ได้แก่ มาตรฐาน (อ่านและเขียน) และอ่านอย่างเดียว
วงจรการซิงค์มาตรฐาน
การผสานรวมกับ Google Health API หมายถึงการคัดลอกข้อมูลไปยังแอปหรือ ที่เก็บข้อมูลแบ็กเอนด์ เพื่อความสะดวกในการใช้งานในเอกสารประกอบนี้ เราจะเรียกที่เก็บข้อมูลนี้ว่าที่เก็บข้อมูลของนักพัฒนาซอฟต์แวร์
"คัดลอก" ในที่นี้สามารถแทนที่กิจกรรมที่ไม่ต่อเนื่องใดๆ ได้ เช่น การอ่านจาก Google Health API (การคัดลอกไปยังที่เก็บข้อมูลของนักพัฒนาซอฟต์แวร์) หรือการเขียนไปยัง Google Health API (การคัดลอกไปยัง Google Health API) การดำเนินการเหล่านี้ ซ้ำๆ ตามลำดับที่เฉพาะเจาะจงคือวงจรการซิงค์
รูปที่ 1 แสดงวงจรการซิงค์มาตรฐานที่เกี่ยวข้องกับการอ่านและการเขียน โดยไม่คำนึงถึงปัจจัยใดๆ ที่กล่าวถึงก่อนหน้านี้
เขียน
- เตรียมข้อมูลใหม่สำหรับการเขียน - โอนข้อมูลจากอุปกรณ์หรือแอปภายนอก และจัดรูปแบบจุดข้อมูลให้เป็นการแสดง JSON ที่เข้ากันได้กับประเภทข้อมูล Google
Health API โปรดทราบว่าขณะนี้ Health API ไม่รองรับรหัสที่กำหนดเองซึ่งไคลเอ็นต์กำหนดสำหรับการเขียน คุณอาจระบุรหัสดังกล่าวใน
POSTแต่ระบบจะไม่นำมาพิจารณา - แทรก/อัปเดตระเบียน - ส่งจุดข้อมูลไปยัง Google Health API โดยใช้
ปลายทาง REST ใช้
POSTเพื่อสร้างระเบียน และPATCHเพื่อแทรก และอัปเดตระเบียนที่มีอยู่ รหัสที่จำเป็นสำหรับการดำเนินการPATCHจะมาจาก การดำเนินการPOSTก่อนหน้า (ขั้นตอนถัดไปในรอบก่อนหน้า) - ประมวลผลรหัสทรัพยากรที่ส่งคืน - เมื่อใช้รหัสที่สร้างขึ้นฝั่งเซิร์ฟเวอร์ ให้ดึงข้อมูล
และบันทึกทรัพยากร
nameหรือรหัสที่เซิร์ฟเวอร์ส่งคืนในที่เก็บข้อมูลของนักพัฒนาแอป เพื่อเปิดใช้การอัปเดต (PATCH) หรือการลบ (DELETE) ในอนาคต ดูข้อมูลเพิ่มเติมเกี่ยวกับรหัส 2 ประเภทได้ที่กลยุทธ์การระบุ
อ่าน
- อ่านระเบียน - ดึงข้อมูลใหม่และการเปลี่ยนแปลงข้อมูลที่มีอยู่จาก
Google Health API โดยใช้ปลายทาง REST (
GETพร้อมพารามิเตอร์การค้นหาfilterและpageTokenการแบ่งหน้า หรือปลายทางการรวบรวม เช่นrollUpและdailyRollUp) หรือรับการแจ้งเตือนแบบเรียลไทม์โดยใช้การสมัครใช้บริการ Webhook (projects.subscribers) การแจ้งเตือนจะระบุว่ามีข้อมูลใหม่ พร้อมใช้งานเท่านั้น ไม่ใช่ข้อมูลจริง - กระทบยอดที่เก็บข้อมูลของนักพัฒนาแอป - กระทบยอดข้อมูลใหม่และข้อมูลที่อัปเดตกับ ที่เก็บข้อมูลของนักพัฒนาแอป อุปกรณ์ที่เชื่อมต่ออาจสร้างช่วงเวลาที่ทับซ้อนกัน ระหว่างการซิงค์ ดูวิธีที่ Google Health API แก้ปัญหาเหล่านี้ได้ที่การประทับเวลาช่วงเวลาและการซิงค์อุปกรณ์ที่เชื่อมต่อ
จากนั้นวงจรนี้จะทำซ้ำตามช่วงเวลาที่เหมาะสมตามความต้องการเฉพาะ ของอุปกรณ์หรือแอปภายนอก โดยทั่วไปแล้ว เราขอแนะนำให้คุณ ซิงค์ข้อมูลระหว่างที่เก็บข้อมูลของคุณเองกับ Google Health API ตามลำดับนี้
กลยุทธ์การระบุ
หากต้องการเขียนข้อมูลไปยัง Google Health API ก่อนที่จะสร้างการผสานรวมกับ Google Health API คุณต้องเลือกกลยุทธ์การระบุทรัพยากรเมื่อสร้างจุดข้อมูล (หน่วยข้อมูลพื้นฐาน)
ขณะนี้ Health API ยังไม่รองรับรหัสที่ไคลเอ็นต์กำหนดสำหรับการเขียน
คุณอาจระบุรหัสดังกล่าวใน POST แต่ระบบจะไม่นำมาพิจารณา รายละเอียดเกี่ยวกับตัวเลือกนี้
มีไว้ที่นี่เพื่อวัตถุประสงค์ในการให้ข้อมูล
- รหัสที่เซิร์ฟเวอร์สร้างขึ้น (ตัวเลือกเริ่มต้น): ไคลเอ็นต์ส่งข้อมูลโดยไม่มีรหัส และแบ็กเอนด์ของ Google Health API จะสร้างและส่งคืนตัวระบุระบบที่ไม่ซ้ำกัน
- รหัสที่กำหนดเองที่ไคลเอ็นต์กำหนด (ตาม AIP-133 ยังไม่รองรับ): แอปไคลเอ็นต์จะสร้างตัวระบุที่ไม่ซ้ำกัน (เช่น UUID หรือคีย์หลักของฐานข้อมูลในเครื่อง) และระบุในเส้นทางทรัพยากรเมื่อสร้าง
ตารางต่อไปนี้เปรียบเทียบกลยุทธ์การระบุทั้ง 2 แบบเพื่อช่วยคุณเลือก แนวทางที่เหมาะสมสำหรับการผสานรวม
| ฟีเจอร์ | รหัสที่เซิร์ฟเวอร์สร้างขึ้น | รหัสที่กำหนดเองซึ่งไคลเอ็นต์กำหนด |
|---|---|---|
| การสร้างรหัส | เซิร์ฟเวอร์จะสร้างรหัสระบบแบบสุ่มในระหว่างการดำเนินการ POST
|
ไคลเอ็นต์สร้างรหัสที่เสถียรในเครื่อง (UUID v4 / PK ภายใน) ก่อนเขียน |
| เส้นทางทรัพยากร | .../dataPoints/{server_id} (ส่งคืนในการตอบกลับ) |
.../dataPoints/{custom_id} |
| ขั้นตอนหลังการเขียนในเครื่อง | ต้องระบุ ต้องจัดเก็บ server_id ที่ส่งคืนใน DB ในเครื่อง
เพื่อเปิดใช้การอัปเดต/การลบในอนาคต |
ไม่มี แอปเป็นเจ้าของรหัสอยู่แล้ว |
| ตารางการจับคู่รหัส | ต้องระบุ ไคลเอ็นต์ต้องรักษาการจับคู่แบบ 2 ทาง
(local_id ↔ server_id) |
ไม่จำเป็น ไคลเอ็นต์ใช้คีย์หลักของตัวเองโดยตรง |
| ลักษณะการลองใหม่ (เครือข่ายอ่อน) | ความเสี่ยงที่จะเกิดรายการที่ซ้ำกัน การลองPOST
ที่หมดเวลาอีกครั้งจะสร้างระเบียนที่ซ้ำกันโดยมีรหัสเซิร์ฟเวอร์ใหม่ |
ปลอดภัยและทำซ้ำได้ การลองอีกครั้งPOSTด้วย
custom_idเดิมจะป้องกันการสร้างซ้ำ (แสดงผล 409
ALREADY_EXISTS) |
| การรองรับการซิงค์แบบออฟไลน์ | จำกัด ต้องรอการตอบกลับจากเซิร์ฟเวอร์เพื่อรับรหัสทรัพยากรอย่างเป็นทางการ ก่อนที่จะอ้างอิง | เต็ม คุณสร้างและเปลี่ยนแปลงเอนทิตีแบบออฟไลน์ได้โดยใช้รหัสที่เสถียร จากนั้นจะซิงค์ได้อย่างราบรื่นเมื่อเชื่อมต่ออีกครั้ง |
| ข้อจำกัดด้านรูปแบบ | จัดการโดยเซิร์ฟเวอร์ทั้งหมด | ต้องเป็นไปตามรูปแบบ ^[a-z0-9-]{4,63}$ (ตัวอักษรพิมพ์เล็ก ตัวอักษรและตัวเลขคละกัน และขีดกลาง 4-63 ตัว) |
| กรณีที่ควรเลือก |
เลือกรหัสที่เซิร์ฟเวอร์สร้างขึ้นในกรณีต่อไปนี้
|
เลือกรหัสที่กำหนดเองในกรณีต่อไปนี้
|
วงจรการซิงค์แบบอ่านอย่างเดียว
แอปที่ต้องการอ่านจาก Google Health API เท่านั้นต้องคัดลอกข้อมูลไปยังที่เก็บข้อมูลของนักพัฒนาแอปและจัดการส่วนการกระทบยอดของวงจร
งานเดียวกันกับที่กล่าวถึงในส่วนอ่านจะใช้ได้ที่นี่
รูปที่ 2 แสดงวงจรแบบอ่านอย่างเดียว
การประทับเวลาช่วงการฝึกและการซิงค์อุปกรณ์ที่เชื่อมต่อ
ข้อมูลช่วงเวลาแสดงถึงการวัดที่รวบรวมในช่วงระยะเวลาหนึ่ง เช่น จำนวนก้าว อัตราการเต้นของหัวใจ หรือเซสชันการออกกำลังกาย ในทางตรงกันข้าม การวัดแบบเฉพาะจุด รวมถึงรายการที่ป้อนด้วยตนเอง เช่น บันทึกอาหารหรือการอ่านค่าจากเครื่องชั่ง โดยปกติแล้วข้อมูลช่วงเวลาจะมาจากการซิงค์อุปกรณ์ที่เชื่อมต่อ เช่น สมาร์ทวอทช์ และเครื่องติดตามการออกกำลังกาย
การประทับเวลาช่วง (startTime และ endTime) จะทำให้เกิดลักษณะการทำงานที่ไม่ซ้ำกัน
เมื่อทำงานกับข้อมูลช่วง ส่วนนี้จะอธิบายสาเหตุที่ช่วงเวลาทับซ้อนกันเกิดขึ้น และเปรียบเทียบปลายทาง list กับ reconcile
ช่วงเวลาที่ทับซ้อนกันจากอุปกรณ์ที่เชื่อมต่อ
อุปกรณ์ที่เชื่อมต่อ เช่น อุปกรณ์ติดตาม Fitbit และ Google Pixel Watch จะ รวบรวมค่าไบโอเมตริกความถี่สูงอย่างต่อเนื่องขณะสวมใส่ หลังจากที่อุปกรณ์ซิงค์จุดข้อมูล กับ Google Health แล้ว ระบบจะไม่เปลี่ยนแปลงบันทึกที่มีอยู่เหล่านั้นย้อนหลัง โดยการประทับเวลาช่วงเวลาที่จัดเก็บไว้จะยังคงเหมือนเดิม
อย่างไรก็ตาม ก่อนรอบการซิงค์ครั้งต่อๆ ไป อัลกอริทึมในอุปกรณ์มักจะตีความข้อมูลการวัดและส่งจากเซ็นเซอร์ดิบอีกครั้ง อุปกรณ์จะจัดกลุ่มการอ่านที่รวบรวมในช่วง 24 ชั่วโมงที่ผ่านมาใหม่ เมื่ออุปกรณ์ซิงค์อีกครั้ง อุปกรณ์จะอัปโหลดจุดข้อมูลใหม่ ขอบเขตเริ่มต้นและสิ้นสุดของช่วงเวลาดังกล่าวอาจทับซ้อนกับช่วงเวลาที่จัดเก็บไว้ก่อนหน้านี้
ตัวอย่างเช่น ลองพิจารณาผู้ใช้ที่สวมสมาร์ทวอทช์ซึ่งซิงค์ข้อมูลกิจกรรม ใน 2 แบตช์ติดต่อกัน
- ในระหว่างการซิงค์ครั้งแรก อุปกรณ์จะอัปโหลดจุดข้อมูลที่ครอบคลุมตั้งแต่
10:00:00Zถึง10:14:59Z - หลังจากการคำนวณใหม่ในอุปกรณ์ การซิงค์ครั้งที่ 2 จะอัปโหลดจุดข้อมูลอีกจุดหนึ่ง
ซึ่งครอบคลุมตั้งแต่
10:14:00Zถึง10:28:59Z
ระบบจะจัดเก็บบันทึกทั้ง 2 รายการแยกกันในแบ็กเอนด์ของ Google Health ด้วยเหตุนี้ จุดข้อมูลทั้ง 2 จุดจึงครอบคลุมช่วงเวลาตั้งแต่ 10:14:00Z ถึง 10:14:59Z
ซึ่งจะทำให้เกิดการทับซ้อน 59 วินาทีเมื่อค้นหาระเบียนดิบ
เปรียบเทียบรายการและปลายทางการกระทบยอด
คุณจัดการช่วงเวลาที่ทับซ้อนกันเหล่านี้ได้โดยใช้ list หรือ
reconcile เลือกปลายทางที่ตรงกับข้อกำหนดของแอปพลิเคชัน
| ฟีเจอร์ | list อุปกรณ์ปลายทาง |
reconcile อุปกรณ์ปลายทาง |
|---|---|---|
| เมธอด HTTP | GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/<var>dataType</var>/dataPoints:reconcile |
| ลักษณะการทำงานของการทับซ้อน | แสดงระเบียนที่จัดเก็บทั้งหมดเป็นระเบียนที่อัปโหลดโดยไม่มีการลบข้อมูลที่ซ้ำกัน เมื่อช่วงเวลาทับซ้อนกัน ระบบจะแสดงทั้ง 2 ระเบียน | แก้ไขความขัดแย้งและนำระเบียนที่ซ้ำกันออกในอุปกรณ์และเซสชันการซิงค์ต่างๆ เพื่อให้เป็นสตรีมต่อเนื่องรายการเดียว |
| ข้อดี | แสดงเส้นทางการตรวจสอบที่สมบูรณ์และไม่มีการแก้ไขของทุกระเบียนที่อุปกรณ์แต่ละเครื่องและชุดการซิงค์อัปโหลด | ช่วยให้การแสดงผลไทม์ไลน์และการคำนวณระยะเวลาเป็นเรื่องง่ายด้วยการจัดการช่วงเวลาที่ทับซ้อนกันและความขัดแย้งในอุปกรณ์หลายเครื่องโดยอัตโนมัติ |
| ข้อเสีย | แอปพลิเคชันของคุณมีหน้าที่ตรวจหาและแก้ไขช่วงเวลาที่ทับซ้อนกัน ความขัดแย้งในอุปกรณ์หลายเครื่อง และช่วงเวลาที่ไม่ได้สวมใส่อุปกรณ์ | ระบบจะละเว้นระเบียนที่ซ้อนทับกันในระดับรองจากการตอบกลับ ดังนั้นจึงไม่สามารถตรวจสอบกลุ่มการซิงค์อุปกรณ์แต่ละรายการแยกกันได้ |
reconcile Endpoint ออกแบบมาเพื่อวาดอินเทอร์เฟซผู้ใช้ แสดงไทม์ไลน์กิจกรรม และคำนวณผลรวมของระยะเวลาที่ไม่ทับซ้อนกัน ซึ่งจะแก้ไขช่วงเวลาที่ขัดแย้งกันจากเซสชันการซิงค์ที่จัดกลุ่มใหม่ นอกจากนี้ ยังช่วยปรับกิจกรรมที่บันทึกพร้อมกันในอุปกรณ์หลายเครื่อง เช่น นาฬิกาและโทรศัพท์ ให้ตรงกันด้วย
การกระทบยอดจะแก้ไขเซสชันที่ขัดแย้งกันโดยเลือกบันทึกที่เชื่อถือได้
แทนที่จะสังเคราะห์การรวมเวลาเทียม เช่น ระบบจะไม่รวม 11:00:00Z กับ 11:30:00Z และ 11:20:00Z กับ 11:50:00Z เป็น 11:00:00Z กับ 11:50:00Z การตอบกลับที่ปรับแล้วจะแสดงจุดข้อมูลที่ชนะ
พร้อมช่วงเวลาที่บันทึกไว้เดิม ซึ่งจะรักษาความสมบูรณ์ของ
การวัดระยะไกลและเมตริกของเซสชันนั้น
รูปที่ 3 แสดงวิธีที่ปลายทาง reconcile จัดการเซสชันที่ทับซ้อนกัน
โดยจะเลือกบันทึกที่เชื่อถือได้แทนที่จะสร้างการรวมเวลาเทียม
คู่มือเกี่ยวกับปลายทางมีตัวอย่างคำขอและการตอบกลับที่สมบูรณ์ หากต้องการเปรียบเทียบ
ระเบียนlistดิบกับreconcileเอาต์พุต โปรดดู
ดูข้อมูลช่วงเวลาที่ปรับแล้ว
list ออกแบบมาสำหรับการวินิจฉัยอุปกรณ์และการตรวจสอบข้อมูล ใช้เมื่อเวิร์กโฟลว์ของคุณต้องตรวจสอบบันทึกที่ไม่มีการแก้ไขตามที่อัปโหลดโดยอุปกรณ์แต่ละเครื่อง เมื่อทำการค้นหาด้วย list ตรรกะของไคลเอ็นต์ต้องจัดการการทับซ้อนของช่วงเวลาในข้อมูลดิบ
การเปลี่ยนแปลงการประทับเวลาและการอัปเดตเจ้าของ
อุปกรณ์ที่เชื่อมต่อจะไม่แก้ไขการประทับเวลาที่จัดเก็บย้อนหลังในระหว่างรอบการซิงค์ปกติ
อย่างไรก็ตาม แสตมป์เวลาของช่วง (startTime และ endTime) ไม่ได้
เปลี่ยนแปลงไม่ได้ในทุกแหล่งข้อมูล มีเพียงผู้สร้างหรือเจ้าของระเบียนเดิมเท่านั้นที่แก้ไขฟิลด์ของระเบียนได้ แอปพลิเคชันอื่นๆ จะแก้ไขจุดข้อมูลที่ไม่ได้สร้างไม่ได้
แอปพลิเคชันเจ้าของสามารถใช้patch เพื่ออัปเดตระเบียนที่มีอยู่ได้ ซึ่งรวมถึงการแก้ไขการประทับเวลาเริ่มต้นหรือสิ้นสุด
ดูตัวอย่างการอัปเดตการประทับเวลาด้วย PATCH ได้ที่
อัปเดตการประทับเวลาช่วงเวลาสำหรับข้อมูลที่มีอยู่
ในคู่มือเกี่ยวกับปลายทาง
ในทำนองเดียวกัน จุดข้อมูลที่ซิงค์จากแพลตฟอร์มภายนอก เช่น Health Connect หรือ แอปพาร์ทเนอร์จะได้รับการอัปเดตจากแหล่งที่มาต้นทาง เมื่อแอปพลิเคชันต้นทางแก้ไขระเบียนที่มีอยู่ การอัปเดตเหล่านั้นจะเผยแพร่ไปยัง Google Health