Pengelolaan data di Google Health API

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

• Apakah Anda menulis data ke Google Health API? Hanya membaca? Atau melakukan keduanya?
• Apakah datastore 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 sampling yang berbeda?
• Apakah Anda berencana membaca data saat aplikasi berada di latar belakang?
• Apakah Anda berencana menggunakan data historis yang dicatat sebelum aplikasi Anda menerima izin pengguna?

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

Siklus proses sinkronisasi standar

Gambar 1: Siklus proses sinkronisasi standar di Google Health API

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

"Menyalin" di sini dapat menggantikan aktivitas terpisah, seperti membaca dari Google Health API (menyalin ke datastore 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 mengilustrasikan siklus proses sinkronisasi standar yang melibatkan operasi baca dan tulis, tanpa mempertimbangkan faktor apa pun yang disebutkan sebelumnya.

Tulis

1. Menyiapkan data baru untuk ditulis — Mentransfer data dari perangkat atau aplikasi eksternal dan memformat titik data menjadi representasi JSON yang kompatibel dengan jenis data Google Health API. Perhatikan bahwa ID kustom yang ditetapkan klien untuk penulisan saat ini tidak didukung di Health API. ID tersebut dapat diberikan dalam POST, tetapi akan diabaikan.
2. Meng-upsert data — Kirim 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 dihasilkan server, ekstrak dan pertahankan name atau ID resource yang ditampilkan server di datastore developer Anda untuk mengaktifkan update (PATCH) atau penghapusan (DELETE) di masa mendatang. Lihat Strategi identifikasi untuk mengetahui informasi selengkapnya tentang kedua jenis tersebut.

Baca

1. Membaca data — Ambil 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 terima notifikasi menggunakan Langganan Webhook (projects.subscribers). Notifikasi hanya menunjukkan bahwa data baru tersedia, bukan data sebenarnya.
2. Merekonsiliasi datastore developer — Rekonsiliasi data baru dan yang diperbarui ke datastore developer Anda. Perangkat 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 menurut kebutuhan spesifik perangkat atau aplikasi eksternal. Ini umumnya adalah urutan yang 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 membangun integrasi dengan Google Health API, Anda harus memilih strategi identifikasi resource saat membuat titik data (unit data dasar).

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

1. ID yang Dibuat Server (opsi default): Klien mengirimkan data tanpa ID, dan backend Google Health API membuat dan menampilkan ID sistem yang unik.
2. ID Kustom yang Ditetapkan Klien (per AIP-133, belum didukung): Aplikasi klien menghasilkan ID unik (misalnya, UUID atau kunci utama database lokal) dan menyediakannya di jalur resource setelah 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 menghasilkan ID sistem acak selama eksekusi POST.	Klien membuat ID stabil secara lokal (UUID v4/PK internal) sebelum penulisan.
Resource Path	.../dataPoints/{server_id} (ditampilkan dalam respons)	.../dataPoints/{custom_id}
Langkah Lokal Pasca-Penulisan	Wajib. Harus menyimpan server_id yang ditampilkan di DB lokal untuk mengaktifkan update/penghapusan di masa mendatang.	Tidak ada. Aplikasi sudah memiliki ID.
Tabel Pemetaan ID	Wajib. Klien harus mempertahankan pemetaan 2 arah (local_id ↔ server_id).	Tidak diperlukan. Klien menggunakan kunci utamanya sendiri secara langsung.
Perilaku Percobaan Ulang (Jaringan Lemah)	Risiko Duplikat. Mencoba ulang POST yang waktu tunggunya habis akan membuat data duplikat dengan ID server baru.	Aman & Idempoten. Mencoba ulang POST dengan custom_id yang sama akan mencegah pembuatan duplikat (menampilkan 409 ALREADY_EXISTS).
Dukungan Sinkronisasi Offline	Terbatas. Harus menunggu respons server untuk mendapatkan ID resource resmi sebelum mereferensikannya.	Penuh. 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 bersifat hanya tulis/hanya tambahkan (misalnya, mengirim telemetri atau jumlah langkah yang tidak pernah diperbarui atau dihapus nanti). Aplikasi Anda tidak mengelola database persisten lokal dari titik data individual. Anda lebih menyukai 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 berbagai perangkat. Aplikasi Anda memiliki database lokal (seperti Room atau SQLite) yang menyimpan data dengan kunci utama lokal. Pengguna Anda mencatat data secara offline atau melalui koneksi seluler yang terputus-putus, sehingga percobaan ulang yang aman diperlukan. Anda ingin menghilangkan tabel pemetaan ID antara database backend dan API.

Siklus proses sinkronisasi hanya baca

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 Membaca berlaku di sini.

Gambar 2 mengilustrasikan siklus proses hanya baca.

Stempel waktu interval dan sinkronisasi perangkat terhubung

Data interval mewakili pengukuran yang dikumpulkan selama durasi waktu, seperti langkah, detak jantung, atau sesi latihan. Sebaliknya, pengukuran pada waktu tertentu 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 dalam payload JSON REST, atau start_time dan end_time dalam ekspresi filter dan gRPC) 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 terhubung

