使用 Android 备份服务备份键值对

Android 备份服务为您的 Android 应用中的键值数据提供云存储备份和恢复功能。在键值备份操作期间，应用的备份数据将传递到设备的备份传输。如果设备使用默认的 Google 备份传输，则数据将传递到 Android 备份服务进行存档。

每个应用用户的数据限制为 5MB。存储备份数据不收费。

有关 Android 备份选项的概述以及有关应备份和恢复哪些数据的指南，请参阅数据备份概述。

实现键值备份

要备份您的应用数据，您需要实现一个备份代理。备份管理器在备份和恢复期间都会调用您的备份代理。

要实现备份代理，您必须

在清单文件中使用 android:backupAgent 属性声明您的备份代理。
通过执行以下操作之一定义备份代理
- 扩展 BackupAgent
  
  该 BackupAgent 类提供了您的应用用于与备份管理器通信的核心接口。如果您直接扩展此类，则必须重写 onBackup() 和 onRestore() 以处理数据的备份和恢复操作。
- 扩展 BackupAgentHelper
  
  该 BackupAgentHelper 类提供了一个围绕 BackupAgent 类的便捷包装器，从而最大程度地减少了您需要编写的代码量。在您的 BackupAgentHelper 中，您必须使用一个或多个辅助对象，这些对象会自动备份和恢复某些类型的数据，因此您无需实现 onBackup() 和 onRestore()。除非您需要完全控制应用的备份，否则我们建议使用 BackupAgentHelper 处理应用的备份。
  
  Android 目前提供了备份辅助程序，这些程序将从 SharedPreferences 和内部存储中备份和恢复完整的文件。

在清单中声明备份代理

确定备份代理的类名后，请使用 <application> 标记中的 android:backupAgent 属性在清单中声明它。

例如

<manifest ... >
    ...
    <application android:label="MyApplication"
                 android:backupAgent="MyBackupAgent">
        <meta-data android:name="com.google.android.backup.api_key"
            android:value="unused" />
        <activity ... >
            ...
        </activity>
    </application>
</manifest>

为了支持旧版设备，我们建议将 API 密钥 <meta-data> 添加到您的 Android 清单文件中。Android 备份服务不再需要服务密钥，但某些旧版设备在备份时仍可能检查密钥。将 android:name 设置为 com.google.android.backup.api_key，并将 android:value 设置为 unused。

android:restoreAnyVersion 属性接受一个布尔值，指示您是否希望无论当前应用版本与生成备份数据版本相比如何，都恢复应用数据。默认值为 false。有关更多信息，请参阅检查恢复数据版本。

扩展 BackupAgentHelper

如果您希望从 SharedPreferences 或内部存储中备份完整文件，则应使用 BackupAgentHelper 构建您的备份代理。使用 BackupAgentHelper 构建备份代理所需的代码比扩展 BackupAgent 少得多，因为您不必实现 onBackup() 和 onRestore()。

您的 BackupAgentHelper 实现必须使用一个或多个备份助手。备份助手是一个专门的组件，BackupAgentHelper 会调用它来对特定类型的数据执行备份和恢复操作。Android 框架目前提供了两个不同的助手

SharedPreferencesBackupHelper 用于备份 SharedPreferences 文件。
FileBackupHelper 用于备份内部存储中的文件。

您可以在 BackupAgentHelper 中包含多个助手，但每种数据类型只需要一个助手。也就是说，如果您有多个 SharedPreferences 文件，则只需要一个 SharedPreferencesBackupHelper。

对于要添加到 BackupAgentHelper 的每个助手，您必须在 onCreate() 方法期间执行以下操作

实例化所需助手类的实例。在类构造函数中，您必须指定要备份的文件。
调用 addHelper() 将助手添加到您的 BackupAgentHelper。

以下部分介绍了如何使用每个可用的助手创建备份代理。

备份 SharedPreferences

当您实例化 SharedPreferencesBackupHelper 时，必须包含一个或多个 SharedPreferences 文件的名称。

例如，要备份名为 user_preferences 的 SharedPreferences 文件，使用 BackupAgentHelper 的完整备份代理如下所示

Kotlin

