การทำงานกับข้อมูลใน Google Health API มีวงจรหลักคือการซิงค์ ข้อมูลระหว่างที่เก็บข้อมูลของ Google Health API ในระบบคลาวด์กับแอปหรือ ที่เก็บข้อมูลแบ็กเอนด์ของคุณเอง อย่างไรก็ตาม วงจรนี้อาจมีรูปแบบที่แตกต่างกันไปตามปัจจัยต่างๆ ดังนี้
- คุณกำลังเขียนข้อมูลไปยัง Google Health API ใช่ไหม อ่านอย่างเดียวใช่ไหม หรือจะทำทั้ง 2 อย่าง
- Datastore อยู่ในเครื่องในแอปหรืออุปกรณ์ใช่ไหม หรือในระบบคลาวด์ของคุณเอง
- คุณต้องซิงค์ข้อมูล 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) การแจ้งเตือนจะระบุว่ามีข้อมูลใหม่พร้อมใช้งานเท่านั้น ไม่ใช่ข้อมูลจริง - กระทบยอด Datastore ของนักพัฒนาแอป - กระทบยอดข้อมูลใหม่และข้อมูลที่อัปเดตกับ Datastore ของนักพัฒนาแอป อุปกรณ์ที่เชื่อมต่ออาจสร้างช่วงเวลาที่ทับซ้อนกัน ระหว่างการซิงค์ ดูวิธีที่ 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} |
| Post-Write Local Step | ต้องระบุ ต้องจัดเก็บ 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 ในเพย์โหลด JSON ของ REST หรือ
start_time และ end_time ในนิพจน์ตัวกรองและ gRPC) จะทำให้เกิดลักษณะการทำงานที่ไม่ซ้ำกัน
เมื่อทำงานกับข้อมูลช่วง ส่วนนี้จะอธิบายสาเหตุที่ช่วงเวลาทับซ้อนกันเกิดขึ้นและเปรียบเทียบปลายทาง 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/dataType/dataPoints |
GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/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 ใน REST
JSON เพย์โหลด หรือ start_time และ end_time ในนิพจน์ตัวกรองและ gRPC)
ไม่ได้เปลี่ยนแปลงไม่ได้ในทุกแหล่งข้อมูล มีเพียงผู้สร้างหรือเจ้าของระเบียนต้นฉบับเท่านั้นที่แก้ไขฟิลด์ของระเบียนได้ แอปพลิเคชันอื่นๆ จะแก้ไขจุดข้อมูลที่ไม่ได้สร้างไม่ได้
แอปพลิเคชันเจ้าของสามารถใช้patch
เพื่ออัปเดตระเบียนที่มีอยู่ ซึ่งรวมถึงการแก้ไขการประทับเวลาเริ่มต้นหรือสิ้นสุด
ซึ่งจะอัปเดตทั้งฟิลด์เวลา UTC (startTime และ endTime) และเวลาพลเรือน
(civilStartTime และ civilEndTime) ในเซิร์ฟเวอร์ ดูตัวอย่างการอัปเดต
การประทับเวลาด้วย PATCH ได้ที่
อัปเดตการประทับเวลาช่วงเวลาสำหรับข้อมูลที่มีอยู่
ในคู่มือปลายทาง
ในทำนองเดียวกัน จุดข้อมูลที่ซิงค์จากแพลตฟอร์มภายนอก เช่น Health Connect หรือ แอปพาร์ทเนอร์จะได้รับการอัปเดตจากแหล่งที่มาต้นทาง หาก Health Connect ได้รับข้อมูลอัปเดตสำหรับระเบียนที่ซิงค์จากแอป ของบุคคลที่สามเดิมในภายหลัง การเปลี่ยนแปลงเหล่านั้นจะแพร่กระจายและเขียนทับระเบียนที่มีอยู่