1# 应用接入数据备份恢复
2
3应用接入数据备份恢复需要通过BackupExtensionAbility实现。
4
5BackupExtensionAbility，是[Stage模型](../application-models/stage-model-development-overview.md)中扩展组件[ExtensionAbility](../application-models/extensionability-overview.md)的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复，备份哪些文件等。
6
7## 接口说明
8
9备份恢复扩展能力API的接口使用指导请参见[BackupExtensionAbility API参考](../reference/apis-core-file-kit/js-apis-application-backupExtensionAbility.md#backupextensionability)和[BackupExtensionContext API参考](../reference/apis-core-file-kit/js-apis-file-backupextensioncontext.md)。
10
11## 约束与限制
12
13- 当备份恢复时，所有待备份文件及目录的路径不得超过4095字节，否则将导致未定义行为。
14- 当备份目录时，应用进程必须拥有读取该目录及其所有子目录的权限（DAC中的`r`），否则将导致备份失败。
15- 当备份文件时，应用进程必须拥有搜索该文件所有祖父级目录的权限（DAC中的`x`），否则将导致备份失败。
16- 当备份恢复时，所有待备份恢复的文件及目录不支持相对路径(../)和软链接。
17
18## 开发步骤
19
201. 在应用配置文件`module.json5`中注册`extensionAbilities`相关配置
21
22   新增`"extensionAbilities"`字段，其中注册类型`"type"`设置为`"backup"`，元数据信息["metadata"](../reference/apis-ability-kit/js-apis-bundleManager-metadata.md)新增一个`"name"`为`"ohos.  extension. backup"`的条目。
23
24   BackupExtensionAbility配置文件示例：
25
26   ```json
27   {
28       "extensionAbilities": [
29           {
30               "description": "$string:ServiceExtAbility",
31               "icon": "$media:icon",
32               "name": "BackupExtensionAbility",
33               "type": "backup",
34               "exported": false,
35               "metadata": [
36                   {
37                       "name": "ohos.extension.backup",
38                       "resource": "$profile:backup_config"
39                   }
40               ],
41               // 在BackupExtension.ets文件里自定义继承BackupExtensionAbility，重写其中的onBackup/onBackupEx和
42               // onRestore/onRestoreEx方法，推荐使用onBackupEx/onRestoreEx。
43               // 如果没有特殊要求可以空实现，则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。
44               "srcEntry": "./ets/BackupExtension/BackupExtension.ets",
45           }
46       ]
47   }
48   ```
49
502. 新增元数据资源配置文件
51
52   在元数据资源配置文件中，定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与`module.json5`中`"metadata.resource"例如"backup_config.json"`名称保持一致，其保存位置在工程的`resources/base/profile`文件夹下。
53
54   元数据资源配置文件示例：
55
56   ```json
57   {
58       "allowToBackupRestore": true,
59       "includes": [
60           "/data/storage/el2/base/files/users/"
61       ],
62       "excludes": [
63           "/data/storage/el2/base/files/users/hidden/"
64       ],
65       "fullBackupOnly": false,
66       "restoreDeps": ""
67   }
68   ```
69
703. 开发者可以在`BackupExtension.ets`文件中自定义类继承的`BackupExtensionAbility`，通过重写其`onBackup/onBackupEx`和`onRestore/onRestoreEx`方法，使其达到在备份预加工应用数据或者在恢复阶段加工待恢复文件。
71
72   如果没有特殊要求可以空实现，则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。
73
74   下面的示例展示了一个空实现的`BackupExtension.ets`文件：
75
76    ```ts
77    //onBackup && onRestore
78    import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
79    import {hilog} from '@kit.PerformanceAnalysisKit';
80
81    const TAG = `FileBackupExtensionAbility`;
82    export default class BackupExtension extends  BackupExtensionAbility {
83      //onBackup
84      async onBackup ()   {
85        hilog.info(0x0000, TAG, `onBackup ok`);
86      }
87      //onRestore
88      async onRestore (bundleVersion : BundleVersion) {
89        hilog.info(0x0000, TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
90        hilog.info(0x0000, TAG, `onRestore end`);
91      }
92    }
93    ```
94
95    ```ts
96    //onBackupEx && onRestoreEx
97    import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
98
99    interface ErrorInfo {
100      type: string,
101      errorCode: number,
102      errorInfo: string
103    }
104
105    class BackupExt extends BackupExtensionAbility {
106      //onBackupEx
107      async onBackupEx(backupInfo: string): Promise<string> {
108        console.log(`onBackupEx ok`);
109        let errorInfo: ErrorInfo = {
110          type: "ErrorInfo",
111          errorCode: 0,
112          errorInfo: "app diy error info"
113        }
114        return JSON.stringify(errorInfo);
115      }
116
117      // onRestoreEx
118      async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> {
119        console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
120        let errorInfo: ErrorInfo = {
121          type: "ErrorInfo",
122          errorCode: 0,
123          errorInfo: "app diy error info"
124        }
125        return JSON.stringify(errorInfo);
126      }
127    }
128    ```
129
130### 元数据资源配置文件说明
131
132| 属性名称             | 数据类型   | 必填 | 含义                                                         |
133| -------------------- | ---------- | ---- | ------------------------------------------------------------ |
134| allowToBackupRestore | 布尔值     | 是   | 是否允许备份恢复，默认为false。                              |
135| includes             | 字符串数组 | 否   | 应用沙箱中需要备份的文件和目录。<br>当模式串以非/开始时，表示一个相对于根路径的相对路径。<br>`includes`支持的路径清单列表如下述代码段内容所示，当配置`includes`时请确保配置路径范围包含在其中。<br>当`includes`已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用下述代码段内容作为默认值。 |
136| excludes             | 字符串数组 | 否   | `includes`中无需备份的例外项。格式同`includes`。<br>在配置`excludes`时，请确保其范围在`includes`的子集中。<br>当`excludes`已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用**空数组**作为默认值。 |
137| fullBackupOnly       | 布尔值     | 否   | 是否使用应用默认恢复目录，默认值为false。当值为true时，恢复数据时会通过临时路径进行缓存，临时路径可通过[backupDir](../reference/apis-core-file-kit/js-apis-file-backupextensioncontext.md)获取。当值为false或者不配置该字段时，恢复数据会以'/'为根目录解压数据。 |
138| restoreDeps          | 字符串     | 否   | **不推荐使用**，应用恢复时依赖其他应用数据，默认值为""，需要配置依赖应用名称。当前仅支持最多一个依赖项。配置的依赖仅在一次恢复任务上下文生效，如果一次恢复任务中没有检测到依赖应用，则忽略该依赖描述继续执行恢复任务。**依赖应用未恢复或者恢复失败都会导致本应用恢复失败**。 |
139| extraInfo            | json串     | 否   | 额外信息可通过该字段传递。                                   |
140
141> **说明：**
142>
143> 1、**有关fullBackupOnly字段的说明**
144>
145> - 当fullBackupOnly为false时，恢复数据会以 **/** 为根目录解压数据，同路径下的同名文件会被覆盖。
146> - 当fullBackupOnly为true时，恢复数据会以临时目录为根目录解压数据，开发者需要在OnRestore/OnRestoreEx内自行实现恢复数据的逻辑，进行最终的恢复。
147>
148> 开发者可根据自身的业务场景，选择对应的恢复数据方式。
149>
150> 示例：
151> 假设应用的数据备份路径为：**data/storage/el2/base/files/A/** 。那么在恢复时，如果配置了fullBackupOnly为false，数据会被直接解压到：**/data/storage/el2/base/files/A/**目录下，如果配置了fullBackupOnly为true，数据则会被解压到：**临时路径[backupDir](../reference/apis-core-file-kit/js-apis-file-backupextensioncontext.md) + /restore/data/storage/el2/base/files/A/** 目录下。
152
153**includes支持的路径清单列表如下：**
154
155```json
156{
157    "includes": [
158    "data/storage/el1/database/",
159    "data/storage/el1/base/files/",
160    "data/storage/el1/base/preferences/",
161    "data/storage/el1/base/haps/*/files/",
162    "data/storage/el1/base/haps/*/preferences/",
163    "data/storage/el2/database/",
164    "data/storage/el2/base/files/",
165    "data/storage/el2/base/preferences/",
166    "data/storage/el2/base/haps/*/files/",
167    "data/storage/el2/base/haps/*/preferences/",
168    "data/storage/el2/distributedfiles/",
169    "data/storage/el5/database/",
170    "data/storage/el5/base/files/",
171    "data/storage/el5/base/preferences/",
172    "data/storage/el5/base/haps/*/files/",
173    "data/storage/el5/base/haps/*/preferences/"
174    ]
175}
176```
177
178## 相关实例
179
180针对应用接入数据的备份与恢复，有以下相关实例可供参考：
181
182- [应用接入数据备份恢复（ArkTS）（Full SDK）（API10）](https://gitee.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/FileManagement/FileBackupExtension)
183