// The name of the SharedPreferences file
const val PREFS = "user_preferences"

// A key to uniquely identify the set of backup data
const val PREFS_BACKUP_KEY = "prefs"

class MyPrefsBackupAgent : BackupAgentHelper() {
    override fun onCreate() {
        // Allocate a helper and add it to the backup agent
        SharedPreferencesBackupHelper(this, PREFS).also {
            addHelper(PREFS_BACKUP_KEY, it)
        }
    }
}

Java

public class MyPrefsBackupAgent extends BackupAgentHelper {
    // The name of the SharedPreferences file
    static final String PREFS = "user_preferences";

    // A key to uniquely identify the set of backup data
    static final String PREFS_BACKUP_KEY = "prefs";

    // Allocate a helper and add it to the backup agent
    @Override
    public void onCreate() {
        SharedPreferencesBackupHelper helper =
                new SharedPreferencesBackupHelper(this, PREFS);
        addHelper(PREFS_BACKUP_KEY, helper);
    }
}

SharedPreferencesBackupHelper 包含备份和恢复 SharedPreferences 文件所需的所有代码。

当备份管理器调用 onBackup() 和 onRestore() 时，BackupAgentHelper 会调用您的备份助手来备份和恢复您指定的文件。

备份其他文件

当您实例化 FileBackupHelper 时，必须包含保存到应用内部存储的一个或多个文件的名称，如 getFilesDir() 所指定，这与 openFileOutput() 写入文件的位置相同。

例如，要备份名为 scores 和 stats 的两个文件，使用 BackupAgentHelper 的备份代理如下所示

Kotlin

// The name of the file
const val TOP_SCORES = "scores"
const val PLAYER_STATS = "stats"
// A key to uniquely identify the set of backup data
const val FILES_BACKUP_KEY = "myfiles"

class MyFileBackupAgent : BackupAgentHelper() {
    override fun onCreate() {
        // Allocate a helper and add it to the backup agent
        FileBackupHelper(this, TOP_SCORES, PLAYER_STATS).also {
            addHelper(FILES_BACKUP_KEY, it)
        }
    }
}

Java

public class MyFileBackupAgent extends BackupAgentHelper {
    // The name of the file
    static final String TOP_SCORES = "scores";
    static final String PLAYER_STATS = "stats";

    // A key to uniquely identify the set of backup data
    static final String FILES_BACKUP_KEY = "myfiles";

    // Allocate a helper and add it to the backup agent
    @Override
    public void onCreate() {
        FileBackupHelper helper = new FileBackupHelper(this,
                TOP_SCORES, PLAYER_STATS);
        addHelper(FILES_BACKUP_KEY, helper);
    }
}

FileBackupHelper 包含备份和恢复保存到应用内部存储的文件所需的所有代码。

但是，读取和写入内部存储中的文件**不是线程安全的**。为了确保备份代理不会与您的活动同时读取或写入文件，您必须在每次执行读取或写入时使用同步语句。例如，在您读取和写入文件的任何活动中，您都需要一个用作同步语句的内在锁的对象

Kotlin

// Object for intrinsic lock
companion object {
    val sDataLock = Any()
}

Java

// Object for intrinsic lock
static final Object sDataLock = new Object();

然后在每次读取或写入文件时创建带有此锁的同步语句。例如，以下是一个将游戏中最新得分写入文件的同步语句

Kotlin

try {
    synchronized(MyActivity.sDataLock) {
        val dataFile = File(filesDir, TOP_SCORES)
        RandomAccessFile(dataFile, "rw").apply {
            writeInt(score)
        }
    }
} catch (e: IOException) {
    Log.e(TAG, "Unable to write to file")
}

Java

try {
    synchronized (MyActivity.sDataLock) {
        File dataFile = new File(getFilesDir(), TOP_SCORES);
        RandomAccessFile raFile = new RandomAccessFile(dataFile, "rw");
        raFile.writeInt(score);
    }
} catch (IOException e) {
    Log.e(TAG, "Unable to write to file");
}

您应该使用相同的锁同步读取语句。

然后，在您的 BackupAgentHelper 中，您必须覆盖 onBackup() 和 onRestore() 以使用相同的内在锁同步备份和恢复操作。例如，上面提到的 MyFileBackupAgent 示例需要以下方法

