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 datastore backend atau aplikasi 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? Unit pengukuran? Seri dengan frekuensi pengambilan sampel yang berbeda?
• Apakah Anda berencana membaca data saat aplikasi 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) serta hanya baca.

Siklus proses sinkronisasi standar

Gambar 1: Siklus proses sinkronisasi standar di Google Health API

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

"Salin" di sini dapat menggantikan aktivitas terpisah apa pun, 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 memperhatikan faktor apa pun yang disebutkan sebelumnya.

Tulis

1. Siapkan data baru untuk ditulis — 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 penulisan tidak didukung di Health API saat ini. ID tersebut dapat diberikan dalam POST, tetapi akan diabaikan.
2. Rekonsiliasi 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. Proses ID resource yang ditampilkan — Saat menggunakan ID yang dibuat server, ekstrak dan pertahankan resource yang ditampilkan server name atau ID 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. Baca 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 real-time menggunakan Langganan Webhook (projects.subscribers). Notifikasi hanya menunjukkan bahwa data baru tersedia, bukan data sebenarnya.
2. Rekonsiliasi datastore developer — Rekonsiliasi data baru dan yang diperbarui ke datastore developer Anda.

Siklus ini kemudian berulang pada interval yang sesuai dengan kebutuhan spesifik perangkat atau aplikasi eksternal. Secara umum, inilah 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 membuat integrasi dengan Google Health API, Anda harus memilih strategi identifikasi resource saat membuat titik data (unit data dasar).

ID yang ditetapkan klien untuk penulisan tidak didukung di Health API saat ini. ID tersebut dapat diberikan dalam POST, tetapi akan diabaikan. Detail tentang opsi ini disediakan 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 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:

Fitur	ID yang Dibuat Server	ID Kustom yang Ditetapkan Klien
Pembuatan ID	Server membuat ID sistem acak selama POST eksekusi.	Klien membuat ID stabil secara lokal (UUID v4 / PK internal) sebelum menulis.
Jalur Resource	.../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 utama miliknya secara langsung.
Perilaku Coba Lagi (Jaringan Lemah)	Risiko Duplikat. Mencoba lagi POST yang waktu operasinya habis akan membuat data duplikat dengan ID server baru.	Aman &Idempoten. Mencoba lagi POST dengan yang samacustom_id akan mencegah pembuatan duplikat (menampilkan 409 ALREADY_EXISTS).
Dukungan Sinkronisasi Offline	Terbatas. Harus menunggu respons server untuk mendapatkan ID resource resmi sebelum mereferensikannya.	Penuh. Entity dapat dibuat dan diubah secara offline dengan ID stabil lalu disinkronkan dengan lancar saat terhubung kembali.
Batasan Format	Ditangani sepenuhnya oleh server.	Harus mengikuti ^[a-z0-9-]{4,63}$ (alfanumerik huruf kecil &tanda hubung 4–63).
Kapan Memilih	Pilih ID yang dibuat server jika: Aplikasi Anda hanya dapat menulis / menambahkan (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 dan memerlukan percobaan ulang yang aman. 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 Baca berlaku di sini.

Gambar 2 mengilustrasikan siklus proses hanya baca.