Zapisywanie danych

Ten przewodnik opisuje proces zapisywania i aktualizowania danych w Health Connect.

Skonfiguruj strukturę danych

Przed zapisaniem danych musimy najpierw skonfigurować rekordy. W przypadku ponad 50 typów danych każdy ma swoją własną strukturę. Więcej informacji o dostępnych typach danych znajdziesz w dokumentacji Jetpacka.

Rekordy podstawowe

Typ danych Kroki w Health Connect rejestruje liczbę kroków, które użytkownik wykonał między odczytami. Liczba kroków to często spotykana metoda pomiarów na platformach związanych ze zdrowiem, aktywnością i samopoczuciem.

Poniższy przykład pokazuje, jak skonfigurować dane o liczbie kroków:

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

Rekordy z jednostkami miary

Aby zapewnić dokładność, Health Connect może przechowywać wartości wraz z jednostkami miary. Jednym z przykładów jest typ danych Żywienie, który jest bardzo obszerny. Zawierają wiele opcjonalnych pól odżywczych, od węglowodanów po witaminy. Każdy punkt danych odzwierciedla składniki odżywcze, które zostały potencjalnie spożyte jako część posiłku lub elementu żywnościowego.

W tym typie danych wszystkie składniki odżywcze są wyrażone w jednostkach Mass, a energy – w jednostce Energy.

Poniższy przykład pokazuje, jak ustawić dane dotyczące wartości odżywczej użytkownika, który zjadł banana:

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
)

Rekordy z danymi serii

Health Connect może przechowywać listę danych serii. Jednym z przykładów jest typ danych Tętno, który rejestruje serię próbek tętna wykrytych między odczytami.

W tym typie danych parametr samples jest reprezentowany przez listę Próbek tętna. Każda próbka zawiera wartości beatsPerMinute i time.

Poniższy przykład pokazuje, jak ustawić dane dotyczące serii tętna:

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(),
        )
    }
)

Zapisywanie danych

Jednym z typowych przepływów pracy w Health Connect jest zapisywanie danych. Aby dodać rekordy, użyj funkcji insertRecords.

Ten przykład pokazuje, jak zapisywać liczbę kroków wstawianych danych:

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
    }
}

Zaktualizuj dane

Jeśli musisz zmienić co najmniej jeden rekord, zwłaszcza gdy musisz synchronizować magazyn danych aplikacji z danymi z Health Connect, możesz zaktualizować swoje dane. Istnieją 2 sposoby aktualizowania istniejących danych, które zależą od identyfikatora używanego do wyszukiwania rekordów.

Metadane

Warto najpierw przyjrzeć się klasie Metadata, ponieważ jest to konieczne przy aktualizowaniu danych. Po utworzeniu każda wartość Record w Health Connect ma swoje pole metadata. Do synchronizacji mają znaczenie:

Właściwości Opis
id Każdy Record w Health Connect ma unikalną wartość id.
Health Connect wypełni tę wartość automatycznie podczas wstawiania nowego rekordu.
lastModifiedTime W każdej pozycji Record rejestruje się również czas ostatniej modyfikacji rekordu.
Health Connect uzupełni tę wartość automatycznie.
clientRecordId Z każdym identyfikatorem Record może być powiązany unikalny identyfikator, który będzie służyć jako odwołanie w magazynie danych aplikacji.
Twoja aplikacja ma tę wartość.
clientRecordVersion Jeśli rekord ma clientRecordId, właściwość clientRecordVersion może być używana do zapewnienia synchronizacji danych z wersją w magazynie danych aplikacji.
Twoja aplikacja ma tę wartość.

Zaktualizuj przez identyfikator rekordu

Aby zaktualizować dane, przygotuj najpierw wymagane rekordy. W razie potrzeby wprowadź zmiany w rekordach. Następnie wywołaj updateRecords, aby wprowadzić zmiany.

Z przykładu poniżej dowiesz się, jak zaktualizować dane. W tym celu każdy rekord ma wartość przesunięcia strefy dostosowywaną do czasu 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
    }
}

Wstaw za pomocą identyfikatora rekordu klienta

Jeśli używasz opcjonalnych wartości identyfikatora rekordu klienta i wersji rekordu klienta, zalecamy użycie insertRecords zamiast updateRecords.

Funkcja insertRecords może wyświetlać dane przez upsert. Jeśli dane istnieją w Health Connect na podstawie podanego zestawu identyfikatorów rekordów klienta, zostaną zastąpione. W przeciwnym razie jest zapisywany jako nowe dane. Ten scenariusz jest przydatny, gdy chcesz zsynchronizować dane z magazynu danych aplikacji z Health Connect.

Ten przykład pokazuje, jak wykonać upsert na danych pobranych z magazynu danych aplikacji:

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
    }
}

Potem możesz je wywoływać w wątku głównym.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

Sprawdzanie wartości w wersji rekordu klienta

