Quản lý dữ liệu trong Google Health API

Về cơ bản, việc xử lý dữ liệu trong API Google Health là một chu kỳ đồng bộ hoá dữ liệu giữa kho dữ liệu API Google Health trên đám mây và kho dữ liệu phụ trợ hoặc ứng dụng của riêng bạn. Tuy nhiên, chu kỳ này có thể có nhiều hình thức tuỳ thuộc vào nhiều yếu tố:

  • Bạn có đang ghi dữ liệu vào Google Health API không? Chỉ đọc? Hay cả hai?
  • Kho dữ liệu của bạn có nằm trên ứng dụng hoặc thiết bị không? Hay trên đám mây của riêng bạn?
  • Bạn có cần đồng bộ hoá dữ liệu của API Google Health giữa ứng dụng của người dùng và một thiết bị đeo không? Bạn đồng bộ hoá thiết bị bao lâu một lần?
  • Bạn đang làm việc với những loại dữ liệu nào? Số lượng cơ bản? Đơn vị đo lường? Chuỗi có tỷ lệ lấy mẫu khác nhau?
  • Bạn có dự định đọc dữ liệu khi ứng dụng đang chạy ở chế độ nền không?
  • Bạn có dự định xử lý dữ liệu trong quá khứ được ghi lại trước khi ứng dụng của bạn nhận được sự cho phép của người dùng không?

Để hiểu cách tất cả những điều này kết hợp với nhau, hãy xem vòng đời đồng bộ hoá của Google Health API. Có hai phiên bản của vòng đời này: tiêu chuẩn (đọc và ghi) và chỉ đọc.

Vòng đời đồng bộ hoá tiêu chuẩn

Vòng đời đồng bộ hoá tiêu chuẩn trong Google Health API
Hình 1: Vòng đời đồng bộ hoá tiêu chuẩn trong API Google Health

Việc tích hợp với Google Health API có nghĩa là sao chép dữ liệu vào một ứng dụng hoặc kho dữ liệu phụ trợ. Để dễ sử dụng trong tài liệu này, chúng tôi sẽ gọi kho dữ liệu này là kho dữ liệu của nhà phát triển.

"Sao chép" ở đây có thể thay thế cho bất kỳ hoạt động riêng biệt nào, chẳng hạn như đọc từ Google Health API (sao chép vào kho dữ liệu của nhà phát triển) hoặc ghi vào Google Health API (sao chép vào Google Health API). Việc thực hiện các hành động này lặp đi lặp lại theo một thứ tự cụ thể là vòng đời đồng bộ hoá.

Hình 1 minh hoạ vòng đời đồng bộ hoá tiêu chuẩn liên quan đến các thao tác đọc và ghi, không liên quan đến bất kỳ yếu tố nào đã đề cập trước đó.

Viết

  1. Chuẩn bị dữ liệu mới để ghi — Chuyển dữ liệu từ một thiết bị hoặc ứng dụng bên ngoài và định dạng các điểm dữ liệu thành các bản trình bày JSON tương thích với các loại dữ liệu của Google Health API. Xin lưu ý rằng Health API hiện không hỗ trợ mã nhận dạng tuỳ chỉnh do ứng dụng chỉ định cho các thao tác ghi. Bạn có thể cung cấp các mã nhận dạng như vậy trong POST, nhưng các mã nhận dạng đó sẽ bị bỏ qua.
  2. Cập nhật bản ghi — Gửi các điểm dữ liệu đến Google Health API bằng cách sử dụng các điểm cuối REST. Sử dụng POST để tạo bản ghi và PATCH để cập nhật bản ghi hiện có. Mã nhận dạng cần thiết cho thao tác PATCH đến từ một thao tác POST trước đó (bước tiếp theo trong chu kỳ trước).
  3. Xử lý mã tài nguyên được trả về – Khi sử dụng mã nhận dạng do máy chủ tạo, hãy trích xuất và lưu giữ tài nguyên name hoặc mã nhận dạng do máy chủ trả về trong kho dữ liệu của nhà phát triển để cho phép cập nhật (PATCH) hoặc xoá trong tương lai. Hãy xem phần Chiến lược nhận dạng để biết thêm thông tin về hai loại này.