Kotlin

@Throws(IOException::class)
override fun onBackup(
        oldState: ParcelFileDescriptor,
        data: BackupDataOutput,
        newState: ParcelFileDescriptor
) {
    // Hold the lock while the FileBackupHelper performs back up
    synchronized(MyActivity.sDataLock) {
        super.onBackup(oldState, data, newState)
    }
}

@Throws(IOException::class)
override fun onRestore(
        data: BackupDataInput,
        appVersionCode: Int,
        newState: ParcelFileDescriptor
) {
    // Hold the lock while the FileBackupHelper restores the file
    synchronized(MyActivity.sDataLock) {
        super.onRestore(data, appVersionCode, newState)
    }
}

Java

@Override
public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
          ParcelFileDescriptor newState) throws IOException {
    // Hold the lock while the FileBackupHelper performs back up
    synchronized (MyActivity.sDataLock) {
        super.onBackup(oldState, data, newState);
    }
}

@Override
public void onRestore(BackupDataInput data, int appVersionCode,
        ParcelFileDescriptor newState) throws IOException {
    // Hold the lock while the FileBackupHelper restores the file
    synchronized (MyActivity.sDataLock) {
        super.onRestore(data, appVersionCode, newState);
    }
}

扩展 BackupAgent

大多数应用都不需要直接扩展 BackupAgent 类，而应该扩展 BackupAgentHelper 以利用内置的助手类，这些类会自动备份和恢复您的文件。但是，您可能需要直接扩展 BackupAgent 来执行以下操作

对数据格式进行版本控制。例如，如果您预计需要修改写入应用数据的方式，则可以构建一个备份代理，以在恢复操作期间交叉检查应用版本，并在设备上的版本与备份数据的版本不同时执行任何必要的兼容性工作。有关更多信息，请参阅检查恢复数据版本。
指定要备份的数据部分。您可以指定要备份的数据部分以及如何将每个部分恢复到设备，而不是备份整个文件。这还可以帮助您管理不同的版本，因为您可以将数据读取和写入为唯一实体，而不是完整的文件。
备份数据库中的数据。如果您有一个 SQLite 数据库，希望在用户重新安装应用时恢复，则需要构建一个自定义的 BackupAgent，该代理在备份操作期间读取相应的数据，然后在恢复操作期间创建表并插入数据。

如果您不需要执行上述任何任务，并且希望从 SharedPreferences 或内部存储中备份完整文件，请参阅扩展 BackupAgentHelper。

必需方法

创建 BackupAgent 时，必须实现以下回调方法

onBackup()

在您请求备份后，备份管理器会调用此方法。在此方法中，您从设备读取应用数据，并将要备份的数据传递给备份管理器，如执行备份中所述。

onRestore()

在恢复操作期间，备份管理器会调用此方法。此方法会传递您的备份数据，您的应用可以使用这些数据恢复其以前的状态，如执行恢复中所述。

当用户重新安装应用时，系统会调用此方法来恢复任何备份数据，但您的应用也可以请求恢复。

执行备份

备份请求不会立即导致调用您的 onBackup() 方法。相反，备份管理器会等待适当的时间，然后对自上次备份执行以来已请求备份的所有应用执行备份。此时，您必须将应用数据提供给备份管理器，以便将其保存到云存储中。

只有备份管理器才能调用备份代理的 onBackup() 方法。每次应用数据发生更改并希望执行备份时，都必须通过调用 dataChanged() 来请求备份操作。有关更多信息，请参阅请求备份。

提示：在开发应用时，您可以使用 bmgr 工具从备份管理器启动立即备份操作。

当备份管理器调用您的 onBackup() 方法时，它会传递三个参数

