כתיבת נתונים

המדריך הזה תואם לגרסה 1.1.0-alpha12 של Health Connect.

במדריך הזה נסביר על התהליך של כתיבת נתונים או עדכון שלהם ב-Health Connect.

הגדרת מבנה הנתונים

לפני שכותבים נתונים, צריך להגדיר קודם את הרשומות. יש יותר מ-50 סוגים של נתונים, לכל אחד מהם יש מבנה משלו. בחומר העזרה של Jetpack מפורט מידע נוסף על סוגי הנתונים הזמינים.

רשומות בסיסיות

סוג הנתונים צעדים ב-Health Connect מתעד את מספר הצעדים שהמשתמש צעד בין שתי מדידות. ספירת הצעדים היא מדידה נפוצה בפלטפורמות של בריאות, כושר ואיכות חיים.

הדוגמה הבאה מראה איך להגדיר נתונים של ספירת צעדים:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 120,
    startTime = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    )
)

רשומות עם יחידות מידה

כדי לשמור על דיוק, מערכת Health Connect יכולה לאחסן ערכים יחד עם יחידות המידה שלהם. דוגמה לכך היא סוג הנתונים תזונה, שהוא רחב ומקיף. הוא כולל מגוון רחב של שדות אופציונליים של חומרים מזינים, החל מפחמימות כלליות ועד ויטמינים. כל נקודה על הגרף מייצגת את החומרים המזינים שנצרכו כחלק מארוחה או מפריט מזון.

בסוג הנתונים הזה, כל החומרים המזינים מיוצגים ביחידות של Mass, ואילו energy מיוצג ביחידות של Energy.

בדוגמה הבאה מוסבר איך להגדיר נתוני תזונה למשתמש שאכל בננה:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(1))

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 = startTime,
    endTime = endTime,
    startZoneOffset = ZoneOffset.UTC,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        device = Device(type = Device.TYPE_PHONE)
    )
)

רשומות עם נתוני סדרות

אפליקציית Health Connect יכולה לאחסן רשימה של נתוני סדרות. דוגמה לכך היא סוג הנתונים דופק, שמתעד סדרה של דגימות של פעימות לב שזוהו בין קריאות.

בסוג הנתונים הזה, הפרמטר samples מיוצג על ידי רשימה של דוגמאות של קצב הלב. כל דגימה מכילה ערך beatsPerMinute וערך time.

הדוגמה הבאה מראה איך להגדיר נתונים של סדרת דופקים:

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(5))

val heartRateRecord = HeartRateRecord(
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    // records 10 arbitrary data, to replace with actual data
    samples = List(10) { index ->
        HeartRateRecord.Sample(
            time = startTime + Duration.ofSeconds(index.toLong()),
            beatsPerMinute = 100 + index.toLong(),
        )
    },
    metadata = Metadata.autoRecorded(
        device = Device(type = Device.TYPE_WATCH)
    ))

כתיבת נתונים

אחד מתהליכי העבודה הנפוצים ב-Health Connect הוא כתיבת נתונים. כדי להוסיף רשומות, משתמשים ב-insertRecords.

בדוגמה הבאה מוסבר איך לכתוב נתונים עם מספרי שלבים:

suspend fun insertSteps(healthConnectClient: HealthConnectClient) {
    val endTime = Instant.now()
    val startTime = endTime.minus(Duration.ofMinutes(5))
    try {
        val stepsRecord = StepsRecord(
            count = 120,
            startTime = startTime,
            endTime = endTime,
            startZoneOffset = ZoneOffset.UTC,
            endZoneOffset = ZoneOffset.UTC,
            metadata = Metadata.autoRecorded(
                device = Device(type = Device.TYPE_WATCH)
            )
        )
        healthConnectClient.insertRecords(listOf(stepsRecord))
    } catch (e: Exception) {
        // Run error handling here
    }
}

עדכון נתונים

אם אתם צריכים לשנות רשומה אחת או יותר, במיוחד כשאתם צריכים לסנכרן את מאגר הנתונים של האפליקציה עם נתונים מ-Health Connect, אתם יכולים לעדכן את הנתונים. יש שתי דרכים לעדכן נתונים קיימים, בהתאם למזהה שמשמש לאיתור הרשומות.

Metadata

כדאי לבדוק קודם את הכיתה Metadata, כי היא נדרשת לעדכון הנתונים. בזמן היצירה, לכל Record ב-Health Connect יש שדה metadata. המאפיינים הבאים רלוונטיים לסנכרון:

