Halaman ini diterjemahkan oleh Cloud Translation API.

Menulis data

Panduan ini membahas proses penulisan atau pembaruan data di Health Connect.

Menyiapkan struktur data

Sebelum menulis data, kita perlu menyiapkan kumpulan data terlebih dahulu. Lebih dari 50 jenis data memiliki strukturnya masing-masing. Lihat referensi Jetpack untuk mengetahui detail selengkapnya tentang jenis data yang tersedia.

Kumpulan data dasar

Jenis data Langkah di Health Connect mendeteksi jumlah langkah pengguna di sela-sela pembacaan. Jumlah langkah mewakili pengukuran umum di berbagai platform kesehatan dan kebugaran.

Contoh berikut menunjukkan cara menetapkan data jumlah langkah:

val stepsRecord = StepsRecord(
    count = 120,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Kumpulan data dengan satuan pengukuran

Health Connect dapat menyimpan nilai bersama dengan satuan pengukurannya untuk memberikan akurasi. Salah satu contohnya adalah jenis data Nutrisi yang luas dan komprehensif. Jenis data ini mencakup berbagai bidang gizi opsional, mulai dari total karbohidrat hingga vitamin. Setiap titik data mewakili gizi yang berpotensi dikonsumsi sebagai bagian dari makanan atau item makanan.

Dalam jenis data ini, semua nutrisi ditampilkan dalam satuan Mass, sementara energy ditampilkan dalam satuan Energy.

Contoh berikut menunjukkan cara menetapkan data gizi untuk pengguna yang telah makan pisang:

val banana = NutritionRecord(
    name = "banana",
    energy = 105.0.kilocalories,
    dietaryFiber = 3.1.grams,
    potassium = 0.422.grams,
    totalCarbohydrate = 27.0.grams,
    totalFat = 0.4.grams,
    saturatedFat = 0.1.grams,
    sodium = 0.001.grams,
    sugar = 14.0.grams,
    vitaminB6 = 0.0005.grams,
    vitaminC = 0.0103.grams,
    startTime = START_TIME,
    endTime = END_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endZoneOffset = END_ZONE_OFFSET
)

Kumpulan data dengan data serial

Health Connect dapat menyimpan daftar data serial. Salah satu contohnya adalah jenis data Detak Jantung yang menangkap serangkaian contoh detak jantung yang terdeteksi di antara pembacaan.

Dalam jenis data ini, parameter samples direpresentasikan oleh daftar contoh Detak Jantung. Setiap sampel berisi nilai beatsPerMinute dan nilai time.

Contoh berikut menunjukkan cara menetapkan data seri detak jantung:

val heartRateRecord = HeartRateRecord(
    startTime = START_TIME,
    startZoneOffset = START_ZONE_OFFSET,
    endTime = END_TIME,
    endZoneOffset = END_ZONE_OFFSET,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = START_TIME + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    }
)

Menulis data

Salah satu alur kerja umum di Health Connect adalah menulis data. Untuk menambahkan kumpulan data, gunakan insertRecords.

Contoh berikut menunjukkan cara menulis data dengan menyisipkan jumlah langkah:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = START_TIME,
            endTime = END_TIME,
            startZoneOffset = START_ZONE_OFFSET,
            endZoneOffset = END_ZONE_OFFSET
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

Memperbarui data

Jika perlu mengubah satu atau beberapa kumpulan data, terutama saat Anda perlu menyinkronkan datastore aplikasi dengan data dari Health Connect, Anda dapat memperbarui data. Ada dua cara untuk memperbarui data yang ada, yang bergantung pada ID yang digunakan untuk menemukan kumpulan data.

Metadata

Sebaiknya periksa class Metadata terlebih dahulu karena hal ini diperlukan saat memperbarui data. Saat pembuatan, setiap Record di Health Connect memiliki kolom metadata. Properti berikut relevan dengan sinkronisasi:

Properti	Deskripsi
`id`	Setiap `Record` di Health Connect memiliki nilai `id` yang unik. Health Connect akan otomatis mengisi ini saat menyisipkan kumpulan data baru.
`lastModifiedTime`	Setiap `Record` juga melacak kapan terakhir kali kumpulan data diubah. Health Connect otomatis mengisinya.
`clientRecordId`	Setiap `Record` dapat memiliki ID unik yang terkait dengannya untuk digunakan sebagai referensi di datastore aplikasi Anda. Aplikasi Anda menyediakan nilai ini.
`clientRecordVersion`	Jika kumpulan data memiliki `clientRecordId`, `clientRecordVersion` dapat digunakan untuk memungkinkan data tetap sinkron dengan versi di datastore aplikasi. Aplikasi Anda menyediakan nilai ini.

Memperbarui melalui ID Kumpulan Data

