Pengelolaan Data di Google Health API

Bekerja dengan data di Google Health API pada dasarnya adalah siklus menyinkronkan data antara datastore Google Health API di cloud dan aplikasi atau datastore backend Anda sendiri. Namun, siklus ini dapat memiliki berbagai bentuk, bergantung pada berbagai faktor:

  • Apakah Anda menulis data ke Google Health API? Hanya membaca? Atau melakukan keduanya?
  • Apakah penyimpanan data Anda bersifat lokal di aplikasi atau perangkat? Atau di cloud Anda sendiri?
  • Apakah Anda perlu menyinkronkan data Google Health API antara aplikasi pengguna dan perangkat wearable? Seberapa sering Anda menyinkronkan perangkat?
  • Apa jenis data yang sedang Anda kelola? Jumlah dasar? Satuan ukur? Deret dengan frekuensi pengambilan sampel yang berbeda?
  • Apakah Anda berencana membaca data saat aplikasi Anda berada di latar belakang?
  • Apakah Anda berencana menggunakan data historis yang direkam sebelum aplikasi Anda menerima izin pengguna?

Untuk memahami cara kerja semuanya, lihat siklus proses sinkronisasi Google Health API. Ada dua versi siklus proses ini: standar (baca dan tulis) dan hanya baca.

Siklus proses sinkronisasi standar

Siklus proses sinkronisasi standar di Google Health API
Gambar 1: Siklus proses sinkronisasi standar di Google Health API

Mengintegrasikan dengan Google Health API berarti menyalin data ke aplikasi atau datastore backend. Untuk mempermudah penggunaan dalam dokumentasi ini, kami akan menyebut datastore ini sebagai developer datastore.

"Menyalin" di sini dapat menggantikan aktivitas diskrit apa pun, seperti membaca dari Google Health API (menyalin ke penyimpanan data developer) atau menulis ke Google Health API (menyalin ke Google Health API). Melakukan tindakan ini berulang kali dalam urutan tertentu adalah siklus proses sinkronisasi.

Gambar 1 menggambarkan siklus proses sinkronisasi standar yang melibatkan operasi baca dan tulis, tanpa memperhatikan faktor apa pun yang disebutkan sebelumnya.

Tulis

  1. Menyiapkan data baru untuk penulisan — Transfer data dari perangkat atau aplikasi eksternal dan format titik data ke dalam representasi JSON yang kompatibel dengan jenis data Google Health API. Perhatikan bahwa ID yang ditetapkan klien kustom untuk operasi tulis saat ini tidak didukung di Health API. ID tersebut dapat diberikan dalam POST, tetapi akan diabaikan.
  2. Memasukkan atau memperbarui data — Kirimkan titik data ke Google Health API menggunakan endpoint REST. Gunakan POST untuk membuat data, dan PATCH untuk menyisipkan dan memperbarui data yang ada. ID yang diperlukan untuk operasi PATCH akan berasal dari operasi POST sebelumnya (langkah berikutnya dalam siklus sebelumnya).
  3. Memproses ID resource yang ditampilkan — Saat menggunakan ID yang dibuat server, ekstrak dan pertahankan name atau ID resource yang ditampilkan server di penyimpanan data developer Anda untuk mengaktifkan pembaruan (PATCH) atau penghapusan (DELETE) di masa mendatang. Lihat Strategi identifikasi untuk mengetahui informasi selengkapnya tentang kedua jenis tersebut.

Baca

  1. Membaca data — Mengambil data baru dari dan perubahan pada data yang ada di Google Health API menggunakan endpoint REST (GET dengan parameter kueri filter dan penomoran halaman pageToken, atau endpoint agregasi seperti rollUp dan dailyRollUp), atau menerima notifikasi real-time menggunakan Langganan Webhook (projects.subscribers). Notifikasi hanya menunjukkan bahwa data baru tersedia, bukan data sebenarnya.
  2. Mencocokkan penyimpanan data developer — Mencocokkan data baru dan yang diperbarui dengan penyimpanan data developer Anda. Perangkat yang terhubung dapat menghasilkan interval yang tumpang-tindih selama sinkronisasi. Untuk mempelajari cara Google Health API menyelesaikannya, lihat Stempel waktu interval dan sinkronisasi perangkat terhubung.

Siklus ini kemudian berulang pada interval yang sesuai berdasarkan kebutuhan spesifik perangkat atau aplikasi eksternal. Urutan ini umumnya kami rekomendasikan untuk menyinkronkan data antara datastore Anda sendiri dan Google Health API.

Strategi identifikasi

Jika Anda ingin menulis data ke Google Health API, sebelum membuat integrasi dengan Google Health API, Anda harus memilih strategi identifikasi resource saat membuat titik data (unit dasar data).

ID yang ditetapkan klien untuk operasi tulis saat ini tidak didukung di Health API. ID tersebut dapat diberikan dalam POST, tetapi akan diabaikan. Detail tentang opsi ini diberikan di sini untuk tujuan informasi.

  1. ID yang Dibuat Server (opsi default): Klien mengirimkan data tanpa ID, dan backend Google Health API membuat serta menampilkan ID sistem yang unik.
  2. ID Kustom yang Ditetapkan Klien (per AIP-133, belum didukung): Aplikasi klien membuat ID unik (misalnya, UUID atau kunci utama database lokal) dan menyediakannya di jalur resource saat pembuatan.

