应用接入数据备份恢复需要通过BackupExtensionAbility实现。
BackupExtensionAbility是Stage模型中扩展组件ExtensionAbility的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为,包括是否允许备份恢复,备份哪些文件等。
备份恢复扩展能力关键接口如下表所示。API的接口使用指导请参见@ohos.application.BackupExtensionAbility (备份恢复扩展能力)和@ohos.file.BackupExtensionContext (备份恢复扩展能力)。
| 接口名 | 描述 |
|---|---|
| onBackup(): void | 数据备份准备阶段,迁移备份数据前回调。 |
| onBackupEx(backupInfo: string): string | Promise<string> | 数据备份准备阶段,迁移备份数据前回调,支持传递备份信息和返回备份结果。 |
| onRestore(bundleVersion: BundleVersion): void | 数据恢复阶段,备份数据迁移完成后回调。 |
| onRestoreEx(bundleVersion: BundleVersion, restoreInfo: string): string | Promise<string> | 数据恢复阶段,备份数据迁移完成后回调,支持传递恢复信息和返回恢复结果。 |
| onRelease(scenario: number): Promise<void> | 备份或恢复完成时的特殊处理,备份或恢复完成时回调。 说明:从API version 20开始支持该接口。 |
在应用配置文件module.json5中注册extensionAbilities相关配置
新增"extensionAbilities"字段,其中注册类型"type"设置为"backup",元数据信息"metadata"新增一个"name"为"ohos.extension.backup"的条目。
BackupExtensionAbility配置文件示例:
{
"extensionAbilities": [
{
"description": "$string:ServiceExtAbility",
"icon": "$media:icon",
"name": "BackupExtensionAbility",
"type": "backup",
"exported": false,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
],
"srcEntry": "./ets/BackupExtension/BackupExtension.ets"
}
]
} 新增元数据资源配置文件
在元数据资源配置文件中,定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与module.json5中"metadata.resource"例如"backup_config.json"名称保持一致,其保存位置在工程的resources/base/profile文件夹下。
元数据资源配置文件示例:
{
"allowToBackupRestore": true,
"includes": [
"/data/storage/el2/base/files/users/"
],
"excludes": [
"/data/storage/el2/base/files/users/hidden/"
],
"fullBackupOnly": false,
"restoreDeps": ""
} 开发者可以在BackupExtension.ets文件中自定义类继承的BackupExtensionAbility,通过重写其onBackup/onBackupEx和onRestore/onRestoreEx方法,使其达到在备份阶段预加工应用数据或者在恢复阶段加工待恢复文件。
如果没有特殊要求可以空实现,则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。
下面的示例展示了一个空实现的BackupExtension.ets文件:
// onBackup && onRestore
import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
import {hilog} from '@kit.PerformanceAnalysisKit';
const TAG = `FileBackupExtensionAbility`;
export default class BackupExtension extends BackupExtensionAbility {
// onBackup
async onBackup () {
hilog.info(0x0000, TAG, `onBackup ok`);
}
// onRestore
async onRestore (bundleVersion : BundleVersion) {
hilog.info(0x0000, TAG, `onRestore end`);
}
} import { BackupExtensionAbility } from '@kit.CoreFileKit';
import { BundleVersion } from '@kit.CoreFileKit';
// ...
interface ErrorInfo {
type: string,
errorCode: number,
errorInfo: string
}
// ...
class BackupExt extends BackupExtensionAbility {
// onBackupEx
async onBackupEx(backupInfo: string): Promise<string> {
console.info('onBackupEx ok');
let errorInfo: ErrorInfo = {
type: 'ErrorInfo',
errorCode: 0,
errorInfo: 'app diy error info'
}
return JSON.stringify(errorInfo);
}
// onRestoreEx
async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> {
console.info(`onRestoreEx begin`);
let errorInfo: ErrorInfo = {
type: 'ErrorInfo',
errorCode: 0,
errorInfo: 'app diy error info'
}
return JSON.stringify(errorInfo);
}
// ...
} 从API 20开始,开发者如需在应用备份恢复完成后执行一些特殊操作,例如清理备份或恢复时应用创建的临时文件,可以在BackupExtension.ets文件中自定义类继承的BackupExtensionAbility,通过重写其onRelease方法,当备份或恢复完成时,会执行onRelease方法以执行开发者自定义的行为。
onRelease具有超时机制,应用若在5秒内未完成onRelease操作,将触发备份恢复结束时的应用进程退出流程。
下面的示例展示了需要清理临时文件目录时onRelease的实现:
import { BackupExtensionAbility } from '@kit.CoreFileKit';
// ...
import { fileIo } from '@kit.CoreFileKit';
// ...
const SCENARIO_BACKUP: number = 1;
const SCENARIO_RESTORE: number = 2;
class BackupExt extends BackupExtensionAbility {
// ...
// onRelease
async onRelease(scenario: number): Promise<void> {
// 清理应用在此目录下创建的备份或恢复临时文件。
let filePath: string = this.context.filesDir + '/.temp/';
try {
if (scenario == SCENARIO_BACKUP) {
// 备份场景,应用自行实现处理,以清理备份产生的临时文件为例
console.info(`onRelease begin`);
await fileIo.rmdir(filePath);
console.info(`onRelease end, rmdir succeed`);
}
if (scenario == SCENARIO_RESTORE) {
// 恢复场景,应用自行实现处理,以清理恢复产生的临时文件为例
console.info(`onRelease begin`);
await fileIo.rmdir(filePath);
console.info(`onRelease end, rmdir succeed`);
}
} catch (error) {
console.error(`onRelease failed with error. Code: ${error.code}, message: ${error.message}`);
}
}
} | 属性名称 | 数据类型 | 必填 | 含义 |
|---|---|---|---|
| allowToBackupRestore | 布尔值 | 是 | 是否允许备份恢复,默认为false。true为允许备份恢复,false为不允许备份恢复。 |
| includes | 字符串数组 | 否 | 应用沙箱中需要备份的文件和目录。 当模式串以非/开始时,表示一个相对于根路径的相对路径。 includes支持的路径清单列表如下述代码段内容所示,当配置includes时请确保配置路径范围包含在其中,不支持备份el3、el4路径。 当includes已配置时,备份恢复框架会采用开发者配置的模式串,否则将会采用下述代码段内容作为默认值。 |
| excludes | 字符串数组 | 否 | includes中无需备份的例外项。格式同includes。 在配置excludes时,请确保其范围在includes的子集中。 当excludes已配置时,备份恢复框架会采用开发者配置的模式串,否则将会采用空数组作为默认值。 |
| fullBackupOnly | 布尔值 | 否 | 是否使用应用默认恢复目录,默认值为false。当值为true时,恢复数据时会通过临时路径进行缓存,临时路径可通过backupDir获取。当值为false或者不配置该字段时,恢复数据会以'/'为根目录解压数据。 |
| restoreDeps | 字符串 | 否 | 不推荐使用,应用恢复时依赖其他应用数据,默认值为"",需要配置依赖应用名称。当前仅支持最多一个依赖项。配置的依赖仅在一次恢复任务上下文生效,如果一次恢复任务中没有检测到依赖应用,则忽略该依赖描述继续执行恢复任务。依赖应用未恢复或者恢复失败都会导致本应用恢复失败。 |
| extraInfo | json串 | 否 | 额外信息可通过该字段传递。 |
字段说明:
有关fullBackupOnly字段的说明
开发者可根据自身的业务场景,选择对应的恢复数据方式。
示例:
假设应用的数据备份路径为:data/storage/el2/base/files/A/ 。那么在恢复时:
includes支持的路径清单列表如下:
{
"includes": [
"data/storage/el1/database/",
"data/storage/el1/base/files/",
"data/storage/el1/base/preferences/",
"data/storage/el1/base/haps/*/files/",
"data/storage/el1/base/haps/*/preferences/",
"data/storage/el2/database/",
"data/storage/el2/base/files/",
"data/storage/el2/base/preferences/",
"data/storage/el2/base/haps/*/files/",
"data/storage/el2/base/haps/*/preferences/",
"data/storage/el2/distributedfiles/",
"data/storage/el5/database/",
"data/storage/el5/base/files/",
"data/storage/el5/base/preferences/",
"data/storage/el5/base/haps/*/files/",
"data/storage/el5/base/haps/*/preferences/"
]
}