การทำงานกับข้อมูลใน Google Health API โดยหลักแล้วคือวงจรการซิงค์ข้อมูลระหว่างที่เก็บข้อมูล Google Health API ในระบบคลาวด์กับแอปหรือที่เก็บข้อมูลแบ็กเอนด์ของคุณเอง อย่างไรก็ตาม วงจรนี้อาจมีรูปแบบที่แตกต่างกันไปตามปัจจัยต่างๆ ดังนี้
- คุณกำลังเขียนข้อมูลไปยัง Google Health API ใช่ไหม อ่านอย่างเดียวใช่ไหม หรือทำทั้ง 2 อย่าง
- ที่เก็บข้อมูลของคุณอยู่ในแอปหรืออุปกรณ์ใช่ไหม หรือในระบบคลาวด์ของคุณเอง
- คุณจำเป็นต้องซิงค์ข้อมูล 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หรือรหัสที่เซิร์ฟเวอร์แสดงผลไว้ใน Datastore ของนักพัฒนาซอฟต์แวร์เพื่อเปิดใช้การอัปเดต (PATCH) หรือการลบ (DELETE) ในอนาคต ดูข้อมูลเพิ่มเติมเกี่ยวกับทั้ง 2 ประเภทได้ที่กลยุทธ์การระบุตัวตน
อ่าน
- อ่านระเบียน — ดึงข้อมูลใหม่และการเปลี่ยนแปลงข้อมูลที่มีอยู่ใน Google Health API โดยใช้ปลายทาง REST (
GETที่มีพารามิเตอร์การค้นหาfilterและการแบ่งหน้าpageTokenหรือปลายทางการรวมข้อมูล เช่นrollUpและdailyRollUp) หรือรับการแจ้งเตือนโดยใช้การสมัครรับข้อมูลเว็บฮุค (projects.subscribers) การแจ้งเตือนจะระบุเฉพาะว่ามีข้อมูลใหม่ ไม่ใช่ข้อมูลจริง - ปรับยอด Datastore ของนักพัฒนาแอป - ปรับยอดข้อมูลใหม่และข้อมูลที่อัปเดตกับ Datastore ของนักพัฒนาแอป อุปกรณ์ที่เชื่อมต่ออาจสร้างช่วงเวลาที่ทับซ้อนกันระหว่างการซิงค์ หากต้องการดูวิธีที่ Google Health API แก้ไขปัญหาดังกล่าว โปรดดูการประทับเวลาของช่วงเวลาและการซิงค์อุปกรณ์ที่เชื่อมต่อ
จากนั้นวงจรนี้จะทำซ้ำตามช่วงเวลาที่เหมาะสมตามความต้องการเฉพาะของอุปกรณ์หรือแอปภายนอก โดยทั่วไปแล้ว เราขอแนะนำให้ซิงค์ข้อมูลระหว่าง Datastore ของคุณเองกับ 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 ที่แสดงผลไว้ในฐานข้อมูลในเครื่องเพื่อเปิดใช้การอัปเดต/การลบในอนาคต |
ไม่มี แอปเป็นเจ้าของรหัสอยู่แล้ว |
| ตารางการจับคู่รหัส | ต้องระบุ ลูกค้าต้องรักษาการจับคู่แบบ 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 ในเพย์โหลด REST JSON หรือ start_time และ end_time ในนิพจน์ตัวกรองและ gRPC) จะทำให้เกิดลักษณะการทำงานที่ไม่ซ้ำกันเมื่อทำงานกับข้อมูลช่วงเวลา ส่วนนี้จะอธิบายสาเหตุที่เกิดช่วงเวลาที่ทับซ้อนกัน และเปรียบเทียบปลายทาง list และ reconcile
ช่วงเวลาที่ทับซ้อนกันจากอุปกรณ์ที่เชื่อมต่อ
อุปกรณ์ที่เชื่อมต่อ เช่น อุปกรณ์ติดตาม Fitbit และ Google Pixel Watch จะรวบรวมข้อมูลการอ่านค่าไบโอเมตริกความถี่สูงอย่างต่อเนื่องขณะสวมใส่ หลังจากที่อุปกรณ์ซิงค์จุดข้อมูลกับ Google Health แล้ว ระบบจะไม่แก้ไขบันทึกที่มีอยู่ย้อนหลัง การประทับเวลาของช่วงเวลาที่จัดเก็บไว้จะยังคงเหมือนเดิม
อย่างไรก็ตาม ก่อนรอบการซิงค์ครั้งต่อๆ ไป อัลกอริทึมในอุปกรณ์มักจะตีความข้อมูลการตรวจวัดระยะไกลของเซ็นเซอร์ดิบอีกครั้ง อุปกรณ์จะจัดกลุ่มค่าที่อ่านได้ซึ่งรวบรวมไว้ในช่วงหลายชั่วโมงก่อนหน้าใหม่ เมื่ออุปกรณ์ซิงค์อีกครั้ง ระบบจะอัปโหลดจุดข้อมูลใหม่ ขอบเขตเริ่มต้นและสิ้นสุดของช่วงเวลาดังกล่าวอาจทับซ้อนกับช่วงเวลาที่จัดเก็บไว้ก่อนหน้านี้
ตัวอย่างเช่น ลองพิจารณาผู้ใช้ที่สวมสมาร์ทวอทช์ซึ่งมีการซิงค์ข้อมูลกิจกรรมเป็น 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 ออกแบบมาเพื่อวาดอินเทอร์เฟซผู้ใช้ แสดงผลไทม์ไลน์กิจกรรม และคำนวณระยะเวลารวมที่ไม่ทับซ้อนกัน ซึ่งจะช่วยแก้ไขช่วงเวลาที่ขัดแย้งกันจากเซสชันการซิงค์ที่จัดกลุ่มใหม่ นอกจากนี้ ยังปรับยอดบันทึกกิจกรรมที่บันทึกพร้อมกันในอุปกรณ์หลายเครื่อง เช่น นาฬิกาและโทรศัพท์
การปรับยอดจะแก้ไขเซสชันที่ขัดแย้งกันโดยเลือกบันทึกที่เชื่อถือได้แทนที่จะสังเคราะห์การรวมเวลาเทียม ตัวอย่างเช่น ระบบจะไม่ผสาน 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 ได้ที่หัวข้ออัปเดตการประทับเวลาของช่วงเวลาสำหรับข้อมูลที่มีอยู่ในคู่มือ Endpoints
ในทำนองเดียวกัน จุดข้อมูลที่ซิงค์จากแพลตฟอร์มภายนอก เช่น Health Connect หรือแอปพาร์ทเนอร์จะรับการอัปเดตจากแหล่งที่มาต้นทาง หาก Health Connect ได้รับการอัปเดตสำหรับบันทึกที่ซิงค์จากแอปของบุคคลที่สามเดิมในภายหลัง การเปลี่ยนแปลงเหล่านั้นจะเผยแพร่และเขียนทับบันทึกที่มีอยู่