Zapisywanie danych

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

Wskazówka: więcej wskazówek dotyczących zapisywania danych znajdziesz w Film dla deweloperów aplikacji na Androida dotyczący odczytywania i zapisu danych w Health Connect.

Skonfiguruj strukturę danych

Przed zapisaniem danych musimy najpierw skonfigurować rekordy. Jeśli masz więcej niż 50 danych każdy ma swoją strukturę. Więcej informacji o danych znajdziesz w dokumentacji Jetpacka. typy dostępnych typów.

Rekordy podstawowe

Typ danych Kroki w Health Connect rejestruje liczbę kroków między odczytami. Liczba kroków to typowy pomiar na platformach dotyczących zdrowia, fitnessu i dobrego samopoczucia.

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

Health Connect może przechowywać wartości wraz z jednostkami miary, dokładności. Jednym z przykładów jest bardzo duży typ danych Żywienie. kompleksowego. Obejmuje on różnorodne opcjonalne pola odżywcze, od węglowodanów do witamin. Każdy punkt danych reprezentuje składniki odżywcze potencjalnie spożyte w ramach posiłku lub produktu spożywczego.

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

Z przykładu poniżej dowiesz się, jak ustawić dane dotyczące odżywiania dla 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. między odczytami.

W tym typie danych parametr samples jest reprezentowany przez listę Próbki tętna. Każda próbka zawiera pole 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 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ć jeden lub więcej rekordów, zwłaszcza gdy zsynchronizować magazyn danych aplikacji z danymi z Health Connect, możesz zaktualizować danych. Istnieją 2 sposoby aktualizowania istniejących danych, Identyfikator używany do wyszukiwania rekordów.

Metadane

Warto najpierw zapoznać się z zajęciami Metadata, ponieważ jest to konieczne, aktualizowania danych. Po utworzeniu każda Record w Health Connect ma przypisaną metadata. Te właściwości są powiązane z: synchronizacja:

Właściwości	Opis
id	Każde Record w Health Connect ma unikalne id . Health Connect wypełni tę wartość automatycznie podczas wstawiania nowego rekordu.
lastModifiedTime	W sekcji Record zapisywane są również informacje o czasie ostatniego wyświetlenia przez użytkownika rekord został zmodyfikowany. Health Connect wypełni tę wartość automatycznie.
clientRecordId	Każdy element Record może mieć unikalny identyfikator powiązany z i używać go jako odniesienia w magazynie danych aplikacji. Taka wartość jest Twoja aplikacja.
clientRecordVersion	Jeśli rekord zawiera element clientRecordId, parametr clientRecordVersion może służyć do zezwalania na dane na: synchronizuj je z wersją w aplikacji magazyn danych. Taka wartość jest Twoja aplikacja.

Zaktualizuj przez identyfikator rekordu

Aby zaktualizować dane, przygotuj najpierw wymagane rekordy. Wprowadź wszelkie zmiany w w razie potrzeby. Następnie zadzwoń pod numer updateRecords, aby zmian.

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

Uwaga: funkcja updateRecords działa tylko wtedy, gdy rekord ma identyfikator rekordu. Jeśli jeden z rekordów nie ma identyfikatora, występuje RemoteException.

Wstaw za pomocą identyfikatora rekordu klienta

Jeśli używasz opcjonalnych wartości Client Record ID (Identyfikator rekordu klienta) i Client Record Version (Wersja rekordu klienta), zalecamy używanie insertRecords zamiast updateRecords.

Funkcja insertRecords może wyświetlać dane przez upsert. Jeśli dane istnieją w Health Connect na podstawie danego zbioru identyfikatory rekordu klienta – zostaną zastąpione. W przeciwnym razie jest zapisywany jako nowe dane. Ten scenariusz jest przydatny, gdy chcesz zsynchronizować dane z z aplikacji do zarządzania danymi o zdrowiu.

Ten przykład pokazuje, jak wykonać upsert na danych pobranych z do 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 obejmuje wersję rekordu klienta, stan Connect wykonuje testy porównawcze w narzędziu clientRecordVersion. . Jeśli wersja z wstawionych danych jest wyższa niż z istniejących danych, następuje wywołanie upsert. W przeciwnym razie zignoruje zmianę, a wartość pozostanie taka sama.