Tabel berikut membandingkan kedua strategi identifikasi untuk membantu Anda memilih pendekatan yang tepat untuk integrasi Anda:

Fitur ID yang Dibuat Server ID Kustom yang Ditetapkan Klien
Pembuatan ID Server membuat ID sistem acak selama eksekusi POST. Klien membuat ID stabil secara lokal (UUID v4 / PK internal) sebelum penulisan.
Jalur Resource .../dataPoints/{server_id} (dikembalikan dalam respons) .../dataPoints/{custom_id}
Post-Write Local Step Wajib. Harus menyimpan server_id yang ditampilkan di DB lokal untuk mengaktifkan update/penghapusan pada masa mendatang. Tidak ada. Aplikasi sudah memiliki ID.
Tabel Pemetaan ID Wajib. Klien harus mempertahankan pemetaan dua arah (local_id ↔ server_id). Tidak diperlukan. Klien menggunakan kunci utamanya sendiri secara langsung.
Perilaku Coba Lagi (Jaringan Lemah) Risiko Duplikat. Mencoba lagi POST yang waktunya habis akan membuat duplikat data dengan ID server baru. Aman & Idempoten. Mencoba lagi POST dengan custom_id yang sama mencegah pembuatan duplikat (menampilkan 409 ALREADY_EXISTS).
Dukungan Sinkronisasi Offline Terbatas. Harus menunggu respons server untuk mendapatkan ID resource resmi sebelum mereferensikannya. Full. Entitas dapat dibuat dan diubah secara offline dengan ID yang stabil, lalu disinkronkan dengan lancar saat terhubung kembali.
Batasan Format Ditangani sepenuhnya oleh server. Harus mengikuti ^[a-z0-9-]{4,63}$ (4–63 alfanumerik huruf kecil & tanda hubung).
Kapan Harus Memilih

Pilih ID yang dibuat server jika:

  • Aplikasi Anda hanya dapat ditulis / ditambahkan (misalnya, mengirim telemetri atau jumlah langkah yang tidak pernah diupdate atau dihapus nanti).
  • Aplikasi Anda tidak mempertahankan database persisten lokal dari titik data individual.
  • Anda lebih memilih kesederhanaan tanpa mengelola batasan validasi string (seperti karakter 4-63).

Pilih ID kustom jika:

  • Anda mengoperasikan aplikasi sinkronisasi dua arah yang membaca, menulis, dan memperbarui catatan kesehatan di seluruh perangkat.
  • Aplikasi Anda memiliki database lokal (seperti Room atau SQLite) yang menyimpan data dengan kunci utama lokal.
  • Pengguna Anda merekam data secara offline atau melalui koneksi seluler yang terputus-putus yang memerlukan percobaan ulang yang aman.
  • Anda ingin menghilangkan tabel pemetaan ID antara database backend dan API.

Siklus proses sinkronisasi hanya baca

Siklus proses sinkronisasi hanya baca di Google Health API
Gambar 2: Siklus proses sinkronisasi hanya baca di Google Health API

Aplikasi yang hanya ingin membaca dari Google Health API harus menyalin data ke datastore developer dan menangani bagian rekonsiliasi siklus proses.

Tugas yang sama yang dibahas di bagian Baca berlaku di sini.

Gambar 2 menggambarkan siklus proses hanya baca.

Stempel waktu interval dan sinkronisasi perangkat terhubung

Data interval merepresentasikan pengukuran yang dikumpulkan selama jangka waktu tertentu, seperti langkah, detak jantung, atau sesi latihan fisik. Sebaliknya, pengukuran pada satu titik waktu mencakup entri manual seperti log makanan atau pembacaan timbangan. Data interval biasanya berasal dari sinkronisasi perangkat terhubung, seperti smartwatch dan pelacak kebugaran.

Stempel waktu interval (startTime dan endTime) memperkenalkan perilaku unik saat bekerja dengan data interval. Bagian ini menjelaskan alasan terjadinya interval yang tumpang-tindih dan membandingkan endpoint list dan reconcile.

Interval yang tumpang-tindih dari perangkat yang terhubung

Perangkat terhubung seperti pelacak Fitbit dan Google Pixel Watch terus-menerus mengumpulkan pembacaan biometrik frekuensi tinggi saat dipakai. Setelah perangkat menyinkronkan titik data ke Google Health, perangkat tidak akan mengubah data yang ada secara retroaktif. Stempel waktu interval yang disimpan tidak akan berubah.

Namun, sebelum siklus sinkronisasi berikutnya, algoritma di perangkat sering kali menafsirkan ulang telemetri sensor mentah. Perangkat mengelompokkan ulang pembacaan yang dikumpulkan selama beberapa jam sebelumnya. Saat perangkat disinkronkan lagi, perangkat akan mengupload titik data baru. Batas awal dan akhirnya dapat tumpang-tindih dengan interval yang disimpan sebelumnya.

