דף זה תורגם על ידי Cloud Translation API.

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

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

ודאו שהאפליקציה מבצעת את הפעולות הבאות:

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

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

נתוני הפיד של Health Connect

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

הכנת הנתונים

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

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

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

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

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

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

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

מקבלים רשימה של רשומות חדשות או מעודכנות ממאגר הנתונים של האפליקציה.
לכל רשומה, צריך ליצור אובייקט Record שמתאים לסוג הנתונים הזה. לדוגמה, אפשר ליצור אובייקט WeightRecord לנתונים שקשורים למשקל.
מציינים אובייקט Metadata בכל Record באמצעות המפתח הייחודי ו את פרטי הגרסה ממאגר הנתונים של האפליקציה. אם אין גרסאות של הנתונים, אפשר להשתמש בערך Long של חותמת הזמן הנוכחית כחלופה.
```
val record = WeightRecord(
    metadata = Metadata(
        clientRecordId = "<Your record's Client ID>",
        clientRecordVersion = <Your record's version>
    ),
    weight = weight,
    time = time,
    zoneOffset = zoneOffset
)
```
להעלות נתונים ל-Health Connect באמצעות insertRecords. עלייה בנתונים פירושה שכל מודל הנתונים ב-Health Connect מוחלפים כל עוד clientRecordId קיימים במאגר הנתונים של Health Connect, וגם clientRecordVersion גבוה מהערך הקיים. אחרת, הנתונים המשוכפלים נכתבים כנתונים חדשים.
```
healthConnectClient.insertRecords(arrayListOf(record))
```

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

מזהים של Store Health Connect

אחרי העברת הרשומות ל-Health Connect, מאגר הנתונים של האפליקציה צריך: לאחסן את 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. אפשר להשתמש בהם כדי לבקש שינויים פונקציה זו מחזירה רשימה של שינויים בנתונים וגם אסימון שינויים חדש לשימוש הבא בזמן האימון.

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

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

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

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

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

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 שסופק כדי למחוק את הרשומה.

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

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

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

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

תפוגת האסימון

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

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

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

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

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

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

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

קריאה בחזית

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

תזמוני ייבוא

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

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