oldState: 一个指向应用提供的上次备份状态的打开的只读 ParcelFileDescriptor。这不是来自云存储的备份数据，而是上次调用 onBackup() 时备份的数据的本地表示形式，由 newState 或 onRestore() 定义。onRestore() 在下一节中介绍。由于 onBackup() 不允许您读取云存储中现有的备份数据，因此您可以使用此本地表示形式来确定自上次备份以来您的数据是否已更改。
data: 一个 BackupDataOutput 对象，您可以使用它将备份数据传递给备份管理器。
newState: 一个指向文件的打开的读写 ParcelFileDescriptor，您必须在此文件中写入传递给 data 的数据的表示形式。表示形式可以像文件的最后修改时间戳一样简单。此对象在备份管理器下次调用您的 onBackup() 方法时作为 oldState 返回。如果您没有将备份数据写入 newState，则下次备份管理器调用 onBackup() 时，oldState 将指向一个空文件。

使用这些参数，实现您的 onBackup() 方法以执行以下操作

通过比较oldState与当前数据，检查您的数据自上次备份以来是否发生更改。您在oldState中读取数据的方式取决于您最初将其写入newState的方式（参见步骤 3）。记录文件状态最简单的方法是使用其上次修改时间戳。例如，以下是如何读取和比较来自oldState的时间戳

Kotlin

val instream = FileInputStream(oldState.fileDescriptor)
val dataInputStream = DataInputStream(instream)
try {
   // Get the last modified timestamp from the state file and data file
   val stateModified = dataInputStream.readLong()
   val fileModified: Long = dataFile.lastModified()
   if (stateModified != fileModified) {
       // The file has been modified, so do a backup
       // Or the time on the device changed, so be safe and do a backup
   } else {
       // Don't back up because the file hasn't changed
       return
   }
} catch (e: IOException) {
   // Unable to read state file... be safe and do a backup
}

Java

// Get the oldState input stream
FileInputStream instream = new FileInputStream(oldState.getFileDescriptor());
DataInputStream in = new DataInputStream(instream);

try {
   // Get the last modified timestamp from the state file and data file
   long stateModified = in.readLong();
   long fileModified = dataFile.lastModified();

   if (stateModified != fileModified) {
       // The file has been modified, so do a backup
       // Or the time on the device changed, so be safe and do a backup
   } else {
       // Don't back up because the file hasn't changed
       return;
   }
} catch (IOException e) {
   // Unable to read state file... be safe and do a backup
}

如果没有任何更改并且您不需要备份，请跳到步骤 3。

如果您的数据与oldState相比发生了更改，请将当前数据写入data，将其备份到云存储。

您必须将数据的每个块作为BackupDataOutput中的一个实体写入。实体是扁平化的二进制数据记录，由唯一的键字符串标识。因此，您备份的数据集在概念上是一组键值对。

要将实体添加到备份数据集，您必须
1. 调用writeEntityHeader()，传递要写入数据的唯一字符串键和数据大小。
2. 调用writeEntityData()，传递包含数据的字节缓冲区以及要从缓冲区写入的字节数，该字节数应与传递给writeEntityHeader()的大小匹配。
例如，以下代码将一些数据扁平化成字节流并将其写入单个实体
Kotlin
val buffer: ByteArray = ByteArrayOutputStream().run { DataOutputStream(this).apply { writeInt(playerName) writeInt(playerScore) } toByteArray() } val len: Int = buffer.size data.apply { writeEntityHeader(TOPSCORE_BACKUP_KEY, len) writeEntityData(buffer, len) }
Java
// Create buffer stream and data output stream for our data ByteArrayOutputStream bufStream = new ByteArrayOutputStream(); DataOutputStream outWriter = new DataOutputStream(bufStream); // Write structured data outWriter.writeUTF(playerName); outWriter.writeInt(playerScore); // Send the data to the Backup Manager via the BackupDataOutput byte[] buffer = bufStream.toByteArray(); int len = buffer.length; data.writeEntityHeader(TOPSCORE_BACKUP_KEY, len); data.writeEntityData(buffer, len);
对您要备份的每个数据片段执行此操作。您如何将数据划分为实体由您决定。您甚至可以使用一个实体。
无论您是否执行备份（在步骤 2 中），都将当前数据的表示形式写入newState ParcelFileDescriptor。备份管理器在本地保留此对象作为当前备份数据的表示形式。它在下一次调用onBackup()时将其作为oldState传递给您，以便您可以确定是否需要进行另一次备份，如步骤 1 中所述。如果您不将当前数据状态写入此文件，则oldState在下次回调期间将为空。

