العمل على البيانات السابقة

تتيح History API لتطبيقك إجراء عمليات مجمّعة في متجر اللياقة البدنية: قراءة بيانات الصحة والعافية التاريخية وإدراجها وتحديثها وحذفها. استخدِم History API لتنفيذ ما يلي:

  • يمكنك قراءة بيانات الصحة والعافية التي تم إدراجها أو تسجيلها باستخدام بيانات التطبيقات.
  • استيراد البيانات المجمعة إلى Google Fit.
  • تحديث البيانات في Google Fit
  • حذف البيانات السابقة التي خزّنها تطبيقك في السابق

لإدراج بيانات تحتوي على بيانات تعريف الجلسة، استخدم واجهة برمجة تطبيقات الجلسات:

قراءة البيانات

تتناول الأقسام التالية كيفية قراءة أنواع مختلفة من البيانات المجمّعة.

قراءة البيانات التفصيلية والمجمّعة

لقراءة البيانات التاريخية، أنشئ DataReadRequest مثال.

Kotlin

// Read the data that's been collected throughout the past week.
val endTime = LocalDateTime.now().atZone(ZoneId.systemDefault())
val startTime = endTime.minusWeeks(1)
Log.i(TAG, "Range Start: $startTime")
Log.i(TAG, "Range End: $endTime")