Đọc

  1. Đọc bản ghi – Tìm nạp dữ liệu mới và các thay đổi đối với dữ liệu hiện có trong Google Health API bằng cách sử dụng các điểm cuối REST (GET có tham số truy vấn filter và phân trang pageToken hoặc các điểm cuối tổng hợp như rollUp và dailyRollUp) hoặc nhận thông báo bằng cách sử dụng Gói thuê bao webhook (projects.subscribers). Thông báo chỉ cho biết rằng có dữ liệu mới, chứ không cho biết dữ liệu thực tế là gì.
  2. Điều chỉnh kho dữ liệu của nhà phát triển — Điều chỉnh dữ liệu mới và dữ liệu đã cập nhật cho kho dữ liệu của nhà phát triển. Các thiết bị thông minh có thể tạo ra các khoảng thời gian trùng lặp trong quá trình đồng bộ hoá. Để tìm hiểu cách Google Health API giải quyết các vấn đề này, hãy xem phần Dấu thời gian của khoảng thời gian và đồng bộ hoá thiết bị thông minh.

Sau đó, chu kỳ này lặp lại theo các khoảng thời gian thích hợp tuỳ theo nhu cầu cụ thể của các thiết bị hoặc ứng dụng bên ngoài. Nhìn chung, đây là thứ tự mà chúng tôi đề xuất để đồng bộ hoá dữ liệu giữa kho dữ liệu của riêng bạn và Google Health API.

Chiến lược xác định

Nếu dự định ghi dữ liệu vào API Google Health, thì trước khi xây dựng quy trình tích hợp với API Google Health, bạn phải chọn một chiến lược xác định tài nguyên khi tạo điểm dữ liệu (đơn vị dữ liệu cơ bản).

Health API hiện không hỗ trợ mã nhận dạng do ứng dụng khách chỉ định cho các thao tác ghi. Bạn có thể cung cấp các mã nhận dạng như vậy trong POST, nhưng các mã nhận dạng đó sẽ bị bỏ qua. Thông tin chi tiết về lựa chọn này được cung cấp tại đây để bạn tham khảo.

  1. Mã nhận dạng do máy chủ tạo (tuỳ chọn mặc định): Ứng dụng gửi dữ liệu mà không có mã nhận dạng, còn phần phụ trợ của Google Health API sẽ tạo và trả về một giá trị nhận dạng hệ thống duy nhất.
  2. Mã tuỳ chỉnh do ứng dụng khách chỉ định (theo AIP-133, chưa được hỗ trợ): Ứng dụng khách tạo một giá trị nhận dạng riêng biệt (ví dụ: UUID hoặc khoá chính của cơ sở dữ liệu cục bộ) và cung cấp giá trị nhận dạng đó trong đường dẫn tài nguyên khi tạo.

Bảng sau đây so sánh cả hai chiến lược nhận dạng để giúp bạn chọn phương pháp phù hợp cho việc tích hợp:

