1# 应用接入数据备份恢复 2 3应用接入数据备份恢复需要通过BackupExtensionAbility实现。 4 5BackupExtensionAbility，是[Stage模型](../application-models/stage-model-development-overview.md)中扩展组件[ExtensionAbility](../application-models/extensionability-overview.md)的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复，备份哪些文件等。 6 7## 接口说明 8 9| 模块 | 类名 | 接口 | 接口描述 | 10| ----------- | ---------------------- | --------------------------------------------- | ----------------------------------------------------------------- | 11| application | BundleVersion | code: number | 应用版本号。 | 12| application | BundleVersion | name: string | 应用版本名称。 | 13| application | BackupExtensionAbility | onBackup(): void | 由Extension机制提供的，应由应用开发者扩展实现的触发备份前的回调。 | 14| application | BackupExtensionAbility | onRestore(bundleVersion: BundleVersion): void | 由Extension机制提供的，应由应用开发者扩展实现的触发恢复后的回调。 | 15| application | BackupExtensionAbility | context: ExtensionContext | BackupExtensionAbility的上下文环境，继承自Context。 | 16 17备份恢复扩展能力API的使用指导请参见[API参考](../reference/apis-core-file-kit/js-apis-application-backupExtensionAbility.md#backupextensionability)。 18 19## 约束与限制 20 21- 当备份恢复时，所有待备份文件及目录的路径不得超过4095字节，否则将导致未定义行为。 22- 当备份目录时，应用进程必须拥有读取该目录及其所有子目录的权限（DAC中的`r`），否则将导致备份失败。 23- 当备份文件时，应用进程必须拥有搜索该文件所有祖父级目录的权限（DAC中的`x`），否则将导致备份失败。 24 25## 开发步骤 26 271. 在应用配置文件`module.json5`中注册`extensionAbilities`相关配置 28 29 新增`"extensionAbilities"`字段，其中注册类型`"type"`设置为`"backup"`，元数据信息["metadata"](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md)新增一个`"name"`为`"ohos. extension. backup"`的条目。 30 31 BackupExtensionAbility配置文件示例： 32 33 ```json 34 { 35 "extensionAbilities": [ 36 { 37 "description": "$string:ServiceExtAbility", 38 "icon": "$media:icon", 39 "name": "BackupExtensionAbility", 40 "type": "backup", 41 "visible": true, 42 "metadata": [ 43 { 44 "name": "ohos.extension.backup", 45 "resource": "$profile:backup_config" 46 } 47 ], 48 // 在BackupExtension.ts文件里自定义继承BackupExtensionAbility，重写其中的onBackup和onRestore方法。 49 // 如果没有特殊要求可以空实现，则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。 50 "srcEntrance": "./ets/BackupExtension/BackupExtension.ts", 51 } 52 ] 53 } 54 ``` 55 562. 新增元数据资源配置文件 57 58 在元数据资源配置文件中，定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与`module.json5`中`"metadata.resource"`名称保持一致，其保存位置在工程的`resources/profile`文件夹下。 59 60 元数据资源配置文件示例： 61 62 ```json 63 { 64 "allowToBackupRestore": true, 65 "includes": [ 66 "/data/storage/el2/base/files/users/" 67 ], 68 "excludes": [ 69 "/data/storage/el2/base/files/users/hidden/" 70 ], 71 "fullBackupOnly": false, 72 "restoreDeps": "", 73 } 74 ``` 75 763. 开发者可以在`BackupExtension.ts`文件中自定义类继承的`BackupExtensionAbility`，通过重写其`onBackup`和`onRestore`方法，使其达到在备份预加工应用数据或者在恢复阶段加工待恢复文件。 77 78 如果没有特殊要求可以空实现，则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。 79 80 下面的示例展示了一个空实现的`BackupExtension.ts`文件。 81 82 ```ts 83 import BackupExtensionAbility, {BundleVersion} from '@ohos.application.BackupExtensionAbility'; 84 import Logger from '../common/Logger'; 85 86 const TAG = `FileBackupExtensionAbility`; 87 export default class BackupExtension extends BackupExtensionAbility { 88 async onBackup () { 89 Logger.info(TAG, `onBackup ok`); 90 } 91 92 async onRestore (bundleVersion : BundleVersion) { 93 Logger.info(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`); 94 Logger.info(TAG, `onRestore end`); 95 } 96 } 97 ``` 98 99### 元数据资源配置文件说明 100 101| 属性名称 | 数据类型 | 必填 | 含义 | 102| -------------------- | ---------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 103| allowToBackupRestore | 布尔值 | 是 | 是否允许备份恢复，默认为false。 | 104| includes | 字符串数组 | 否 | 应用沙箱中需要备份的文件和目录。<br>当模式串以非/开始时，表示一个相对于根路径的相对路径。<br>当`includes`已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用下述代码段内容作为默认值。 | 105| excludes | 字符串数组 | 否 | `includes`中无需备份的例外项。格式同`includes`。<br>当`excludes`已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用**空数组**作为默认值。 | 106| fullBackupOnly | 布尔值 | 否 | 是否使用应用默认恢复目录，默认值为false。当值为true时，恢复数据会以 **/data/storage/el2/backup/restore/** 为根目录解压数据。<br>当值为false或者不配置该字段时，恢复数据会以/为根目录解压数据。 | 107| restoreDeps | 字符串 | 否 | 应用恢复时依赖其他应用数据，默认值为""，需要配置的依赖应用名称，多个应用以 **,** 分隔。 | 108 109> **说明：** 110> 111> **有关fullBackupOnly字段的说明** 112> - 当fullBackupOnly为false时，恢复的数据意味着会对同路径下的同名文件进行覆盖。 113> - 当fullBackupOnly为true时，恢复数据会以 **/data/storage/el2/backup/restore/** 为根目录解压数据，开发者可在OnRestore内访问数据进行最终的恢复。 114> 115> 开发者可根据自身的业务场景，选择对应的恢复数据方式。如果配置了fullBackupOnly为true，那么开发者需要在OnRestore内自行实现恢复数据的逻辑。 116> 117> 举个例子：假设应用的数据备份路径为：**data/storage/el2/base/files/A/** 。那么在恢复时，数据会被解压到：**/data/storage/el2/backup/restore/data/storage/el2/base/files/A/** 目录下。 118 119**includes默认值：** 120 121```json 122{ 123 "includes": [ 124 "data/storage/el1/database/", 125 "data/storage/el1/base/files/", 126 "data/storage/el1/base/preferences/", 127 "data/storage/el1/base/haps/<module-name>/files/", 128 "data/storage/el1/base/haps/<module-name>/preferences/", 129 "data/storage/el2/database/", 130 "data/storage/el2/base/files/", 131 "data/storage/el2/base/preferences/", 132 "data/storage/el2/base/haps/<module-name>/files/", 133 "data/storage/el2/base/haps/<module-name>/preferences/", 134 "data/storage/el2/distributedfiles/" 135 ] 136} 137``` 138 139## 相关实例 140 141针对应用接入数据的备份与恢复，有以下相关实例可供参考： 142 143- [应用接入数据备份恢复（ArkTS）（Full SDK）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/FileManagement/FileBackupExtension) 144