val readRequest =
    DataReadRequest.Builder()
        // The data request can specify multiple data types to return,
        // effectively combining multiple data queries into one call.
        // This example demonstrates aggregating only one data type.
        .aggregate(DataType.AGGREGATE_STEP_COUNT_DELTA)
        // Analogous to a "Group By" in SQL, defines how data should be
        // aggregated.
        // bucketByTime allows for a time span, whereas bucketBySession allows
        // bucketing by <a href="/fit/android/using-sessions">sessions</a>.
        .bucketByTime(1, TimeUnit.DAYS)
        .setTimeRange(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .build()

Java

// Read the data that's been collected throughout the past week.
ZonedDateTime endTime = LocalDateTime.now().atZone(ZoneId.systemDefault());
ZonedDateTime startTime = endTime.minusWeeks(1);
Log.i(TAG, "Range Start: $startTime");
Log.i(TAG, "Range End: $endTime");

DataReadRequest readRequest = new DataReadRequest.Builder()
        // The data request can specify multiple data types to return,
        // effectively combining multiple data queries into one call.
        // This example demonstrates aggregating only one data type.
        .aggregate(DataType.AGGREGATE_STEP_COUNT_DELTA)
        // Analogous to a "Group By" in SQL, defines how data should be
        // aggregated.
        // bucketByTime allows for a time span, while bucketBySession allows
        // bucketing by sessions.
        .bucketByTime(1, TimeUnit.DAYS)
        .setTimeRange(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .build();

يستخدم المثال السابق نقاط بيانات مجمّعة، حيث يتم احتساب كل DataPoint عدد الخطوات التي تم قطعها في اليوم. بالنسبة لحالة الاستخدام هذه بالذات، لنقاط البيانات المجمّعة ميزتين:

  • يتبادل تطبيقك ومتجر اللياقة البدنية كميات أصغر من البيانات.
  • لا يحتاج تطبيقك إلى تجميع البيانات يدويًا.

تجميع البيانات لأنواع أنشطة متعددة

يمكن لتطبيقك استخدام طلبات البيانات لاسترداد العديد من أنواع البيانات المختلفة. تشير رسالة الأشكال البيانية المثال التالي كيفية إنشاء DataReadRequest للحصول على السعرات الحرارية التي تم حرقها مقابل كل نشاط يتم إجراؤه خلال النطاق الزمني المحدد. تطابق البيانات الناتجة السعرات الحرارية لكل نشاط ويتم الإبلاغ عنها في تطبيق Google Fit، حيث يحصل كل نشاط على حزمته الخاصة لبيانات السعرات الحرارية.

Kotlin

val readRequest = DataReadRequest.Builder()
    .aggregate(DataType.AGGREGATE_CALORIES_EXPENDED)
    .bucketByActivityType(1, TimeUnit.SECONDS)
    .setTimeRange(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
    .build()

Java

DataReadRequest readRequest = new DataReadRequest.Builder()
        .aggregate(DataType.AGGREGATE_CALORIES_EXPENDED)
        .bucketByActivityType(1, TimeUnit.SECONDS)
        .setTimeRange(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .build();

بعد إنشاء مثيل DataReadRequest، استخدِم السمة HistoryClient.readData() لقراءة البيانات السابقة بشكل غير متزامن.

يوضح المثال التالي كيفية الحصول على مثيلات DataPoint من أ DataSet:

Kotlin

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
    .readData(readRequest)
    .addOnSuccessListener { response ->
        // The aggregate query puts datasets into buckets, so flatten into a
        // single list of datasets
        for (dataSet in response.buckets.flatMap { it.dataSets }) {
            dumpDataSet(dataSet)
        }
    }
    .addOnFailureListener { e ->
        Log.w(TAG,"There was an error reading data from Google Fit", e)
    }

fun dumpDataSet(dataSet: DataSet) {
    Log.i(TAG, "Data returned for Data type: ${dataSet.dataType.name}")
    for (dp in dataSet.dataPoints) {
        Log.i(TAG,"Data point:")
        Log.i(TAG,"\tType: ${dp.dataType.name}")
        Log.i(TAG,"\tStart: ${dp.getStartTimeString()}")
        Log.i(TAG,"\tEnd: ${dp.getEndTimeString()}")
        for (field in dp.dataType.fields) {
            Log.i(TAG,"\tField: ${field.name.toString()} Value: ${dp.getValue(field)}")
        }
    }
}

fun DataPoint.getStartTimeString() = Instant.ofEpochSecond(this.getStartTime(TimeUnit.SECONDS))
    .atZone(ZoneId.systemDefault())
    .toLocalDateTime().toString()

fun DataPoint.getEndTimeString() = Instant.ofEpochSecond(this.getEndTime(TimeUnit.SECONDS))
    .atZone(ZoneId.systemDefault())
    .toLocalDateTime().toString()

Java

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
        .readData(readRequest)
        .addOnSuccessListener (response -> {
            // The aggregate query puts datasets into buckets, so convert to a
            // single list of datasets
            for (Bucket bucket : response.getBuckets()) {
                for (DataSet dataSet : bucket.getDataSets()) {
                    dumpDataSet(dataSet);
                }
            }
        })
        .addOnFailureListener(e ->
            Log.w(TAG, "There was an error reading data from Google Fit", e));

}

private void dumpDataSet(DataSet dataSet) {
    Log.i(TAG, "Data returned for Data type: ${dataSet.dataType.name}");
    for (DataPoint dp : dataSet.getDataPoints()) {
        Log.i(TAG,"Data point:");
        Log.i(TAG,"\tType: ${dp.dataType.name}");
        Log.i(TAG,"\tStart: ${dp.getStartTimeString()}");
        Log.i(TAG,"\tEnd: ${dp.getEndTimeString()}");
        for (Field field : dp.getDataType().getFields()) {
            Log.i(TAG,"\tField: ${field.name.toString()} Value: ${dp.getValue(field)}");
        }
    }
}


private String getStartTimeString() {
    return Instant.ofEpochSecond(this.getStartTime(TimeUnit.SECONDS))
        .atZone(ZoneId.systemDefault())
        .toLocalDateTime().toString();
}

private String getEndTimeString() {
    return Instant.ofEpochSecond(this.getEndTime(TimeUnit.SECONDS))
            .atZone(ZoneId.systemDefault())
            .toLocalDateTime().toString();
}

قراءة البيانات الإجمالية اليومية

ويوفّر Google Fit أيضًا وصولاً سهلاً إلى الإجمالي اليومي نوع البيانات المحدد. يمكنك استخدام HistoryClient.readDailyTotal() لاسترداد نوع البيانات الذي تحدده اعتبارًا من منتصف الليل يوم في المنطقة الزمنية الحالية للجهاز. على سبيل المثال، ضع علامة في المربّع بجانب نوع بيانات TYPE_STEP_COUNT_DELTA لهذه الطريقة لاسترداد الإجمالي اليومي الخطوات. ويمكنك تمرير نوع بيانات فوري يتضمّن بيانات مجمّعة يومية الإجمالي. لمزيد من المعلومات حول أنواع البيانات المتوافقة، راجع DataType.getAggregateType

لا يتطلب Google Fit إذنًا للاشتراك في TYPE_STEP_COUNT_DELTA تعديل من "HistoryClient.readDailyTotal()" عند استدعاء هذه الطريقة باستخدام الحساب الافتراضي وليس النطاقات محددة. قد يكون ذلك مفيدًا إذا كنت تحتاج إلى استخدام بيانات الخطوات في المناطق التي يتعذّر عليك فيها استخدام لإظهار لوحة الأذونات، مثلاً على خلفيات شاشة ساعة Wear OS

يفضّل المستخدمون مشاهدة أعداد خطوات متسقة عبر تطبيق Google Fit، وتطبيقات أخرى، وخلفيات شاشة ساعة Wear OS، لأن هذا يوفر لهم تجربة متسقة وموثوقة. للحفاظ على اتساق أعداد الخطوات، اشترك في الخطوات في نظام Google Fit من تطبيقك أو خلفية شاشة الساعة، ثم تعديل العدد في onExitAmbient() لمزيد من المعلومات حول كيفية استخدام هذه البيانات في خلفية شاشة الساعة، يمكنك الاطّلاع على إضافات خلفيات شاشة الساعة ونموذج تطبيق Android WatchFace.

إدخال البيانات

لإدراج البيانات السابقة، يجب أولاً إنشاء DataSetمثيل:

Kotlin

// Declare that the data being inserted was collected during the past hour.
val endTime = LocalDateTime.now().atZone(ZoneId.systemDefault())
val startTime = endTime.minusHours(1)

// Create a data source
val dataSource = DataSource.Builder()
    .setAppPackageName(this)
    .setDataType(DataType.TYPE_STEP_COUNT_DELTA)
    .setStreamName("$TAG - step count")
    .setType(DataSource.TYPE_RAW)
    .build()

// For each data point, specify a start time, end time, and the
// data value -- in this case, 950 new steps.
val stepCountDelta = 950
val dataPoint =
    DataPoint.builder(dataSource)
        .setField(Field.FIELD_STEPS, stepCountDelta)
        .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .build()

val dataSet = DataSet.builder(dataSource)
    .add(dataPoint)
    .build()

Java

// Declare that the data being inserted was collected during the past hour.
ZonedDateTime endTime = LocalDateTime.now().atZone(ZoneId.systemDefault());
ZonedDateTime startTime = endTime.minusHours(1);

// Create a data source
DataSource dataSource = new DataSource.Builder()
        .setAppPackageName(this)
        .setDataType(DataType.TYPE_STEP_COUNT_DELTA)
        .setStreamName("$TAG - step count")
        .setType(DataSource.TYPE_RAW)
        .build();

// For each data point, specify a start time, end time, and the
// data value -- in this case, 950 new steps.
int stepCountDelta = 950;
DataPoint dataPoint = DataPoint.builder(dataSource)
        .setField(Field.FIELD_STEPS, stepCountDelta)
        .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .build();

DataSet dataSet = DataSet.builder(dataSource)
        .add(dataPoint)
        .build();

بعد إنشاء مثيل DataSet، استخدِم السمة HistoryClient.insertData لإضافة هذه البيانات السابقة بشكل غير متزامن.

Kotlin

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
    .insertData(dataSet)
    .addOnSuccessListener {
        Log.i(TAG, "DataSet added successfully!")
    }
    .addOnFailureListener { e ->
        Log.w(TAG, "There was an error adding the DataSet", e)
    }

Java

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
        .insertData(dataSet)
        .addOnSuccessListener (unused ->
                Log.i(TAG, "DataSet added successfully!"))
        .addOnFailureListener(e ->
                Log.w(TAG, "There was an error adding the DataSet", e));
}

إدارة نقاط البيانات المتعارضة

على كل DataPoint في DataSet لتطبيقك، يجب أن يحتوي على startTime وendTime يحدد فاصل زمني فريد خلال DataSet، بدون تداخل بين DataPoint الحالات.

إذا حاول تطبيقك إدراج DataPoint جديد يتعارض مع عنصر حالي DataPoint المثيل، يتم تجاهل DataPoint الجديد. لإدراج علامة جديدة DataPoint التي قد تتداخل مع نقاط البيانات الحالية، يمكنك استخدام HistoryClient.updateData الطريقة الموضّحة في مقالة تعديل البيانات.

لا يمكن إدراج نقطة بيانات إذا كانت مدتها تتداخل مع أي بيانات حالية
نقطة

الشكل 1. كيفية تعامل طريقة insertData() مع نقاط البيانات الجديدة التي تتعارض مع DataPoint حالية.

تحديث البيانات

يتيح Google Fit لتطبيقك تعديل بيانات الصحة والعافية السابقة. تم إدراجها مسبقًا. لإضافة البيانات السابقة الخاصة بـ "DataSet" جديد، أو لإضافة بيانات جديدة مثيلان (DataPoint) لا تتعارض مع البيانات الحالية النقاط، استخدِم طريقة HistoryApi.insertData.

لتعديل البيانات السابقة، استخدِم الطريقة HistoryClient.updateData. هذا النمط تؤدّي الطريقة إلى حذف أي مثيلات حالية DataPoint تتداخل مع DataPoint. المثيلات المضافة باستخدام هذه الطريقة.

لتعديل بيانات الصحة والعافية السابقة، عليك أولاً إنشاء DataSet. مثال:

Kotlin

// Declare that the historical data was collected during the past 50 minutes.
val endTime = LocalDateTime.now().atZone(ZoneId.systemDefault())
val startTime = endTime.minusMinutes(50)

// Create a data source
val dataSource  = DataSource.Builder()
    .setAppPackageName(this)
    .setDataType(DataType.TYPE_STEP_COUNT_DELTA)
    .setStreamName("$TAG - step count")
    .setType(DataSource.TYPE_RAW)
    .build()

// Create a data set
// For each data point, specify a start time, end time, and the
// data value -- in this case, 1000 new steps.
val stepCountDelta = 1000

val dataPoint = DataPoint.builder(dataSource)
    .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
    .setField(Field.FIELD_STEPS, stepCountDelta)
    .build()

val dataSet = DataSet.builder(dataSource)
    .add(dataPoint)
    .build()

Java

// Declare that the historical data was collected during the past 50 minutes.
ZonedDateTime endTime = LocalDateTime.now().atZone(ZoneId.systemDefault());
ZonedDateTime startTime = endTime.minusMinutes(50);

// Create a data source
DataSource dataSource = new DataSource.Builder()
        .setAppPackageName(this)
        .setDataType(DataType.TYPE_STEP_COUNT_DELTA)
        .setStreamName("$TAG - step count")
        .setType(DataSource.TYPE_RAW)
        .build();

// Create a data set
// For each data point, specify a start time, end time, and the
// data value -- in this case, 1000 new steps.
int stepCountDelta = 1000;

DataPoint dataPoint = DataPoint.builder(dataSource)
        .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .setField(Field.FIELD_STEPS, stepCountDelta)
        .build();

DataSet dataSet = DataSet.builder(dataSource)
        .add(dataPoint)
        .build();

بعد ذلك، استخدِم DataUpdateRequest.Builder() لإنشاء طلب جديد لتعديل البيانات. استخدِم طريقة HistoryClient.updateData لإنشاء الطلب:

Kotlin

val request = DataUpdateRequest.Builder()
    .setDataSet(dataSet)
    .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
    .build()

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
    .updateData(request)
    .addOnSuccessListener {
        Log.i(TAG, "DataSet updated successfully!")
    }
    .addOnFailureListener { e ->
        Log.w(TAG, "There was an error updating the DataSet", e)
    }

Java

DataUpdateRequest request = new DataUpdateRequest.Builder()
        .setDataSet(dataSet)
        .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .build();

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
        .updateData(request)
        .addOnSuccessListener(unused ->
                Log.i(TAG, "DataSet updated successfully!"))
        .addOnFailureListener(e ->
                Log.w(TAG, "There was an error updating the DataSet", e));

حذف البيانات

يتيح Google Fit لتطبيقك حذف بيانات الصحة والعافية السابقة. تم إدراجها مسبقًا.

لحذف البيانات السابقة، استخدِم HistoryClient.deleteData :

Kotlin

// Declare that this code deletes step count information that was collected
// throughout the past day.
val endTime = LocalDateTime.now().atZone(ZoneId.systemDefault())
val startTime = endTime.minusDays(1)

// Create a delete request object, providing a data type and a time interval
val request = DataDeleteRequest.Builder()
    .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
    .addDataType(DataType.TYPE_STEP_COUNT_DELTA)
    .build()

// Invoke the History API with the HistoryClient object and delete request, and
// then specify a callback that will check the result.
Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
    .deleteData(request)
    .addOnSuccessListener {
        Log.i(TAG, "Data deleted successfully!")
    }
    .addOnFailureListener { e ->
        Log.w(TAG, "There was an error with the deletion request", e)
    }

Java

// Declare that this code deletes step count information that was collected
// throughout the past day.
ZonedDateTime endTime = LocalDateTime.now().atZone(ZoneId.systemDefault());
ZonedDateTime startTime = endTime.minusDays(1);

// Create a delete request object, providing a data type and a time interval
DataDeleteRequest request = new DataDeleteRequest.Builder()
        .setTimeInterval(startTime.toEpochSecond(), endTime.toEpochSecond(), TimeUnit.SECONDS)
        .addDataType(DataType.TYPE_STEP_COUNT_DELTA)
        .build();

// Invoke the History API with the HistoryClient object and delete request, and
// then specify a callback that will check the result.
Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
        .deleteData(request)
        .addOnSuccessListener (unused ->
                Log.i(TAG, "Data deleted successfully!"))
        .addOnFailureListener(e ->
        Log.w(TAG, "There was an error with the deletion request", e));

يمكن للتطبيقات حذف البيانات من جلسات أو حذف جميع البيانات. لمزيد من المعلومات، يمكنك الاطلاع على مرجع واجهة برمجة التطبيقات لـ DataDeleteRequest

التسجيل للحصول على تحديثات البيانات

يمكن لتطبيقك قراءة بيانات جهاز الاستشعار الأولية في الوقت الفعلي من خلال التسجيل باستخدام SensorsClient

بالنسبة للأنواع الأخرى من البيانات الأقل تكرارًا ويتم احتسابها يدويًا، يمكن للتطبيق التسجيل لتلقي التحديثات عند إدخال هذه القياسات في قاعدة بيانات Google Fit. تتضمن أمثلة أنواع البيانات هذه الارتفاع والوزن وتمارين مثل رفع الأثقال؛ للحصول على مزيد من التفاصيل، يُرجى الاطّلاع على القائمة الكاملة من أنواع البيانات المتوافقة للتسجيل للحصول على التحديثات، استخدم HistoryClient.registerDataUpdateListener

يتيح مقتطف الرمز التالي إشعارًا للتطبيق عندما يدخل المستخدم إلى سطر جديد قيمة وزنها:

Kotlin

val intent = Intent(this, MyDataUpdateService::class.java)
val pendingIntent = PendingIntent.getService(this, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT)

val request = DataUpdateListenerRegistrationRequest.Builder()
    .setDataType(DataType.TYPE_WEIGHT)
    .setPendingIntent(pendingIntent)
    .build()

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
    .registerDataUpdateListener(request)
    .addOnSuccessListener {
        Log.i(TAG, "DataUpdateListener registered")
    }

Java

Intent intent = new Intent(this, MyDataUpdateService.class);
PendingIntent pendingIntent = PendingIntent.getService(this, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT)

DataUpdateListenerRegistrationRequest request = new DataUpdateListenerRegistrationRequest.Builder()
        .setDataType(DataType.TYPE_WEIGHT)
        .setPendingIntent(pendingIntent)
        .build();

Fitness.getHistoryClient(this, GoogleSignIn.getAccountForExtension(this, fitnessOptions))
        .registerDataUpdateListener(request)
        .addOnSuccessListener(unused ->
                Log.i(TAG, "DataUpdateListener registered"));

يمكن استخدام IntentService لتلقّي إشعارات بالتحديثات:

Kotlin

class MyDataUpdateService : IntentService("MyDataUpdateService") {
    override fun onHandleIntent(intent: Intent?) {
        val update = DataUpdateNotification.getDataUpdateNotification(intent)
        // Show the time interval over which the data points were collected.
        // To extract specific data values, in this case the user's weight,
        // use DataReadRequest.
        update?.apply {
            val start = getUpdateStartTime(TimeUnit.MILLISECONDS)
            val end = getUpdateEndTime(TimeUnit.MILLISECONDS)

            Log.i(TAG, "Data Update start: $start end: $end DataType: ${dataType.name}")
        }
    }
}

Java

public class MyDataUpdateService extends IntentService {

    public MyDataUpdateService(String name) {
        super("MyDataUpdateService");
    }

    @Override
    protected void onHandleIntent(@Nullable Intent intent) {
        if (intent != null) {
            DataUpdateNotification update = DataUpdateNotification.getDataUpdateNotification(intent);

            // Show the time interval over which the data points
            // were collected.
            // To extract specific data values, in this case the user's weight,
            // use DataReadRequest.
            if (update != null) {
                long start = update.getUpdateStartTime(TimeUnit.MILLISECONDS);
                long end = update.getUpdateEndTime(TimeUnit.MILLISECONDS);
            }

            Log.i(TAG, "Data Update start: $start end: $end DataType: ${dataType.name}");
        }
    }
}

يجب تعريف IntentService في ملف AndroidManifest.xml.