כתיבת נתונים

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

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

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

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

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

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

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

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

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

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

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

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
)

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

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

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

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

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

כתיבת נתונים

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

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

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

עדכון נתונים

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

Metadata

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

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

כדי לעדכן נתונים, קודם צריך להכין את הרשומות הנדרשות. מבצעים שינויים ב רשומות לפי הצורך. לאחר מכן, צריך להתקשר אל 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)
        }

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

דיווח באמצעות מזהה רשומת לקוח

אם אתם משתמשים בערכים האופציונליים 'מזהה רשומת לקוח' ו-'Client Record Version', אנחנו ממליצים להשתמש ב-insertRecords במקום ב-updateRecords.

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

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

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

אחר כך אפשר לקרוא לפונקציות האלה בשרשור הראשי.

upsertSteps(healthConnectClient, pullStepsFromDatastore())

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

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

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

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

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

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

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

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

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

כתיבת פעילויות

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

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

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

מעקב אחר נתונים במהלך פעילות גופנית

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