Perangkat terhubung seperti pelacak Fitbit dan Google Pixel Watch terus 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 berubah.

Namun, sebelum siklus sinkronisasi berikutnya, algoritma di perangkat sering kali menafsirkan ulang telemetri sensor mentah. Perangkat akan 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 akan mengupload titik data lain yang mencakup 10:14:00Z hingga 10:28:59Z.

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

Membandingkan endpoint daftar dan rekonsiliasi

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/dataType/dataPoints	GET https://health.googleapis.com/v4/users/me/dataTypes/dataType/dataPoints:reconcile
Perilaku tumpang-tindih	Menampilkan semua data yang disimpan seperti yang diupload tanpa penghapusan duplikat. Jika interval tumpang-tindih, kedua data akan ditampilkan.	Menyelesaikan konflik dan menghapus duplikat data yang tumpang-tindih di seluruh perangkat dan sesi sinkronisasi menjadi satu aliran berkelanjutan.
Kelebihan	Memberikan jejak audit yang lengkap dan tidak dimodifikasi dari setiap data yang diupload oleh setiap perangkat dan batch sinkronisasi.	Menyederhanakan rendering linimasa dan penghitungan durasi dengan otomatis menangani interval yang tumpang-tindih dan konflik multiperangkat.
Kekurangan	Aplikasi Anda bertanggung jawab untuk mendeteksi dan menyelesaikan interval yang tumpang-tindih, konflik multiperangkat, dan periode saat perangkat tidak dipakai di pergelangan tangan.	Data tumpang-tindih bawahan 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. ID ini menyelesaikan interval yang bertentangan dari sesi sinkronisasi yang dikelompokkan ulang. Health Connect juga merekonsiliasi aktivitas yang dicatat secara bersamaan di beberapa perangkat, seperti smartwatch dan ponsel.

Rekonsiliasi menyelesaikan sesi yang bertentangan dengan memilih data yang otoritatif, bukan menyintesis gabungan waktu buatan. Misalnya, alat ini 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 direkonsiliasi menampilkan titik data pemenang dengan interval asli yang dicatat. Hal ini menjaga integritas telemetri dan metrik yang diukur dalam sesi tersebut.

Gambar 3 mengilustrasikan cara endpoint reconcile menangani sesi yang tumpang-tindih. Tindakan ini memilih kumpulan data yang kredibel, bukan membuat gabungan waktu buatan.

Gambar 3: Rekonsiliasi sesi yang bertentangan versus penggabungan gabungan waktu buatan

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

Endpoint list dirancang untuk diagnostik perangkat dan audit data. Gunakan ini saat alur kerja Anda memerlukan pemeriksaan data yang tidak diubah 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 pembaruan pemilik

Perangkat terhubung tidak mengubah stempel waktu yang disimpan secara retroaktif selama siklus sinkronisasi normal. Namun, stempel waktu interval (startTime dan endTime dalam payload JSON REST, atau start_time dan end_time dalam ekspresi filter dan gRPC) tidak selalu tidak dapat diubah di semua sumber data. Hanya pembuat atau pemilik asli data yang dapat mengubah kolomnya. Aplikasi lain tidak dapat mengedit titik data yang tidak dibuatnya.

Aplikasi pemilik dapat menggunakan endpoint patch untuk memperbarui data yang ada. Hal ini termasuk mengubah stempel waktu mulai atau berakhir, yang memperbarui kolom UTC (startTime dan endTime) dan waktu sipil (civilStartTime dan civilEndTime) di server. Untuk contoh memperbarui stempel waktu dengan PATCH, lihat Memperbarui stempel waktu interval untuk data yang ada di panduan Endpoint.

Demikian pula, titik data yang disinkronkan dari platform eksternal seperti Health Connect atau aplikasi partner akan mewarisi update dari sumber asalnya. Jika Health Connect kemudian menerima update untuk data yang disinkronkan dari aplikasi pihak ketiga asli, perubahan tersebut akan diterapkan dan menimpa data yang ada.

Perhatian: Jangan pernah berasumsi bahwa stempel waktu interval titik data bersifat tetap secara permanen. Saat meng-cache titik data secara lokal, pastikan pipeline sinkronisasi Anda menangani update pada data yang ada dan intervalnya.