Jeśli proces wprowadzania danych przez upsert obejmuje wersję rekordu klienta, Health Connect przeprowadza testy porównawcze wartości clientRecordVersion. Jeśli wersja z wstawionych danych jest wyższa niż wersja z istniejących danych, zachodzi upsert. W przeciwnym razie zmiana zostanie zignorowana, a wartość pozostaje taka sama.

Aby w danych uwzględnić obsługę wersji, musisz podać Metadata.clientRecordVersion z wartością Long opartą na Twojej logice obsługi wersji.

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

Upsert nie zwiększają automatycznie wartości version po każdej zmianie, co zapobiega nieoczekiwanym przypadkom zastępowania danych. Musisz więc ręcznie podać mu większą wartość.

Sprawdzone metody zapisu danych

Aplikacje mogą zapisywać w Health Connect tylko dane pochodzące od siebie.

Jeśli dane w Twojej aplikacji zostały zaimportowane z innej aplikacji, obowiązkiem tej aplikacji jest zapisanie własnych danych w Health Connect.

Warto też wdrożyć logikę, która obsługuje wyjątki zapisu, na przykład dane spoza granic lub wewnętrzny błąd systemu. Strategie ponawiania i ponawiania prób możesz zastosować w mechanizmie planowania zadań. Jeśli wysyłanie wiadomości do Health Connect się nie powiedzie, upewnij się, że aplikacja może przejść poza ten punkt eksportu. Nie zapomnij zapisać i zgłosić błędów, aby ułatwić diagnostykę.

Przy śledzeniu danych możesz skorzystać z kilku sugestii w zależności od tego, jak aplikacja zapisuje dane.

Śledzenie pasywne

Dotyczy to aplikacji, które wykonują pasywne śledzenie aktywności fizycznej lub zdrowia, np. rejestrują kroki lub tętno w trybie ciągłym w tle.

Aplikacja musi okresowo zapisywać dane w Health Connect w ten sposób:

  • Przy każdej synchronizacji zapisuj tylko nowe dane i zaktualizowane dane, które zostały zmodyfikowane od ostatniej synchronizacji.
  • Podziel żądania na fragment do maksymalnie 1000 rekordów na żądanie zapisu.
  • Za pomocą WorkManager zaplanuj okresowe zadania w tle, które będą obejmować co najmniej 15 minut.

  • Ogranicz zadania tak, aby były uruchamiane tylko wtedy, gdy urządzenie jest bezczynne i nie ma niskiego poziomu baterii.

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

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

Aktywne śledzenie

Dotyczy to aplikacji, które śledzą zdarzenia na podstawie zdarzeń, np. ćwiczeń i snu, lub generują ręcznie dane użytkownika, np. odżywianie. Rekordy te są tworzone, gdy aplikacja działa na pierwszym planie lub w rzadkich sytuacjach, gdy aplikacja jest używana kilka razy dziennie.

Sprawdź, czy aplikacja nie działa w Health Connect przez cały czas trwania zdarzenia.

Dane należy zapisywać w Health Connect na 1 z 2 sposobów:

  • Zsynchronizuj dane z Health Connect po zakończeniu zdarzenia. Na przykład: synchronizuj dane, gdy użytkownik zakończy śledzoną sesję ćwiczeniową.
  • Zaplanuj jednorazowe zadanie za pomocą WorkManager, aby później zsynchronizować dane.

Sprawdzone metody dotyczące szczegółowości i częstotliwości zapisów

Zapisując dane w Health Connect, używaj odpowiedniej rozdzielczości. Wybór odpowiedniej rozdzielczości pomaga zmniejszyć obciążenie pamięci masowej, jednocześnie zachowując spójność i dokładność danych. Rozpoznawanie danych obejmuje 2 kwestie:

  1. Częstotliwość zapisów: jak często aplikacja przekazuje nowe dane do Health Connect. np. zapisywać nowe dane co 15 minut.
  2. Szczegółowość zapisanych danych: jak często przesyłane dane były próbkowane. Na przykład zapisuj próbki tętna co 5 s. Nie każdy typ danych wymaga takiej samej częstotliwości próbkowania. Modyfikowanie danych o liczbie kroków co sekundę ma niewielkie korzyści w porównaniu z mniejszym cyklem, np. co 60 sekund. Wyższe częstotliwości próbkowania mogą jednak zapewniać użytkownikom bardziej szczegółowe i szczegółowe dane dotyczące zdrowia i aktywności fizycznej. Częstotliwość próbkowania powinna zapewniać równowagę między szczegółami a skutecznością.

Zapisuj dane monitorowane w ciągu dnia

W przypadku danych zbieranych na bieżąco (np. kroków) aplikacja powinna zapisywać się w Health Connect co najmniej co 15 minut w ciągu dnia.

Typ danych

Jednostka

Oczekiwana

Przykład

Kroki

kroki

Co minutę

23:14–23:15 – 5 kroków

23:16-23:17 – 22 kroki

23:17–23:18 – 8 kroków

Kadencja kroków

kroki/min

Co minutę

23:14–23:15 – 5 kr./min