מאפיינים תיאור
id לכל Record ב-Health Connect יש ערך id ייחודי.
Health Connect מאכלס את השדה הזה באופן אוטומטי כשמזינים רשומה חדשה.
lastModifiedTime כל Record גם עוקב אחרי הפעם האחרונה שבה הרשומה שונתה.
המערכת של Health Connect מאכלסת את השדה הזה באופן אוטומטי.
clientRecordId לכל Record יכול להיות מזהה ייחודי שמשויך אליו, שישמש כמקור לנתונים במאגר הנתונים של האפליקציה.
האפליקציה שלכם מספקת את הערך הזה.
clientRecordVersion כשהרשומה כוללת את הערך clientRecordId, אפשר להשתמש ב-clientRecordVersion כדי לאפשר לנתונים להישאר מסונכרנים עם הגרסה במאגר הנתונים של האפליקציה.
האפליקציה שלכם מספקת את הערך הזה.

עדכון באמצעות מזהה הרשומה

כדי לעדכן נתונים, צריך קודם להכין את הרשומות הנדרשות. מבצעים את השינויים הנדרשים ברשומים. לאחר מכן, קוראים ל-updateRecords כדי לבצע את השינויים.

בדוגמה הבאה מוסבר איך לעדכן נתונים. לשם כך, ערכי ההיסט של כל אזור מתואמים ל-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)
        }

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

הוספה או עדכון של רשומה באמצעות מזהה הלקוח

אם אתם משתמשים בערכים האופציונליים של מזהה רשומת הלקוח וגרסת רשומת הלקוח, מומלץ להשתמש ב-insertRecords במקום ב-updateRecords.

הפונקציה insertRecords יכולה לבצע עדכון נתונים. אם הנתונים קיימים ב-Health Connect על סמך הקבוצה הנתונה של מזהי רשומות הלקוח, הם יימחקו ויוחלפו בנתונים החדשים. אחרת, הוא נכתב כנתונים חדשים. התרחיש הזה שימושי בכל פעם שצריך לסנכרן נתונים ממאגר הנתונים של האפליקציה עם Health Connect.

הדוגמה הבאה מראה איך לבצע upsert בנתונים שחולצו ממאגר הנתונים של האפליקציה:

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(
        metadata = Metadata.autoRecorded(
            clientRecordId = "Your client record ID",
            device = Device(type = Device.TYPE_WATCH)
        ),
        // Assign more parameters for this record
    )
    appStepsRecords.add(sr)
    // ...
    return appStepsRecords
}

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

לאחר מכן, תוכלו להפעיל את הפונקציות האלה בשרשור הראשי.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

בדיקת ערך בגרסה של רשומת הלקוח

אם תהליך העדכון וההוספה של נתונים כולל את גרסת הרשומה של הלקוח, מערכת Health Connect מבצעת בדיקות השוואה בערכים של clientRecordVersion. אם הגרסה מהנתונים שהוכנסו גבוהה מהגרסה מהנתונים הקיימים, מתבצע ה-upsert. אחרת, התהליך מתעלם מהשינוי והערך נשאר ללא שינוי.

כדי לכלול את ניהול הגרסאות בנתונים, צריך לספק ל-Metadata.clientRecordVersion ערך Long על סמך הלוגיקה של ניהול הגרסאות.

val endTime = Instant.now()
val startTime = endTime.minus(Duration.ofMinutes(15))

val stepsRecord = StepsRecord(
    count = 100L,
    startTime = startTime,
    startZoneOffset = ZoneOffset.UTC,
    endTime = endTime,
    endZoneOffset = ZoneOffset.UTC,
    metadata = Metadata.manualEntry(
        clientRecordId = "Your supplied record ID",
        clientRecordVersion = 0L, // Your supplied record version
        device = Device(type = Device.TYPE_WATCH)
    )
)

פעולות ה-upsert לא מגדילות את הערך של version באופן אוטומטי בכל פעם שיש שינויים, כדי למנוע מקרים לא צפויים של כתיבה מעל נתונים. במקרה כזה, תצטרכו לספק לו ערך גבוה יותר באופן ידני.

שיטות מומלצות לכתיבה של נתונים

אפליקציות יכולות לכתוב ב-Health Connect רק נתונים מקוריים.

אם הנתונים באפליקציה מיובאים מאפליקציה אחרת, האחריות לכתוב את הנתונים שלה ב-Health Connect היא של האפליקציה האחרת.

מומלץ גם להטמיע לוגיקה שמטפלת בחריגות של כתיבה, כמו נתונים מחוץ למגבלות או שגיאת מערכת פנימית. אפשר להחיל את האסטרטגיות שלכם להשהיה ולניסיון חוזר על מנגנון תזמון משימות. אם הכתיבה ל-Health Connect נכשלת בסופו של דבר, צריך לוודא שהאפליקציה יכולה לעבור את נקודת הייצוא הזו. אל תשכחו לתעד שגיאות ולדווח עליהן כדי לעזור באבחון.