Tính năng Mã nhận dạng do máy chủ tạo Mã tùy chỉnh do khách hàng chỉ định
Tạo mã nhận dạng Máy chủ tạo mã hệ thống ngẫu nhiên trong quá trình thực thi POST. Ứng dụng tạo mã nhận dạng ổn định trên thiết bị (UUID phiên bản 4/khoá chính nội bộ) trước khi ghi.
Đường dẫn tài nguyên .../dataPoints/{server_id} (được trả về trong phản hồi) .../dataPoints/{custom_id}
Bước cục bộ sau khi ghi Bắt buộc. Phải lưu trữ server_id được trả về trong cơ sở dữ liệu cục bộ để cho phép cập nhật/xoá trong tương lai. Không có. Ứng dụng đã sở hữu mã nhận dạng này.
Bảng liên kết mã nhận dạng Bắt buộc. Ứng dụng phải duy trì mối liên kết hai chiều (local_id ↔ server_id). Không cần thiết. Ứng dụng khách sử dụng trực tiếp khoá chính của riêng mình.
Hành vi thử lại (Mạng yếu) Rủi ro trùng lặp. Việc thử lại một POST đã hết thời gian chờ sẽ tạo một bản ghi trùng lặp có mã máy chủ mới. An toàn và không thay đổi trạng thái. Việc thử lại POST bằng cùng một custom_id sẽ ngăn việc tạo trùng lặp (trả về 409 ALREADY_EXISTS).
Hỗ trợ đồng bộ hoá khi không có mạng Bị hạn chế. Phải đợi phản hồi của máy chủ để lấy mã tài nguyên chính thức trước khi tham chiếu đến các mã đó. Đầy. Bạn có thể tạo và thay đổi các thực thể khi không có mạng bằng mã nhận dạng ổn định, sau đó đồng bộ hoá liền mạch khi kết nối lại.
Các quy tắc ràng buộc về định dạng Do máy chủ xử lý hoàn toàn. Phải tuân theo ^[a-z0-9-]{4,63}$ (4 – 63 chữ cái viết thường, chữ số và dấu gạch nối).
Trường hợp sử dụng

Chọn mã nhận dạng do máy chủ tạo nếu:

  • Ứng dụng của bạn chỉ có quyền ghi/chỉ có quyền thêm (ví dụ: gửi dữ liệu đo từ xa hoặc số bước không bao giờ được cập nhật hoặc xoá sau đó).
  • Ứng dụng của bạn không duy trì cơ sở dữ liệu cục bộ ổn định cho các điểm dữ liệu riêng lẻ.
  • Bạn thích sự đơn giản mà không cần quản lý các quy tắc ràng buộc về việc xác thực chuỗi (chẳng hạn như ký tự 4-63).

Chọn mã tuỳ chỉnh nếu:

  • Bạn vận hành một ứng dụng đồng bộ hoá hai chiều có chức năng đọc, ghi và cập nhật hồ sơ sức khoẻ trên các thiết bị.
  • Ứng dụng của bạn có một cơ sở dữ liệu cục bộ (chẳng hạn như Room hoặc SQLite) lưu trữ các bản ghi có khoá chính cục bộ.
  • Người dùng của bạn ghi lại dữ liệu khi không có mạng hoặc qua kết nối di động không ổn định, trong trường hợp đó, bạn cần thử lại một cách an toàn.
  • Bạn muốn loại bỏ bảng liên kết mã nhận dạng giữa cơ sở dữ liệu phụ trợ và API.

Vòng đời đồng bộ hoá chỉ có thể đọc

Vòng đời đồng bộ hoá chỉ có thể đọc trong API Google Health
Hình 2: Vòng đời đồng bộ hoá chỉ có thể đọc trong API Google Health

Ứng dụng chỉ có ý định đọc từ API Google Health phải sao chép dữ liệu vào kho dữ liệu của nhà phát triển và xử lý phần đối chiếu của vòng đời.

Các nhiệm vụ tương tự được đề cập trong phần Đọc cũng áp dụng tại đây.

Hình 2 minh hoạ vòng đời chỉ có thể đọc.

Dấu thời gian của khoảng thời gian và đồng bộ hoá thiết bị thông minh

Dữ liệu khoảng thời gian thể hiện các số đo được thu thập trong một khoảng thời gian, chẳng hạn như số bước, tần số tim hoặc các phiên tập thể dục. Ngược lại, các phép đo tại thời điểm cụ thể bao gồm các mục nhập thủ công như nhật ký thực phẩm hoặc chỉ số cân nặng. Dữ liệu khoảng thời gian thường bắt nguồn từ việc đồng bộ hoá các thiết bị thông minh, chẳng hạn như đồng hồ thông minh và thiết bị theo dõi thể chất.