Untuk memperbarui data, siapkan kumpulan data yang diperlukan terlebih dahulu. Lakukan perubahan pada kumpulan data jika diperlukan. Selanjutnya, panggil updateRecords untuk melakukan perubahan.

Contoh berikut menunjukkan cara mengupdate data. Untuk tujuan ini, setiap kumpulan data memiliki nilai offset zona yang disesuaikan menjadi PST.

suspend fun updateSteps(
    healthConnectClient: HealthConnectClient,
    prevRecordStartTime: Instant,
    prevRecordEndTime: Instant
) {
    try {
        val request = healthConnectClient.readRecords(
            ReadRecordsRequest(
                recordType = StepsRecord::class,
                timeRangeFilter = TimeRangeFilter.between(
                    prevRecordStartTime,
                    prevRecordEndTime
                )
            )
        )

        val newStepsRecords = arrayListOf<StepsRecord>()
        for (record in request.records) {
            // Adjusted both offset values to reflect changes
            val sr = StepsRecord(
                count = record.count,
                startTime = record.startTime,
                startZoneOffset = record.startTime.atZone(ZoneId.of("PST")).offset,
                endTime = record.endTime,
                endZoneOffset = record.endTime.atZone(ZoneId.of("PST")).offset,
                metadata = record.metadata
            )
            newStepsRecords.add(sr)
        }

        client.updateRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Memperbarui dan Menyisipkan melalui ID Kumpulan Data Klien

Jika Anda menggunakan nilai ID Kumpulan Data Klien dan Versi Kumpulan Data Klien opsional, sebaiknya gunakan insertRecords, bukan updateRecords.

Fungsi insertRecords memiliki kemampuan untuk memperbarui dan menyisipkan data. Jika data ada di Health Connect berdasarkan serangkaian ID Kumpulan Data Klien tertentu, data tersebut akan ditimpa. Jika tidak, data akan ditulis sebagai data baru. Skenario ini berguna setiap kali Anda perlu menyinkronkan data dari datastore aplikasi ke Health Connect.

Contoh berikut menunjukkan cara melakukan pembaruan dan penyisipan pada data yang diambil dari datastore aplikasi:

suspend fun pullStepsFromDatastore() : ArrayList<StepsRecord> {
    val appStepsRecords = arrayListOf<StepsRecord>()
    // Pull data from app datastore
    // ...
    // Make changes to data if necessary
    // ...
    // Store data in appStepsRecords
    // ...
    var sr = StepsRecord(
        // Assign parameters for this record
        metadata = Metadata(
            clientRecordId = cid
        )
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

suspend fun upsertSteps(
    healthConnectClient: HealthConnectClient,
    newStepsRecords: ArrayList<StepsRecord>
) {
    try {
        healthConnectClient.insertRecords(newStepsRecords)
    } catch (e: Exception) {
        // Run error handling here
    }
}

Setelah itu, Anda dapat memanggil fungsi ini di thread utama.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Pemeriksaan nilai di Versi Kumpulan Data Klien

Jika proses pembaruan dan penyisipan data Anda mencakup Versi Kumpulan Data Klien, Health Connect akan melakukan pemeriksaan perbandingan dalam nilai clientRecordVersion. Jika versi dari data yang disisipkan lebih tinggi daripada versi dari data yang ada, pembaruan dan penyisipan akan terjadi. Jika tidak, proses akan mengabaikan perubahan dan nilainya tetap sama.

Untuk menyertakan pembuatan versi dalam data, Anda harus menyediakan Metadata.clientRecordVersion dengan nilai Long berdasarkan logika pembuatan versi.

val sr = StepsRecord(
    count = count,
    startTime = startTime,
    startZoneOffset = startZoneOffset,
    endTime = endTime,
    endZoneOffset = endZoneOffset,
    metadata = Metadata(
        clientRecordId = cid,
        clientRecordVersion = version
    )
)

Pembaruan dan penyisipan tidak otomatis menambah version setiap kali ada perubahan, sehingga mencegah instance yang tidak terduga menimpa data. Dengan demikian, Anda harus menyediakannya dengan nilai yang lebih tinggi secara manual.

Praktik terbaik untuk menulis data

Aplikasi hanya boleh menulis data yang berasal dari aplikasi sendiri ke Health Connect.

Jika data di aplikasi Anda telah diimpor dari aplikasi lain, aplikasi tersebut yang bertanggung jawab untuk menulis data ke Health Connect.

Sebaiknya terapkan logika yang menangani pengecualian penulisan seperti data berada di luar batas, atau error sistem internal. Anda dapat menerapkan strategi backoff dan percobaan ulang pada mekanisme penjadwalan tugas. Jika penulisan ke Health Connect pada akhirnya gagal, pastikan aplikasi Anda dapat melewati titik ekspor tersebut. Jangan lupa mencatat dan melaporkan error untuk membantu diagnosis.

Saat melacak data, ada beberapa saran yang dapat Anda ikuti, bergantung pada cara aplikasi Anda menulis data.

Pelacakan pasif

Mencakup aplikasi yang melakukan pelacakan kebugaran atau kesehatan pasif, seperti mencatat langkah atau detak jantung secara terus-menerus di latar belakang.

Aplikasi Anda perlu menulis data secara berkala ke Health Connect dengan cara berikut:

Di setiap sinkronisasi, hanya operasi tulis data baru dan data terbaru yang diubah sejak sinkronisasi terakhir.
Tentukan batas permintaan maksimal ke 1.000 data per permintaan tulis.
Gunakan WorkManager untuk menjadwalkan tugas latar belakang berkala, dengan jangka waktu minimal 15 menit.

Batasi tugas yang akan dijalankan, hanya saat perangkat sedang tidak ada aktivitas dan tidak kehabisan baterai.

val constraints = Constraints.Builder()
    .requiresBatteryNotLow()
    .requiresDeviceIdle(true)
    .build()

val writeDataWork = PeriodicWorkRequestBuilder<WriteDataToHealthConnectWorker>(
        15,
        TimeUnit.MINUTES,
        5,
        TimeUnit.MINUTES
    )
    .setConstraints(constraints)
    .build()

Pelacakan aktif

Ini mencakup aplikasi yang melakukan pelacakan berbasis peristiwa, seperti olahraga dan tidur, atau input pengguna manual seperti nutrisi. Kumpulan data ini dibuat saat aplikasi berada di latar depan, atau dalam peristiwa yang jarang terjadi ketika aplikasi digunakan beberapa kali dalam sehari.

Pastikan aplikasi Anda tidak membuat Health Connect tetap berjalan selama peristiwa berlangsung.

Data harus ditulis ke Health Connect dengan salah satu dari dua cara:

Menyinkronkan data ke Health Connect setelah peristiwa selesai. Misalnya, menyinkronkan data saat pengguna mengakhiri sesi olahraga yang dilacak.
Menjadwalkan tugas satu kali menggunakan WorkManager untuk menyinkronkan data nanti.

Praktik terbaik untuk perincian dan frekuensi penulisan

Saat menulis data ke Health Connect, gunakan resolusi yang sesuai. Menggunakan resolusi yang tepat akan membantu mengurangi beban penyimpanan, sambil tetap mempertahankan data yang konsisten dan akurat. Resolusi data mencakup 2 hal:

Frekuensi penulisan: seberapa sering aplikasi Anda mendorong data baru ke Health Connect. Misalnya, tulis data baru setiap 15 menit.
Perincian data tertulis: seberapa sering data yang didorong masuk diambil sampelnya. Misalnya, tulis sampel detak jantung setiap 5 dtk. Tidak semua jenis data memerlukan frekuensi sampel yang sama. Tidak banyak manfaat dari memperbarui jumlah langkah data setiap detik, dibandingkan dengan ritme yang lebih jarang, seperti setiap 60 detik. Namun, frekuensi sampel yang lebih tinggi dapat memberikan data kesehatan dan kebugaran mereka. Frekuensi sampel harus mencapai keseimbangan antara detail dan performa.

Menulis data yang dipantau sepanjang hari

Untuk data yang dikumpulkan secara berkelanjutan, seperti langkah-langkah, aplikasi Anda harus menulis ke Health Connect setidaknya setiap 15 menit sepanjang hari.

Jenis data	Satuan	Diperkirakan	Contoh
Langkah	langkah	Setiap 1 menit	23.14 - 23.15 - 5 langkah 23:16 - 23:17 - 22 langkah 23:17 - 23:18 - 8 langkah
Rangkaian Langkah Penjualan	langkah/mnt	Setiap 1 menit	23.14 - 23.15 - 5 spm 23.16 - 23.17 - 22 spm 23.17 - 23.18 - 8 spm
Dorongan kursi roda	mendorong	Setiap 1 menit	23:14 - 23:15 - 5 dorongan 23:16 - 23:17 - 22 dorongan 23:17 - 23:18 - 8 dorongan
Kalori Aktif yang Dibakar	Kalori	Setiap 15 menit	23:15 - 23:30 - 2 Kalori 23:30 - 23:45 - 25 Kalori 23:45 - 00:00 - 5 Kalori
Total Kalori yang Terbakar	Kalori	Setiap 15 menit	23:15 - 23:30 - 16 Kalori 23:30 - 23:45 - 16 Kalori 23:45 - 00:00 - 16 Kalori
Jarak	km/mnt	Setiap 1 menit	23.14-23.15 - 0,008 km 23:16 - 23:16 - 0,021 km 23:17 - 23:18 - 0,012 km
Elevasi yang Dicapai	m	Setiap 1 menit	20.36 - 20.37 - 3.048m 20.39 - 20.40 - 3.048m 23.23 - 23.24 - 9.144m
Lantai yang Dinaiki	lantai	Setiap 1 menit	23:14 - 23:15 - 5 lantai 23:16 - 23:16 - 22 lantai 23:17 - 23:18 - 8 lantai
Detak Jantung	bpm	Setiap 1 menit	06.11 - 55 bpm
Detak JantungVariabilitasRmssd	md	Setiap 1 menit	06.11 - 23 md
Tingkat Pernapasan	napas/menit	Setiap 1 menit	23.14 - 23.15 - 60 napas/menit 23:16 - 23:16 - 62 napas/menit 23:17 - 23:18 - 64 napas/menit
Saturasi Oksigen	%	Setiap 1 jam	6.11 - 95,208%

Menulis sesi

Data harus ditulis ke Health Connect di akhir latihan fisik atau tidur sesi.

Sebagai praktik terbaik, setiap sesi tidur atau sesi latihan harus ditulis dengan perangkat perekam dan metadata yang sesuai, termasuk RecordingMethod.

Setidaknya, aplikasi Anda harus mengikuti panduan dalam laporan "yang diharapkan" di bawah. Lokasi mungkin, ikuti jawaban "terbaik" panduan.

Data yang dilacak selama latihan

Jenis data	Satuan	Diperkirakan	Hormat kami,	Contoh
Langkah	langkah	Setiap 1 menit	Setiap 1 detik	23:14-23:15 - 5 langkah 23:16 - 23:17 - 22 langkah 23:17 - 23:18 - 8 langkah
Rangkaian Langkah Penjualan	langkah/mnt	Setiap 1 menit	Setiap 1 detik	23.14-23.15 - 35 spm 23.16 - 23.17 - 37 spm 23.17—23.18—40 spm
Dorongan kursi roda	mendorong	Setiap 1 menit	Setiap 1 detik	23:14-23:15 - 5 dorongan 23:16 - 23:17 - 22 dorongan 23:17 - 23:18 - 8 dorongan
Rangkaian Langkah PenjualanPedal Sepeda	napas per menit; npm [abbrv., use per context]	Setiap 1 menit	Setiap 1 detik	23.14-23.15 - 65 rpm 23.16 - 23.17 - 70 rpm 23.17 - 23.18 - 68 rpm
Daya	watt	Setiap 1 menit	Setiap 1 detik	23:14-23:15 - 250 watt 23:16 - 23:17 - 255 watt 23:17 - 23:18 - 245 watt
Kecepatan	km/mnt	Setiap 1 menit	Setiap 1 detik	23:14-23:15 - 0,3 km/mnt 23:16 - 23:17 - 0,4 km/mnt 23:17 - 23:18 -0,4 km/mnt
Jarak	km/m	Setiap 1 menit	Setiap 1 detik	23.14-23.15 - 0,008 km 23:16 - 23:16 - 0,021 km 23:17 - 23:18 - 0,012 km
Kalori Aktif yang Dibakar	Kalori	Setiap 1 menit	Setiap 1 detik	23:14-23:15 - 20 Kalori 23:16 - 23:17 - 20 Kalori 23:17 - 23:18 - 25 Kalori
Total Kalori yang Terbakar	Kalori	Setiap 1 menit	Setiap 1 detik	23:14-23:15 - 36 Kalori 23:16 - 23:17 - 36 Kalori 23:17 - 23:18 - 41 Kalori
Elevasi yang Dicapai	m	Setiap 1 menit	Setiap 1 detik	20.36 - 20.37 - 3.048m 20.39 - 20.40 - 3.048m 23.23 - 23.24 - 9.144m
ExerciseRoutes	lat/lng/alt	Setiap 3-5 detik	Setiap 1 detik
Detak Jantung	bpm	Setiap 1 menit	Setiap 1 detik	23.14-23.15 - 150 bpm 23.16 - 23.17 -152 bpm 23.17 - 23.18 - 155 bpm

Data yang dilacak saat tidur

Jenis data	Satuan	Contoh yang diharapkan	Contoh
Pengaturan Tidur	tahap	Periode waktu terperinci per tahapan tidur	23.46 - 23.50 - terbangun 23.50 - 23.56 - tidur ringan 23:56 - 00:16 - tidur nyenyak
Detak Jantung Istirahat	bpm	Satu nilai harian (hal pertama yang diharapkan di pagi hari)	06.11 - 60 bpm
Saturasi Oksigen	%	Satu nilai harian (hal pertama yang diharapkan di pagi hari)	6.11 - 95,208%