כשאתם עוקבים אחרי נתונים, יש כמה הצעות שאפשר לפעול לפיהן בהתאם לאופן שבו האפליקציה שלכם כותבת נתונים.

מעקב פסיבי

הרשאות אלה כוללות אפליקציות שמבצעות מעקב פסיבי אחר כושר או בריאות, כמו תיעוד של צעדים או דופק באופן רציף ברקע.

האפליקציה צריכה לכתוב נתונים באופן קבוע ב-Health Connect בדרכים הבאות:

  • בכל סנכרון, כותבים רק נתונים חדשים ונתונים מעודכנים ששונו מאז הסנכרון האחרון.
  • חלוקת בקשות למקטעים של עד 1,000 רשומות לכל בקשת כתיבה.
  • אפשר להשתמש ב-WorkManager כדי לתזמן משימות תקופתיות ברקע, עם פרק זמן של לפחות 15 דקות.

  • הגבלת משימות כך שיפעלו רק כשהמכשיר לא פעיל ורמת הטעינה של הסוללה לא נמוכה.

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

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

מעקב פעיל

ההגדרה הזו כוללת אפליקציות שמבצעות מעקב מבוסס-אירועים, כמו אימון ושינה, או קלט ידני של המשתמש, כמו תזונה. הרשומות האלה נוצרות כשהאפליקציה נמצאת בחזית, או במקרים נדירים שבהם משתמשים בה כמה פעמים ביום.

חשוב לוודא שהאפליקציה לא מפעילה את Health Connect במשך כל זמן האירוע.

יש לכתוב נתונים ב-Health Connect באחת משתי הדרכים הבאות:

  • לסנכרן את הנתונים עם Health Connect אחרי סיום האירוע. לדוגמה, סנכרון נתונים כשהמשתמש מסיים סשן אימון במעקב.
  • תוכלו לתזמן משימה חד-פעמית באמצעות WorkManager כדי לסנכרן את הנתונים מאוחר יותר.

שיטות מומלצות לרמת הפירוט ולתדירות של פעולות הכתיבה

כשכותבים נתונים ב-Health Connect, צריך להשתמש ברזולוציה המתאימה. שימוש ברזולוציה המתאימה עוזר להפחית את עומס האחסון, תוך שמירה על נתונים עקביים ומדויקים. פתרון בעיות בנתונים כולל שני דברים:

  1. תדירות הכתיבה: באיזו תדירות האפליקציה שלכם שולחת נתונים חדשים ל-Health Connect. לדוגמה, כתיבה של נתונים חדשים כל 15 דקות.
  2. רמת הפירוט של הנתונים שנכתבים: תדירות הדגימה של הנתונים שנשלחים. לדוגמה, אפשר לכתוב דגימות של דופק כל 5 שניות. לא כל סוג נתונים מחייב את אותה תדירות דגימה. אין הרבה תועלת בעדכון נתוני ספירת הצעדים בכל שנייה, בהשוואה לקצב עדכון פחות תדיר, כמו כל 60 שניות. עם זאת, שיעור דגימה גבוה יותר עשוי לספק למשתמשים תמונה מפורטת ומקיפה יותר של נתוני הבריאות והכושר שלהם. תדרי תדירות הדגימה צריכים למצוא איזון בין פירוט לביצועים.

כתיבת נתונים שנמצאים במעקב במהלך היום

לגבי נתונים שנאספים באופן שוטף, כמו צעדים, האפליקציה צריכה לכתוב ב-Health Connect לפחות כל 15 דקות במהלך היום.

סוג הנתונים

היחידה

צפוי

דוגמה

צעדים

צעדים

כל דקה

23:14 עד 23:15 – 5 שלבים

23:16 - 23:17 - 22 שלבים

23:17 עד 23:18 – 8 שלבים

StepsCadence

צעדים בדקה

כל דקה

23:14 עד 23:15 – 5 הודעות לשעה

23:16 - 23:17 - 22 spm

23:17 - 23:18 - 8 spm

דחיפות כיסא גלגלים

דחיפה

כל דקה

23:14 עד 23:15 – 5 דחפים

23:16 – 23:17 – 22 דחפים

23:17 עד 23:18 – 8 דחפים

ActiveCaloriesBurned

קלוריות

כל 15 דקות

23:15 עד 23:30 – 2 קלוריות

23:30 עד 23:45 – 25 קלוריות

23:45 עד 00:00 – 5 קלוריות

TotalCaloriesBurned

קלוריות

כל 15 דקות

23:15 עד 23:30 – 16 קלוריות

23:30 עד 23:45 – 16 קלוריות

23:45 עד 00:00 – 16 קלוריות

מרחק

קמ"ש

כל דקה

23:14-23:15 – 0.008 ק"מ

23:16 - 23:16 - 0.021 ק"מ