Dấu thời gian của khoảng thời gian (startTime và endTime trong tải trọng JSON REST hoặc start_time và end_time trong biểu thức bộ lọc và gRPC) sẽ tạo ra các hành vi riêng biệt khi làm việc với dữ liệu khoảng thời gian. Phần này giải thích lý do xảy ra các khoảng thời gian trùng lặp và so sánh các điểm cuối list và reconcile.

Khoảng thời gian trùng lặp trên các thiết bị thông minh

Các thiết bị thông minh như thiết bị theo dõi Fitbit và Google Pixel Watch liên tục thu thập dữ liệu sinh trắc học tần suất cao khi người dùng đeo. Sau khi đồng bộ hoá các điểm dữ liệu với Google Health, thiết bị sẽ không thay đổi các bản ghi hiện có đó. Dấu thời gian khoảng thời gian được lưu trữ của các dấu thời gian này không thay đổi.

Tuy nhiên, trước các chu kỳ đồng bộ hoá tiếp theo, thuật toán trên thiết bị thường diễn giải lại dữ liệu đo từ xa thô của cảm biến. Thiết bị sẽ phân nhóm lại các chỉ số thu thập được trong những giờ trước. Khi đồng bộ hoá lại, thiết bị sẽ tải các điểm dữ liệu mới lên. Ranh giới bắt đầu và kết thúc của các khoảng thời gian này có thể trùng lặp với các khoảng thời gian đã lưu trữ trước đó.

Ví dụ: hãy xem xét một người dùng đeo đồng hồ thông minh có dữ liệu hoạt động được đồng bộ hoá trong hai lô liên tiếp:

  1. Trong lần đồng bộ hoá đầu tiên, thiết bị sẽ tải một điểm dữ liệu từ 10:00:00Z đến 10:14:59Z lên.
  2. Sau khi tính toán lại trên thiết bị, một lần đồng bộ hoá thứ hai sẽ tải một điểm dữ liệu khác lên, bao gồm 10:14:00Z đến 10:28:59Z.

Cả hai hồ sơ đều được lưu trữ độc lập trong phần phụ trợ của Google Health. Do đó, cả hai điểm dữ liệu đều bao gồm khoảng thời gian từ 10:14:00Z đến 10:14:59Z. Điều này tạo ra sự trùng lặp 59 giây khi truy vấn các bản ghi thô.

So sánh danh sách và đối chiếu các điểm cuối

Bạn có thể xử lý các khoảng thời gian trùng lặp này bằng cách sử dụng điểm cuối list hoặc reconcile. Chọn điểm cuối phù hợp với yêu cầu của ứng dụng:

Tính năng điểm cuối list điểm cuối reconcile
Phương thức HTTP GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile
Hành vi chồng chéo Trả về tất cả bản ghi được lưu trữ dưới dạng đã tải lên mà không loại bỏ trùng lặp. Khi các khoảng thời gian trùng lặp, cả hai bản ghi đều được trả về. Giải quyết xung đột và loại bỏ các bản ghi trùng lặp trên các thiết bị và phiên đồng bộ hoá thành một luồng liên tục duy nhất.
Ưu điểm Cung cấp nhật ký kiểm tra đầy đủ, chưa sửa đổi của mọi bản ghi được tải lên theo từng thiết bị và lô đồng bộ hoá. Đơn giản hoá việc kết xuất dòng thời gian và tính toán thời lượng bằng cách tự động xử lý các khoảng thời gian chồng chéo và xung đột giữa nhiều thiết bị.
Nhược điểm Ứng dụng của bạn chịu trách nhiệm phát hiện và giải quyết các khoảng thời gian trùng lặp, xung đột giữa nhiều thiết bị và khoảng thời gian không đeo thiết bị. Các bản ghi trùng lặp cấp dưới sẽ bị bỏ qua trong phản hồi, vì vậy, không thể kiểm tra riêng lẻ các lô đồng bộ hoá thiết bị.

