סנכרון נתונים

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

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

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

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

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

העברת נתונים ל-Health Connect

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

הכנת הנתונים

בדרך כלל, הרשומות במאגר הנתונים של האפליקציה כוללות את הפרטים הבאים:

  • מפתח ייחודי, כמו UUID.
  • גרסה או חותמת זמן.

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

כתיבת נתונים ב-Health Connect

כדי להזין נתונים ל-Health Connect, מבצעים את השלבים הבאים:

  1. מקבלים רשימה של רשומות חדשות, מעודכנות או שנמחקו ממאגר הנתונים של האפליקציה.
  2. לכל רשומה, יוצרים אובייקט Record שמתאים לסוג הנתונים. לדוגמה, אפשר ליצור אובייקט WeightRecord לנתונים שקשורים למשקל.

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

    val recordVersion = 0L
// Specify as needed
// The clientRecordId is an ID that you choose for your record. This
// is often the same ID you use in your app's datastore.
val clientRecordId = "<your-record-id>"

val record = WeightRecord(
    metadata = Metadata.activelyRecorded(
        clientRecordId = clientRecordId,
        clientRecordVersion = recordVersion,
        device = Device(type = Device.TYPE_SCALE)
    ),
    weight = Mass.kilograms(62.0),
    time = Instant.now(),
    zoneOffset = ZoneOffset.UTC,
)
healthConnectClient.insertRecords(listOf()(record))

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

    healthConnectClient.insertRecords(arrayListOf(record))

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

שמירת מזהים של Health Connect

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

הפונקציה insertRecords מחזירה InsertRecordsResponse שמכיל את רשימת הערכים id. משתמשים בתשובה כדי לקבל את מזהי הרשומות ומאחסנים אותם.

val response = healthConnectClient.insertRecords(arrayListOf(record))

for (recordId in response.recordIdsList) {
    // Store recordId to your app's datastore
}

שליפת נתונים מ-Health Connect

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

קבלת טוקן שינויים

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

כדי לקבל אסימון Changes, קוראים ל-getChangesToken ומספקים את סוגי הנתונים הנדרשים.

val changesToken = healthConnectClient.getChangesToken(
    ChangesTokenRequest(recordTypes = setOf(WeightRecord::class))
)

בדיקה של שינויים בנתונים

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

  1. מתקשרים אל getChanges באמצעות הטוקן כדי לקבל רשימה של שינויים.
  2. בודקים את סוג השינוי של כל שינוי: UpsertionChange או DeletionChange, ומבצעים את הפעולות הנדרשות.
    • במקרה של UpsertionChange, רק שינויים שלא הגיעו מהאפליקציה שביצעה את הקריאה יתקבלו, כדי לוודא שלא מתבצע ייבוא חוזר של נתונים.
  3. מקצים את אסימון השינויים הבא כאסימון החדש.
  4. חוזרים על שלבים 1-3 עד שלא נותרים שינויים.
  5. אחסון האסימון הבא ושמירתו לייבוא עתידי.
suspend fun processChanges(token: String): String {
    var nextChangesToken = token
    do {
        val response = healthConnectClient.getChanges(nextChangesToken)
        response.changes.forEach { change ->
            when (change) {
                is UpsertionChange ->
                    if (change.record.metadata.dataOrigin.packageName != context.packageName) {
                        processUpsertionChange(change)
                    }
                is DeletionChange -> processDeletionChange(change)
            }
        }
        nextChangesToken = response.nextChangesToken
    } while (response.hasMore)
    // Return and store the changes token for use next time.
    return nextChangesToken
}

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

עיבוד שינויים בנתונים

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

מחיקת נתונים מ-Health Connect

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

שיטות מומלצות לסינכרון נתונים

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

תוקף הטוקן

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

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

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

אם האפליקציה מקבלת טוקנים של שינויים שהם פסולים או שתוקפם פג, מומלץ להשתמש באסטרטגיות הניהול הבאות בהתאם לאופן השימוש בהם בלוגיקה שלכם:

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

סוג הנתונים משנה את האסימונים

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

קריאות בחזית

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

קריאה ברקע

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

ייבוא תזמונים

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

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