以下示例使用文件的上次修改时间戳将当前数据的表示形式保存到newState
Kotlin
val modified = dataFile.lastModified() FileOutputStream(newState.fileDescriptor).also { DataOutputStream(it).apply { writeLong(modified) } }
Java
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor()); DataOutputStream out = new DataOutputStream(outstream); long modified = dataFile.lastModified(); out.writeLong(modified);

执行恢复

当需要恢复应用数据时，备份管理器会调用备份代理的onRestore()方法。当它调用此方法时，备份管理器会传递您的备份数据，以便您将其恢复到设备上。

只有备份管理器才能调用onRestore()，这会在系统安装您的应用并找到现有备份数据时自动发生。

当备份管理器调用您的onRestore()方法时，它会传递三个参数

data: 一个BackupDataInput对象，允许您读取备份数据。
appVersionCode: 一个整数，表示您的应用的android:versionCode清单属性的值，在备份此数据时该值是什么。您可以使用它来交叉检查当前应用版本并确定数据格式是否兼容。有关如何使用它来处理不同版本的恢复数据的更多信息，请参阅检查恢复数据版本。
newState: 一个打开的读/写ParcelFileDescriptor，指向一个文件，您必须将使用data提供的最终备份状态写入该文件。此对象在下一次调用onBackup()时作为oldState返回。请记住，您还必须在onBackup()回调中写入相同的newState对象——在此处执行此操作也可确保传递给onBackup()的oldState对象即使在设备恢复后第一次调用onBackup()时也是有效的。

在您对onRestore()的实现中，您应该在data上调用readNextHeader()以迭代数据集中的所有实体。对于找到的每个实体，请执行以下操作

使用getKey()获取实体键。
将实体键与您应该在BackupAgent类中声明为静态最终字符串的已知键值列表进行比较。当键与您的一个已知键字符串匹配时，进入一个语句以提取实体数据并将其保存到设备
1. 使用getDataSize()获取实体数据大小，并创建一个该大小的字节数组。
2. 调用readEntityData()并将其传递给字节数组（数据将存储在此处），并指定起始偏移量和要读取的大小。
3. 您的字节数组现在已满。读取数据并根据需要将其写入设备。
在将数据读回并写回设备后，将数据的状态写入newState参数，就像在onBackup()期间一样。

例如，以下是如何恢复上一节示例中备份的数据

Kotlin

@Throws(IOException::class)
override fun onRestore(data: BackupDataInput, appVersionCode: Int,
                       newState: ParcelFileDescriptor) {
    with(data) {
        // There should be only one entity, but the safest
        // way to consume it is using a while loop
        while (readNextHeader()) {
            when(key) {
                TOPSCORE_BACKUP_KEY -> {
                    val dataBuf = ByteArray(dataSize).also {
                        readEntityData(it, 0, dataSize)
                    }
                    ByteArrayInputStream(dataBuf).also {
                        DataInputStream(it).apply {
                            // Read the player name and score from the backup data
                            playerName = readUTF()
                            playerScore = readInt()
                        }
                        // Record the score on the device (to a file or something)
                        recordScore(playerName, playerScore)
                    }
                }
                else -> skipEntityData()
            }
        }
    }

    // Finally, write to the state blob (newState) that describes the restored data
    FileOutputStream(newState.fileDescriptor).also {
        DataOutputStream(it).apply {
            writeUTF(playerName)
            writeInt(mPlayerScore)
        }
    }
}

Java

@Override
public void onRestore(BackupDataInput data, int appVersionCode,
                      ParcelFileDescriptor newState) throws IOException {
    // There should be only one entity, but the safest
    // way to consume it is using a while loop
    while (data.readNextHeader()) {
        String key = data.getKey();
        int dataSize = data.getDataSize();

        // If the key is ours (for saving top score). Note this key was used when
        // we wrote the backup entity header
        if (TOPSCORE_BACKUP_KEY.equals(key)) {
            // Create an input stream for the BackupDataInput
            byte[] dataBuf = new byte[dataSize];
            data.readEntityData(dataBuf, 0, dataSize);
            ByteArrayInputStream baStream = new ByteArrayInputStream(dataBuf);
            DataInputStream in = new DataInputStream(baStream);

            // Read the player name and score from the backup data
            playerName = in.readUTF();
            playerScore = in.readInt();

            // Record the score on the device (to a file or something)
            recordScore(playerName, playerScore);
        } else {
            // We don't know this entity key. Skip it. (Shouldn't happen.)
            data.skipEntityData();
        }
    }

    // Finally, write to the state blob (newState) that describes the restored data
    FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
    DataOutputStream out = new DataOutputStream(outstream);
    out.writeUTF(playerName);
    out.writeInt(mPlayerScore);
}