Điểm cuối reconcile được thiết kế để vẽ giao diện người dùng, hiển thị dòng thời gian hoạt động và tính tổng thời lượng không trùng lặp. Lớp này giải quyết các khoảng thời gian xung đột từ các phiên đồng bộ hoá được phân nhóm lại. API này cũng điều chỉnh hoạt động được ghi lại đồng thời trên nhiều thiết bị, chẳng hạn như đồng hồ và điện thoại.

Quá trình điều chỉnh sẽ giải quyết các phiên xung đột bằng cách chọn bản ghi có thẩm quyền thay vì tổng hợp một liên kết thời gian nhân tạo. Ví dụ: chế độ này không hợp nhất 11:00:00Z thành 11:30:00Z và 11:20:00Z thành 11:50:00Z thành 11:00:00Z thành 11:50:00Z. Phản hồi đã điều chỉnh sẽ trả về điểm dữ liệu chiến thắng cùng với khoảng thời gian được ghi lại ban đầu. Điều này giúp đảm bảo tính toàn vẹn của dữ liệu đo từ xa và chỉ số đo lường được của phiên đó.

Hình 3 minh hoạ cách điểm cuối reconcile xử lý các phiên trùng lặp. Phương thức này chọn bản ghi có thẩm quyền thay vì tạo một hợp nhất thời gian nhân tạo.

Giải quyết các khoảng thời gian trùng lặp: điều chỉnh việc loại bỏ trùng lặp điểm cuối so với việc hợp nhất liên kết thời gian nhân tạo
Hình 3: Đối chiếu phiên xung đột so với hợp nhất liên kết thời gian nhân tạo

Hướng dẫn về Điểm cuối cung cấp các ví dụ đầy đủ về yêu cầu và phản hồi. Để so sánh bản ghi list thô với kết quả đầu ra reconcile, hãy xem bài viết Xem dữ liệu khoảng thời gian đã đối chiếu.

Điểm cuối list được thiết kế để chẩn đoán thiết bị và kiểm tra dữ liệu. Hãy sử dụng chế độ này khi quy trình công việc của bạn yêu cầu kiểm tra các bản ghi chưa sửa đổi do từng thiết bị tải lên. Khi truy vấn bằng list, logic ứng dụng của bạn phải xử lý mọi khoảng thời gian trùng lặp trong dữ liệu thô.

Tính biến đổi của dấu thời gian và thông tin cập nhật của chủ sở hữu

Thiết bị thông minh không sửa đổi dấu thời gian đã lưu theo hiệu lực hồi tố trong các chu kỳ đồng bộ hoá thông thường. Tuy nhiên, dấu thời gian của khoảng thời gian (startTime và endTime trong tải trọng JSON REST hoặc start_time và end_time trong biểu thức bộ lọc và gRPC) không phải là bất biến trên tất cả các nguồn dữ liệu. Chỉ người tạo hoặc chủ sở hữu ban đầu của một bản ghi mới có thể sửa đổi các trường của bản ghi đó. Các ứng dụng khác không thể chỉnh sửa những điểm dữ liệu mà chúng không tạo.

Ứng dụng của chủ sở hữu có thể sử dụng điểm cuối patch để cập nhật các bản ghi hiện có. Trong đó có cả việc sửa đổi dấu thời gian bắt đầu hoặc kết thúc, thao tác này sẽ cập nhật cả trường giờ UTC (startTime và endTime) và trường giờ dân sự (civilStartTime và civilEndTime) trên máy chủ. Để xem ví dụ về cách cập nhật dấu thời gian bằng PATCH, hãy xem phần Cập nhật dấu thời gian của khoảng thời gian cho dữ liệu hiện có trong hướng dẫn về Điểm cuối.

Tương tự, các điểm dữ liệu được đồng bộ hoá từ các nền tảng bên ngoài như Health Connect hoặc ứng dụng của đối tác sẽ kế thừa nội dung cập nhật từ nguồn gốc. Nếu sau đó Health Connect nhận được bản cập nhật cho một bản ghi đã đồng bộ hoá từ ứng dụng bên thứ ba ban đầu, thì những thay đổi đó sẽ được áp dụng và ghi đè lên bản ghi hiện có.