23:17 עד 23:18 – 0.012 ק"מ

ElevationGained

m

כל דקה

20:36 – 20:37 – 3.048m

20:39 עד 20:40 – 3.048 מ'

23:23 - 23:24 - 9.144m

FloorsClimbed

קומות

כל דקה

23:14 עד 23:15 – 5 קומות

23:16 - 23:16 - 22 קומות

23:17 עד 23:18 – 8 קומות

HeartRate

bpm

כל דקה

6:11 – 55 פעימות לדקה

HeartRateVariabilityRmssd

אלפיות שנייה

כל דקה

6:11 – 23 אלפיות השנייה

RespiratoryRate

נשימות בדקה

כל דקה

23:14 עד 23:15 – 60 נשימות בדקה

23:16 - 23:16 - 62 נשימות בדקה

23:17 עד 23:18 – 64 נשימות בדקה

OxygenSaturation

%

כל שעה

6:11 – 95.208%

כתיבת סשנים

צריך לכתוב את הנתונים ב-Health Connect בסיום האימון או סשן השינה.

מומלץ לכתוב כל סשן שינה או סשן אימון באמצעות מכשיר ההקלטה והמטא-נתונים המתאימים, כולל RecordingMethod.

לפחות, האפליקציה צריכה לפעול בהתאם להנחיות שמפורטות בעמודה 'צפוי' שבהמשך. במידת האפשר, כדאי לפעול לפי ההנחיות 'הטובות ביותר'.

נתונים שנאספים במהלך אימון

סוג הנתונים

היחידה

צפוי

המשך יום נעים

דוגמה

צעדים

צעדים

כל דקה

כל שנייה

23:14-23:15 – 5 שלבים

23:16 - 23:17 - 22 שלבים

23:17 עד 23:18 – 8 שלבים

StepsCadence

צעדים בדקה

כל דקה

כל שנייה

23:14-23:15 – 35 spm

23:16 - 23:17 - 37 spm

23:17 - 23:18 - 40 spm

דחיפות כיסא גלגלים

דחיפה

כל דקה

כל שנייה

23:14-23:15 – 5 דחפים

23:16 – 23:17 – 22 דחפים

23:17 עד 23:18 – 8 דחפים

CyclingPedalingCadence

נשימות בדקה

כל דקה

כל שנייה

23:14-23:15 – 65 סיבובים לדקה

23:16 - 23:17 - 70 סיבובים לדקה

23:17 – 23:18 – 68 סיבובים לדקה

כוח

ואט

כל דקה

כל שנייה

23:14-23:15 – 250 ואט

23:16 עד 23:17 – 255 ואט

23:17 – 23:18 – 245 ואט

מהירות

קמ"ש

כל דקה

כל שנייה

23:14-23:15 – 0.3 ק"מ לדקה

23:16 עד 23:17 – 0.4 ק"מ לדקה

23:17 עד 23:18 -0.4 קמ' לדקה

מרחק

קמ"ר

כל דקה

כל שנייה

23:14-23:15 – 0.008 ק"מ

23:16 - 23:16 - 0.021 ק"מ

23:17 עד 23:18 – 0.012 ק"מ

ActiveCaloriesBurned

קלוריות

כל דקה

כל שנייה

23:14-23:15 – 20 קלוריות

23:16 עד 23:17 – 20 קלוריות

23:17 – 23:18 – 25 קלוריות

TotalCaloriesBurned

קלוריות

כל דקה

כל שנייה

23:14-23:15 – 36 קלוריות

23:16 עד 23:17 – 36 קלוריות

23:17 עד 23:18 – 41 קלוריות

ElevationGained

m

כל דקה

כל שנייה

20:36 – 20:37 – 3.048m

20:39 עד 20:40 – 3.048 מ'

23:23 - 23:24 - 9.144m

ExerciseRoutes

lat/lng/alt

כל 3-5 שניות

כל שנייה

HeartRate

bpm

כל דקה

כל שנייה

23:14-23:15 – 150 פעימות בדקה

23:16 – 23:17 -152 bpm

23:17 עד 23:18 – 155 פעימות בדקה

נתונים שנאספים במהלך השינה

סוג הנתונים

היחידה

טעימות צפויות

דוגמה

שלבי השינה

שלב

תקופת זמן מפורטת לכל שלב שינה

23:46 עד 23:50 – ערות

23:50 עד 23:56 – שינה קלה

23:56 עד 00:16 – שינה עמוקה

RestingHeartRate

bpm

ערך יומי יחיד (צפוי להתקבל בשעות הבוקר המוקדמות)

6:11 – 60 פעימות לדקה

OxygenSaturation

%

ערך יומי יחיד (צפוי להתקבל בשעות הבוקר המוקדמות)

6:11 – 95.208%