Aby uwzględnić obsługę wersji w danych, musisz dostarczyć Metadata.clientRecordVersion z wartością Long na podstawie Twojej wersji logikę logiczną.

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 wprowadzeniu zmian. co zapobiega nieoczekiwanym przypadkom zastępowania danych. Dlatego musisz ręcznie wprowadzić większą wartość.

Sprawdzone metody zapisu danych

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

Jeśli dane w aplikacji zostały zaimportowane z innej aplikacji, obowiązkiem trafia na inną aplikację, aby zapisać własne dane w Health Connect.

Warto też wdrożyć logikę, która obsługuje wyjątki, takie jak dane są poza granicami lub wystąpił wewnętrzny błąd systemu. Możesz zastosować strategii ponawiania i ponawiania w mechanizmie planowania zadań. Jeśli piszesz na Aplikacja Health Connect kończy się niepowodzeniem. Upewnij się, że aplikacja może zostać przeniesiona danego punktu eksportu. Nie zapomnij zapisać i zgłosić błędów, aby ułatwić diagnostykę.

Przy śledzeniu danych możesz skorzystać z kilku wskazówek, w zależności od sposobu zapisu danych przez aplikację.

Śledzenie pasywne

Obejmuje to aplikacje, które wykonują pasywne śledzenie aktywności lub zdrowia, stale rejestrując kroki lub tętno w tle.

Aplikacja musi okresowo zapisywać dane w Health Connect na w następujący sposób:

• Przy każdej synchronizacji zapisuj tylko nowe dane i zaktualizowane dane, które zostały zmodyfikowane od przy ostatniej synchronizacji.
• Podziel żądania na fragment do maksymalnie 1000 rekordów na żądanie zapisu.
• Korzystaj z WorkManager, aby planować okresowe zadania w tle, co najmniej 15 minut.

• Ogranicz zadania tak, aby były uruchamiane tylko wtedy, gdy urządzenie jest nieaktywne i nie jest zbyt niskie 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ą zdarzeniami, np. ćwiczeń, snu, lub ręczne wprowadzanie danych, np. żywienie. Rekordy są tworzone, gdy aplikacja znajduje się na pierwszym planie lub w rzadkich sytuacjach, gdy jest używane kilka razy dziennie.

Sprawdź, czy aplikacja nie działa przez cały czas trwania Health Connect w czasie 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 zsynchronizuj dane, gdy użytkownik zakończy śledzone ćwiczenia.
• Planowanie jednorazowego zadania przy użyciu WorkManager do synchronizowania danych później.

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

Zapisując dane w Health Connect, używaj odpowiedniej rozdzielczości. Korzystanie z odpowiednia rozdzielczość pomaga zmniejszyć obciążenie pamięci masowej, przy zachowaniu spójne i dokładne dane. 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. Aktualizowanie liczby kroków nie ma zbyt wielu korzyści danych co sekundę, a nie rzadziej, np. co 60 sek. Wyższe częstotliwości próbkowania mogą jednak zapewniać użytkownikom szczegółowe dane o zdrowiu i aktywności fizycznej. Częstotliwość próbkowania który powinien znaleźć równowagę między szczegółami a skutecznością.

Zapisuj dane monitorowane w ciągu dnia

W przypadku danych zbieranych na bieżąco, takich jak kroki, aplikacja powinna zapisywać w Health Connect co najmniej raz w ciągu dnia 15 minut.

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	Kalorie	Co 15 minut	23:15 - 23:30 - 16 kalorii 23:30 - 23:45 - 16 kalorii 23:45 - 00:00 - 16 kalorii
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 snu .

Zalecamy, aby każda sesja snu lub sesje ćwiczeń były zapisywane w urządzenie nagrywające i odpowiednie metadane, w tym RecordingMethod

Zgłoszenie powinno być zgodne z wytycznymi podanymi w sekcji „Oczekiwane” kolumnę poniżej. Gdzie użyj „najlepszego”, ze 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
Zasilanie	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	Kalorie	Co minutę	Co sekundę	23:14-23:15 - 20 kalorii 23:16 - 23:17 - 20 kalorii 23:17 - 23:18 - 25 kcal
Wszystkie spalone kalorie	Kalorie	Co minutę	Co sekundę	23:14-23:15 - 36 kalorii 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%