استخدام البيانات السابقة

تتيح واجهة برمجة التطبيقات 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 لا تتعارض مع't نقاط البيانات الحالية، استخدِم الطريقة 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.