在此示例中，传递给onRestore()的appVersionCode参数未使用。但是，如果用户应用的版本实际已向后移动（例如，用户从应用的 1.5 版更改为 1.0 版），则您可能希望使用它。有关更多信息，请参阅下一节。

检查恢复数据版本

当备份管理器将您的数据保存到云存储时，它会自动包含您的应用版本，如清单文件的android:versionCode属性所定义。在备份管理器调用您的备份代理以恢复您的数据之前，它会查看已安装应用的android:versionCode并将其与恢复数据集中记录的值进行比较。如果恢复数据集中记录的版本比设备上的应用版本更新，则用户已降级其应用。在这种情况下，备份管理器将中止对您应用的恢复操作，并且不会调用您的onRestore()方法，因为恢复集被认为对旧版本没有意义。

您可以使用android:restoreAnyVersion属性覆盖此行为。将此属性设置为true以指示您希望恢复应用，无论恢复集版本如何。默认值为false。如果将其设置为true，则备份管理器将忽略android:versionCode并在所有情况下调用您的onRestore()方法。通过这样做，您可以手动检查onRestore()方法中的版本差异，并在版本不匹配时采取必要的步骤使数据兼容。

为了帮助您在恢复操作期间处理不同的版本，onRestore()方法将包含在恢复数据集中的版本代码作为appVersionCode参数传递给您。然后，您可以使用PackageInfo.versionCode字段查询当前应用的版本代码。例如

Kotlin

val info: PackageInfo? = try {
    packageManager.getPackageInfo(packageName, 0)
} catch (e: PackageManager.NameNotFoundException) {
    null
}

val version: Int = info?.versionCode ?: 0

Java

PackageInfo info;
try {
    String name = getPackageName();
    info = getPackageManager().getPackageInfo(name, 0);
} catch (NameNotFoundException nnfe) {
    info = null;
}

int version;
if (info != null) {
    version = info.versionCode;
}

然后将从PackageInfo获取的version与传递给onRestore()的appVersionCode进行比较。

请求备份

您可以随时通过调用dataChanged()来请求备份操作。此方法通知备份管理器您希望使用备份代理备份数据。然后，备份管理器将在将来的某个时间调用备份代理的onBackup()方法。通常，您应该在每次数据更改时（例如，当用户更改您要备份的应用首选项时）请求备份。如果您在备份管理器从您的代理请求备份之前多次调用dataChanged()，您的代理仍然只会收到一次对onBackup()的调用。

请求恢复

在应用的正常生命周期中，您不需要请求恢复操作。系统会在安装您的应用时自动检查备份数据并执行恢复。

迁移到自动备份

您可以通过在清单文件的<application>元素中将android:fullBackupOnly设置为true来将您的应用转换为全数据备份。在 Android 5.1（API 级别 22）或更低版本的设备上运行时，您的应用会忽略清单中的此值，并继续执行键值备份。在 Android 6.0（API 级别 23）或更高版本的设备上运行时，您的应用会执行自动备份而不是键值备份。

用户隐私

在 Google，我们敏锐地意识到用户对我们的信任以及我们保护用户隐私的责任。Google 会安全地将备份数据传输到 Google 服务器和从 Google 服务器传输备份数据，以提供备份和恢复功能。Google 会根据 Google 的隐私权政策将此数据视为个人信息。

此外，用户可以通过 Android 系统的备份设置禁用数据备份功能。当用户禁用备份时，Android 备份服务会删除所有保存的备份数据。用户可以在设备上重新启用备份，但 Android 备份服务不会恢复任何先前删除的数据。