23:16–23:17 – 22 kr./min

23:17–23:18 – 20:00

Pchnięcia wózka inwalidzkiego

wypychanie

Co minutę

23:14–23:15 – 5 uderzeń

23:16–23:17 – 22 pchnięcia

23:17–23:18 – 8 pchnięć

Aktywne kalorie

Kalorie

Co 15 minut

23:15 - 23:30 - 2 kalorie

23:30 - 23:45 - 25 kcal

23:45 - 00:00 - 5 kalorii

Wszystkie spalone kalorie

kcal

Co 15 minut

23:15-23:30 – 16 kcal

23:30-23:45 – 16 kcal

23:45-00:00 – 16 kcal

Odległość

km/min

Co minutę

23:14–23:15 – 0,008 km

23:16-23:16-0,021 km

23:17–23:18 – 0,012 km

Przebyte przewyższenie

min

Co minutę

20:36-20:37-3,048

20:39-20:40-3,048

23:23–23:24 – 9,144

Pokonane piętra

piętra

Co minutę

23:14–23:15 – 5 pięter

23:16–23:16 – 22 piętra

23:17–23:18 – 8 pięter

Tętno

uderz./min

Co minutę

6:11–55 uderz./min

Zmienność rytmu serca

ms

Co minutę

6:11–23 ms

Częstość oddychania

oddechy/min

Co minutę

23:14-23:15 – 60 oddechów/min

23:16-23:16 – 62 oddechy/min

23:17-23:18 – 64 oddechy/min

Nasycenie tlenem

%

Co godzinę

6:11–95,208%

Zapisywanie sesji

Dane powinny być zapisywane w Health Connect po zakończeniu treningu lub sesji snu.

Sprawdzoną metodą jest zapisanie każdej sesji snu lub sesji ćwiczeń za pomocą urządzenia do nagrywania i odpowiednich metadanych, np. RecordingMethod.

Zgłoszenie powinno być zgodne przynajmniej ze wskazówkami podanymi w kolumnie „Oczekiwane” poniżej. Jeśli to możliwe, postępuj zgodnie z „najlepszymi” wskazówkami.

Dane śledzone podczas ćwiczenia

Typ danych

Jednostka

Oczekiwana

Pozdrawiam

Przykład

Kroki

kroki

Co minutę

Co sekundę

23:14–23:15 – 5 kroków

23:16-23:17 – 22 kroki

23:17–23:18 – 8 kroków

Kadencja kroków

kroki/min

Co minutę

Co sekundę

23:14–23:15 – 35 kr./min

23:16–23:17 – 37 kr./min

23:17–23:18 – 40 kr./min

Pchnięcia wózka inwalidzkiego

wypychanie

Co minutę

Co sekundę

23:14–23:15 – 5 uderzeń

23:16–23:17 – 22 pchnięcia

23:17–23:18 – 8 pchnięć

Ścieżka rowerowa

obr./min

Co minutę

Co sekundę

23:14–23:15 – 65 obr./min

23:16-23:17 - 70 obr./min

23:17-23:18-68 obr./min

Moc

waty

Co minutę

Co sekundę

23:14–23:15 – 250 watów

23:16–23:17 – 255 watów

23:17–23:18 – 245 watów

Szybkość

km/min

Co minutę

Co sekundę

23:14–23:15 – 0,3 km/min

23:16-23:17 - 0,4 km/min

23:17-23:18 -0,4 km/min

Odległość

km/m

Co minutę

Co sekundę

23:14–23:15 – 0,008 km

23:16-23:16-0,021 km

23:17–23:18 – 0,012 km

Aktywne kalorie

kcal

Co minutę

Co sekundę

23:14-23:15 – 20 kcal

23:16-23:17 – 20 kcal

23:17-23:18 – 25 kcal

Wszystkie spalone kalorie

kcal

Co minutę

Co sekundę

23:14-23:15 – 36 kcal

23:16-23:17 – 36 kcal

23:17-23:18 – 41 kcal

Przebyte przewyższenie

min

Co minutę

Co sekundę

20:36-20:37-3,048

20:39-20:40-3,048

23:23–23:24 – 9,144

Trasy ćwiczeń

szer./dł./sł./sł.

Co 3–5 sekund

Co sekundę

Tętno

uderz./min

Co minutę

Co sekundę

23:14–23:15–150 uderz./min

23:16–23:17–152 uderz./min

23:17–23:18–155 uderz./min

Dane śledzone podczas snu

Typ danych

Jednostka

Oczekiwane próbki

Przykład

Ocena snu

etapie

Szczegółowe przedziały czasu dla poszczególnych faz snu

23:46–23:50 – obudzenie

23:50–23:56 – sen płytki

23:56-00:16 – sen głęboki

Tętno spoczynkowe

uderz./min

Jedna wartość dzienna (oczekiwana z rana)

6:11–60 uderz./min

Nasycenie tlenem

%

Jedna wartość dzienna (oczekiwana z rana)

6:11–95,208%