Misalnya, pertimbangkan pengguna yang memakai smartwatch yang data aktivitasnya disinkronkan dalam dua batch berturut-turut:

  1. Selama sinkronisasi pertama, perangkat mengupload titik data yang mencakup 10:00:00Z hingga 10:14:59Z.
  2. Setelah penghitungan ulang di perangkat, sinkronisasi kedua mengupload titik data lain yang mencakup 10:14:00Z hingga 10:28:59Z.

Kedua catatan disimpan secara terpisah di backend Google Health. Akibatnya, kedua titik data mencakup interval dari 10:14:00Z hingga 10:14:59Z. Hal ini akan menghasilkan tumpang-tindih 59 detik saat mengkueri rekaman mentah.

Membandingkan daftar dan menyamakan endpoint

Anda dapat menangani interval yang tumpang-tindih ini menggunakan endpoint list atau reconcile. Pilih endpoint yang sesuai dengan persyaratan aplikasi Anda:

Fitur list endpoint reconcile endpoint
Metode 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
Perilaku tumpang-tindih Menampilkan semua rekaman tersimpan sebagai diupload tanpa penghapusan duplikat. Jika interval tumpang-tindih, kedua rekaman akan ditampilkan. Menyelesaikan konflik dan menghapus duplikat catatan yang tumpang-tindih di seluruh perangkat dan sesi sinkronisasi ke dalam satu aliran berkelanjutan.
Kelebihan Menyediakan jejak audit lengkap dan tidak dimodifikasi dari setiap data yang diupload oleh setiap perangkat dan batch sinkronisasi. Menyederhanakan rendering linimasa dan penghitungan durasi dengan menangani secara otomatis interval yang tumpang-tindih dan konflik multiperangkat.
Kekurangan Aplikasi Anda bertanggung jawab untuk mendeteksi dan menyelesaikan interval yang tumpang-tindih, konflik multi-perangkat, dan periode saat tidak dipakai di pergelangan tangan. Subordinate overlapping records dihilangkan dari respons, sehingga batch sinkronisasi perangkat individual tidak dapat diaudit secara terpisah.

Endpoint reconcile dirancang untuk menggambar antarmuka pengguna, merender linimasa aktivitas, dan menghitung total durasi yang tidak tumpang-tindih. Tindakan ini menyelesaikan konflik interval dari sesi sinkronisasi yang dikelompokkan ulang. Fitur ini juga menyelaraskan aktivitas yang dicatat secara bersamaan di beberapa perangkat, seperti smartwatch dan ponsel.

Rekonsiliasi menyelesaikan sesi yang bertentangan dengan memilih catatan otoritatif, bukan menyintesis gabungan waktu buatan. Misalnya, tidak menggabungkan 11:00:00Z ke 11:30:00Z dan 11:20:00Z ke 11:50:00Z menjadi 11:00:00Z ke 11:50:00Z. Respons yang disesuaikan menampilkan titik data yang menang dengan interval yang direkam aslinya. Hal ini menjaga integritas telemetri dan metrik yang diukur pada sesi tersebut.

Gambar 3 mengilustrasikan cara endpoint reconcile menangani sesi yang tumpang-tindih. Fitur ini memilih catatan otoritatif, bukan membuat gabungan waktu buatan.

Menyelesaikan interval yang tumpang-tindih: menyelaraskan penghapusan duplikat endpoint versus penggabungan gabungan waktu buatan
Gambar 3: Rekonsiliasi sesi yang bertentangan versus penggabungan gabungan waktu buatan

Panduan Endpoints memberikan contoh permintaan dan respons yang lengkap. Untuk membandingkan rekaman list mentah dengan output reconcile, lihat Mendapatkan tampilan data interval yang disesuaikan.

Endpoint list dirancang untuk diagnostik perangkat dan audit data. Gunakan fitur ini jika alur kerja Anda memerlukan pemeriksaan rekaman yang tidak dimodifikasi seperti yang diupload oleh setiap perangkat. Saat membuat kueri dengan list, logika klien Anda harus menangani tumpang-tindih interval dalam data mentah.

Mutabilitas stempel waktu dan update pemilik

Perangkat yang terhubung tidak mengubah stempel waktu yang disimpan secara retroaktif selama siklus sinkronisasi normal. Namun, stempel waktu interval (startTime dan endTime) tidak dapat diubah secara universal di semua sumber data. Hanya pembuat atau pemilik asli suatu rekaman yang dapat mengubah kolomnya. Aplikasi lain tidak dapat mengedit titik data yang tidak dibuatnya.

Aplikasi pemilik dapat menggunakan endpoint patch untuk memperbarui catatan yang ada. Hal ini mencakup pengubahan stempel waktu mulai atau akhir. Untuk contoh memperbarui stempel waktu dengan PATCH, lihat Memperbarui stempel waktu interval untuk data yang ada di panduan Endpoints.

Demikian pula, titik data yang disinkronkan dari platform eksternal seperti Health Connect atau aplikasi partner mewarisi pembaruan dari sumber aslinya. Saat aplikasi asal mengubah data yang ada, pembaruan tersebut akan diteruskan ke Google Health.