README_zh.md
1# 应用接入数据备份恢复
2
3### 介绍
4
5应用接入数据备份恢复需要通过配置BackupExtensionAbility实现。
6
7BackupExtensionAbility，是[Stage模型](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/stage-model-development-overview.md)中扩展组件[ExtensionAbility](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/application-models/extensionability-overview.md)的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复，备份哪些文件等。
8
9本sample主要给备份流程提供应用，用于生成数据和显示数据。
10
11### 效果预览
12
13|初始界面|生成文件界面|恢复备份后显示|
14|--------------------------------|--------------------------------|--------------------------------|
15||||
16
17使用说明：
18
191. 点击按钮“生成文件数据”，应用会随机生成2个到10个txt文件，大小在1Byte到1024Byte之间，用于校验备份和恢复的数据为同一数据。
202. 本应用仅适用于生成和显示数据，具体的备份和恢复的操作目前需要使用hdc shell命令操作。
213. 具体操作方面，进入应用点击按钮生成文件数据后，进入hdc shell，使用backup_tool backup --isLocal=true --bundle com.samples.backupextension --pathCapFile /data/backup/tmp命令进行备份。然后可以把应用删掉，重新安装应用后进入hdc shell，使用backup_tool restore --bundle com.samples.backupextension --pathCapFile /data/backup/tmp，提示成功后，重新打开应用可以看到备份的文件显示在列表里。
22
23### 工程目录
24```
25entry/src/main/ets/
26|---Application
27|---Common
28| |---Logger.ts // 日志工具
29|---MainAbility
30| |---EntryAbility.ts // Ability类
31|---fileFs
32| |---CreateFile.ts // 创建文件
33|---pages
34| |---Index.ets // 首页
35```
36### 具体实现
37
381. 在应用配置文件`module.json5`中注册`extensionAbilities`相关配置
39
40新增`"extensionAbilities"`字段，其中注册类型`"type"`设置为`"backup"`，元数据信息["metadata"](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundleManager-metadata.md)新增一个`"name"`为`"ohos.extension.backup"`的条目。
41
42BackupExtensionAbility配置文件示例：
43
44```
45{
46 "extensionAbilities": [
47 {
48 "description": "$string:ServiceExtAbility",
49 "icon": "$media:icon",
50 "name": "BackupExtensionAbility",
51 "type": "backup",
52 "visible": true,
53 "metadata": [
54 {
55 "name": "ohos.extension.backup",
56 "resource": "$profile:backup_config"
57 }
58 ],
59 "srcEntrance": "",
60 }
61 ]
62}
63```
64
652. 新增元数据资源配置文件
66
67在元数据资源配置文件中，定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与`module.json5`中 `"metadata.resource"`名称保持一致，其保存位置在Profile文件夹下。
68
69元数据资源配置文件示例：
70
71```
72{
73 "allowToBackupRestore": true,
74 "includes": [
75 "data/storage/el2/database/",
76 "data/storage/el2/base/files/",
77 "data/storage/el2/base/preferences/",
78 "data/storage/el2/base/haps/*/database/",
79 "data/storage/el2/base/haps/*/base/files/",
80 "data/storage/el2/base/haps/*/files/",
81 "data/storage/el2/base/haps/entry/files/TextDir/",
82 "data/storage/el2/base/haps/*/base/preferences/",
83 "/data/storage/el2/base/files/users/*/*.json"
84 ],
85 "excludes": [
86 "/data/storage/el2/base/files/users/*/hidden.json"
87 ]
88}
89```
90
91其中includes里面的文件夹是用户需要备份数据的路径，excludes为用户不想备份数据的路径。
92
933. 使用应用生成数据：
94
95点击界面的“生成文件数据”按钮，会使用以下代码生成文件，并在onPageShow中获取文件名列表和文件大小列表，然后显示在界面上。
96
97```
98async createTestFiles(): Promise<void> {
99 try {
100 let num = Math.floor(Math.random() * FILE_NUM_MAX) + FILE_NUM_MIN;
101 if (!fs.accessSync(this.baseDir)) {
102 fs.mkdirSync(this.baseDir);
103 }
104 let dpath = this.baseDir;
105 Logger.info(TAG, 'sanBoxFileDir = ' + dpath);
106 Logger.info(TAG, 'num is = ' + num);
107 for (let i = 0; i < num; i++) {
108 let myFile = dpath + `/TestFile_${i}.txt`;
109 Logger.info(TAG, 'readyFile myFile = ' + myFile);
110 let file = fs.openSync(myFile, fs.OpenMode.CREATE | fs.OpenMode.READ_WRITE);
111 fs.writeSync(file.fd, new ArrayBuffer(ONE_KILOBYTE * Math.random()));
112 fs.closeSync(file);
113 }
114 } catch (e) {
115 Logger.error(TAG, 'Failed to prepare media files, error:' + e.message + e.code);
116 }
117 }
118```
119
1204. 备份与恢复操作：
121
122由于目前备份与恢复尚未提供具体的应用接口，所以备份与功能仅提供命令行方式进行检验：
123
124```
125应用备份
126backup_tool backup --isLocal=true --bundle com.sample.backupextension --pathCapFile /data/backup/tmp
127备份成功提示：
128BundleStarted errCode = 0, BundleName = com.example.backupextension
129FileReady owner = com.example.backupextension, fileName = manage.json, sn = 0, fd = 9
130FileReady owner = com.example.backupextension, fileName = 1.tar, sn = 0, fd = 9
131BundleFinished errCode = 0, BundleName = com.example.backupextension
132backup successful
133
134应用恢复
135backup_tool restore --bundle com.sample.backupextension --pathCapFile /data/backup/tmp
136恢复成功提示：
137BundleStarted errCode = 0, BundleName = com.example.backupextension
138FileReady owner = com.example.backupextension, fileName = 1.tar, sn = 0, fd = 8
139FileReady owner = com.example.backupextension, fileName = manage.json, sn = 0, fd = 8
140BundleFinished errCode = 0, BundleName = com.example.backupextension
141Restore successful
142```
143
144backup详细说明可以使用backup -help查看。
145
146
147
148### 相关权限
149
150[ohos.permission.GET_BUNDLE_INFO_PRIVILEGED](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md#ohospermissionget_bundle_info_privileged)
151
152
153
154### 依赖
155
156不涉及。
157
158### 约束与限制
159
1601.本示例仅支持标准系统上运行，支持设备：RK3568。
161
1622.本示例为Stage模型，支持API10版本SDK，SDK版本号(API Version 10 Release),镜像版本号(4.0 Release)
163
1643.本示例需要使用DevEco Studio 版本号(4.0 Release)及以上版本才可编译运行。
165
1664.本示例所配置的权限ohos.permission.GET_BUNDLE_INFO_PRIVILEGED为system_basic级别(相关权限级别可通过[权限定义列表](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/AccessToken/permissions-for-system-apps.md) 查看)，需要手动配置对应级别的权限签名(具体操作可查看[自动化签名方案](https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/security/hapsigntool-overview.md)) 。
167
168### 下载
169
170如需单独下载本工程，执行如下命令：
171```
172git init
173git config core.sparsecheckout true
174echo code/BasicFeature/FileManagement/FileBackupExtension > .git/info/sparse-checkout
175git remote add origin https://gitee.com/openharmony/applications_app_samples.git
176git pull origin master
177
178```
179
