Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
未验证 提交 d97221b8 编写于 作者: O openharmony_ci 提交者： Gitee
浏览文件
操作

!17702 新增备份恢复开发者文档 

Merge pull request !17702 from 花轻似梦/master
上级 6190014b 0b03876e
隐藏空白更改
内联 并排
Showing with 433 addition and 0 deletion
zh-cn/application-dev/file-management/Readme-CN.md
浏览文件 @ d97221b8
......@@ -10,6 +10,10 @@
- [应用及文件系统空间统计](app-fs-space-statistics.md)
- [向应用沙箱推送文件](send-file-to-app-sandbox.md)
- [应用文件分享](share-app-file.md)
- 应用数据备份恢复
- [应用数据备份恢复概述](app-file-backup-overview.md)
- [应用接入数据备份恢复](app-file-backup-extension.md)
- [应用触发数据备份/恢复（仅对系统应用开放）](app-file-backup.md)
- 用户文件
- [用户文件概述](user-file-overview.md)
- 选择与保存用户文件（FilePicker）
......
zh-cn/application-dev/file-management/app-file-backup-extension.md 0 → 100644
浏览文件 @ d97221b8
# 应用接入数据备份恢复
应用接入数据备份恢复需要通过BackupExtensionAbility实现。
BackupExtensionAbility，是[Stage模型](../../application-dev/application-models/stage-model-development-overview.md)中扩展组件[ExtensionAbility](../application-models/extensionability-overview.md)的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复，备份哪些文件等。
## 约束与限制
- 当备份恢复时，所有待备份文件及目录的路径不得超过4095字节，否则将导致未定义行为。
- 当备份目录时，应用进程必须拥有读取该目录及其所有子目录的权限（DAC中的`r`），否则将导致备份失败。
- 当备份文件时，应用进程必须拥有搜索该文件所有祖父级目录的权限（DAC中的`x`），否则将导致备份失败。
## 开发步骤
1. 在应用配置文件`module.json5`中注册`extensionAbilities`相关配置
新增`"extensionAbilities"`字段，其中注册类型`"type"`设置为`"backup"`，元数据信息["metadata"](../../application-dev/reference/apis/js-apis-bundleManager-metadata.md)新增一个`"name"`为`"ohos. extension. backup"`的条目。
BackupExtensionAbility配置文件示例：
```json
{
"extensionAbilities": [
{
"description": "$string:ServiceExtAbility",
"icon": "$media:icon",
"name": "BackupExtensionAbility",
"type": "backup",
"visible": true,
"metadata": [
{
"name": "ohos.extension.backup",
"resource": "$profile:backup_config"
}
],
"srcEntrance": "",
}
]
}
```
2. 新增元数据资源配置文件
在元数据资源配置文件中，定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与`module.json5`中 `"metadata.resource"`名称保持一致，其保存位置在Profile文件夹下。
元数据资源配置文件示例：
```json
{
"allowToBackupRestore": true,
"includes": [
"/data/storage/el2/base/files/users/*/*.json"
],
"excludes": [
"/data/storage/el2/base/files/users/*/hidden.json"
],
}
```
### 元数据资源配置文件说明
| 属性名称 | 数据类型 | 必填 | 含义 |
| -------------------- | ---------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| allowToBackupRestore | 布尔值 | 是 | 是否允许备份恢复，默认为false |
| includes | 字符串数组 | 否 | 应用沙箱中需要备份的文件和目录。<br>数组中的每一项均为模式串，可包含SHELL风格通配符（`*`，`?`，`[`）。<br>当模式串以非/开始时，表示一个相对于根路径的相对路径。<br>当`includes`已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用下述代码段内容作为默认值。 |
| excludes | 字符串数组 | 否 | `includes`中无需备份的例外项。格式同`includes`。<br>当`excludes`已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用**空数组**作为默认值。 |
**includes默认值：**
```json
{
"includes": [
"data/storage/el2/database/",
"data/storage/el2/base/files/",
"data/storage/el2/base/preferences/",
"data/storage/el2/base/haps/*/database/",
"data/storage/el2/base/haps/*/base/files/",
"data/storage/el2/base/haps/*/base/preferences/",
]
}
```
zh-cn/application-dev/file-management/app-file-backup-overview.md 0 → 100644
浏览文件 @ d97221b8
# 应用数据备份恢复概述
用户在使用应用的过程中，会产生对应的应用数据，如配置信息、业务数据等。为了保证用户数据不会因为应用升级、迁移等操作而丢失，应用需要接入数据备份恢复。
在开发前，需要先了解ExtensionAbility组件，建议参考[ExtensionAbility组件概述](../application-models/extensionability-overview.md)。
BackupExtensionAbility是Stage模型中扩展组件ExtensionAbility的派生类，用于提供备份及恢复应用数据的能力。它是一种无界面的扩展组件，随着备份恢复任务的启动而运行，随着备份恢复任务的结束而退出。
不同应用所需实现的场景不同，分为：
- [应用接入数据备份恢复](app-file-backup-extension.md)：应用均可以接入数据备份恢复，在接入后，应用可通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复、备份哪些数据。
应用本身无法触发数据的备份和恢复，仅能进行备份恢复的配置。
- [应用触发数据备份恢复（仅对系统应用开放）](app-file-backup.md)：仅系统应用可以触发数据备份恢复，触发后备份恢复框架会确认各个应用是否接入了数据备份恢复。如果应用已接入，备份恢复框架将会根据应用的配置文件备份、恢复数据。
\ No newline at end of file
zh-cn/application-dev/file-management/app-file-backup.md 0 → 100644
浏览文件 @ d97221b8
# 应用触发数据备份/恢复（仅对系统应用开放）
备份恢复是为设备上应用数据、公共数据和系统服务提供的完整的数据备份和恢复解决方案。系统应用开发者可以根据需求，按下述指导开发应用，以触发备份/恢复数据。
- [获取能力文件](#获取能力文件)：获取当前系统用户内所有应用与备份恢复相关基础信息的能力文件。能力文件在应用备份/恢复数据时不可缺少。
- [应用备份数据](#应用备份数据)：根据能力文件提供的应用信息，选择需要备份的应用数据并进行备份。
- [应用恢复数据](#应用恢复数据)：根据能力文件提供的应用信息，选择需要恢复的应用数据并进行恢复。
- [应用恢复数据时安装应用](#应用恢复数据时安装应用)：应用恢复数据的拓展功能，当用于恢复数据的应用未安装时，建议使用此功能，设备将先安装应用再恢复数据。
## 开发说明
备份恢复API的使用指导请参见[API参考](../reference/apis/js-apis-file-backup.md)。
在使用备份恢复接口之前，需要：
1. [申请相关权限](../security/accesstoken-guidelines.md)：`ohos.permission.BACKUP`
2. 导入依赖模块：`@ohos.file.backup`
```js
import backup from '@ohos.file.backup';
```
## 获取能力文件
获取当前系统用户内所有应用与备份恢复相关基础信息的能力文件。能力文件在应用备份恢复数据时是不可缺少的，开发者可以根据需要获取能力文件。
该文件包含设备类型、设备版本、应用的基础性信息，如应用名称、应用数据大小、应用版本信息、是否支持备份恢复、是否在恢复时安装应用。
调用`backup.getLocalCapabilities()`获取能力文件。
```js
import fs from '@ohos.file.fs';
try {
let fileData = await backup.getLocalCapabilities();
console.info('getLocalCapabilities success');
let fpath = await globalThis.context.filesDir + '/localCapabilities.json';
fs.copyFileSync(fileData.fd, fpath);
fs.closeSync(fileData.fd);
} catch (err) {
console.error('getLocalCapabilities failed with err: ' + err);
}
```
**返回的能力文件内容示例：**
| 属性名称 | 数据类型 | 必填 | 含义 |
| -------------- | -------- | ---- | ---------------------- |
| bundleInfos | 数组 | 是 | 应用信息列表 |
| allToBackup | 布尔值 | 是 | 是否允许备份恢复 |
| extensionName | 字符串 | 是 | 应用的扩展名 |
| name | 字符串 | 是 | 应用的包名 |
| needToInstall | 布尔值 | 是 | 应用恢复时是否需要安装 |
| spaceOccupied | 数值 | 是 | 应用数据占用的空间大小 |
| versionCode | 数值 | 是 | 应用的版本号 |
| versionName | 字符串 | 是 | 应用的版本名称 |
| deviceType | 字符串 | 是 | 设备类型 |
| systemFullName | 字符串 | 是 | 设备版本 |
```json
{
"bundleInfos" :[{
"allToBackup" : true,
"extensionName" : "BackupExtensionAbility",
"name" : "com.example.hiworld",
"needToInstall" : false,
"spaceOccupied" : 0,
"versionCode" : 1000000,
"versionName" : "1.0.0"
}],
"deviceType" : "default",
"systemFullName" : "OpenHarmony-4.0.0.0"
}
```
## 应用备份数据
开发者可以根据能力文件提供的应用信息，选择需要备份的应用数据。
备份过程中，备份恢复服务会将应用的数据打包成文件，打包后的文件会以打开的文件句柄形式，通过创建实例时所注册的回调[onFileReady](../reference/apis/js-apis-file-backup.md#onfileready)接口返回。
开发者可以根据需要将文件内容保存到本地。
**示例**
```ts
import fs from '@ohos.file.fs';
// 创建SessionBackup类的实例用于备份数据
let session = new backup.SessionBackup({
onFileReady: async (err, file) => {
if (err) {
console.info('onFileReady err: ' + err);
}
try {
let bundlePath = await globalThis.context.filesDir + '/' + file.bundleName;
if (!fs.accessSync(bundlePath)) {
fs.mkdirSync(bundlePath);
}
fs.copyFileSync(file.fd, bundlePath + `/${file.uri}`);
fs.closeSync(file.fd);
console.info('onFileReady success');
} catch (e) {
console.error('onFileReady failed with err: ' + e);
}
},
onBundleBegin: (err, bundleName) => {
if (err) {
console.info('onBundleBegin err: ' + err);
} else {
console.info('onBundleBegin bundleName: ' + bundleName);
}
},
onBundleEnd: (err, bundleName) => {
if (err) {
console.info('onBundleEnd err: ' + err);
} else {
console.info('onBundleEnd bundleName: ' + bundleName);
}
},
onAllBundlesEnd: (err) => {
if (err) {
console.info('onAllBundlesEnd err: ' + err);
} else {
console.info('onAllBundlesEnd');
}
},
onBackupServiceDied: () => {
console.info('onBackupServiceDied');
},
});
// 此处可根据backup.getLocalCapabilities()提供的能力文件，选择需要备份的应用
// 也可直接根据应用包名称进行备份
const backupApps = [
"com.example.hiworld",
]
await session.appendBundles(backupApps);
console.info('appendBundles success');
```
## 应用恢复数据
开发者可以根据能力文件提供的应用信息，选择需要恢复的应用数据。
恢复过程中，备份恢复服务会根据开发者调用[getFileHandle](../reference/apis/js-apis-file-backup.md#getfilehandle)的请求内容，将应用待恢复数据的文件句柄，通过创建实例时注册的回调[onFileReady](../reference/apis/js-apis-file-backup.md#onfileready)接口返回。可以根据返回的[uri](../reference/apis/js-apis-file-backup.md#filemeta)将应用对应的待恢复数据写入到文件句柄中。写入完成后开发者调用[publishFile](../reference/apis/js-apis-file-backup.md#publishfile)通知服务写入完成。
待应用所有恢复数据准备就绪后，服务开始恢复应用数据。
**示例**
```ts
import fs from '@ohos.file.fs';
// 创建SessionRestore类的实例用于恢复数据
let session = new backup.SessionRestore({
onFileReady: async (err, file) => {
if (err) {
console.info('onFileReady err: ' + err);
}
try {
let bundlePath = await globalThis.context.filesDir + '/' + file.bundleName + '/'+ file.uri;
if (!fs.accessSync(bundlePath)) {
console.info('onFileReady bundlePath err : ' + bundlePath);
}
fs.copyFileSync(bundlePath, file.fd);
fs.closeSync(file.fd);
// 恢复数据传输完成后，会通知服务端文件准备就绪
await session.publishFile({
bundleName: file.bundleName,
uri: file.uri,
});
console.info('onFileReady success');
} catch (e) {
console.error('onFileReady failed with err: ' + e);
}
},
onBundleBegin: (err, bundleName) => {
if (err) {
console.info('onBundleBegin err: ' + err);
} else {
console.info('onBundleBegin bundleName: ' + bundleName);
}
},
onBundleEnd: (err, bundleName) => {
if (err) {
console.info('onBundleEnd err: ' + err);
} else {
console.info('onBundleEnd bundleName: ' + bundleName);
}
},
onAllBundlesEnd: (err) => {
if (err) {
console.info('onAllBundlesEnd err: ' + err);
} else {
console.info('onAllBundlesEnd');
}
},
onBackupServiceDied: () => {
console.info('onBackupServiceDied');
},
});
const backupApps = [
"com.example.hiworld",
]
// 能力文件的获取方式可以根据开发者实际场景进行调整。此处仅为请求示例
// 开发者也可以根据能力文件内容的结构示例，自行构造能力文件内容
let fileData = await backup.getLocalCapabilities();
await session.appendBundles(fileData.fd, backupApps);
console.info('appendBundles success');
// 添加需要恢复的应用成功后，请根据需要恢复的应用名称，调用getFileHandle接口获取待恢复应用数文件的文件句柄
// 应用待恢复数据文件数请依据实际备份文件个数为准，此处仅为请求示例
await session.getFileHandle({
bundleName: restoreApps[0],
uri: "manage.json"
});
await session.getFileHandle({
bundleName: restoreApps[0],
uri: "1.tar"
});
console.info('getFileHandle success');
```
## 应用恢复数据时安装应用
开发者在恢复数据时可以选择先安装应用后再进行恢复应用数据。与[应用恢复数据](#应用恢复数据)相比需要修改[能力文件](#获取能力文件)中`bundleInfos`数组内的`needToInstall`字段修改为`true`。
> **说明：**
> - [应用备份数据](#应用备份数据)不支持备份应用安装包，因此开发者需要自行准备应用安装包。
> - 开发者在调用[getFileHandle](../reference/apis/js-apis-file-backup.md#getfilehandle)时，传入固定的`FileMeta.uri`=`"/data/storage/el2/restore/bundle.hap"`，用于获取应用安装包的文件句柄。与应用恢复数据时一致，应用安装包的文件句柄，通过创建实例时注册的回调onFileReady接口返回给开发者，返回的`File.uri`=`"/data/storage/el2/restore/bundle.hap"`。
**示例**
```ts
import fs from '@ohos.file.fs';
// 创建SessionRestore类的实例用于恢复数据
let session = new backup.SessionRestore({
onFileReady: async (err, file) => {
if (err) {
console.info('onFileReady err: ' + err);
}
try {
let bundlePath;
if( file.uri == "/data/storage/el2/restore/bundle.hap" )
{
// 此处开发者请根据实际场景安装包的存放位置进行调整
} else {
bundlePath = await globalThis.context.filesDir + '/' + file.bundleName + '/'+ file.uri;
}
if (!fs.accessSync(bundlePath)) {
console.info('onFileReady bundlePath err : ' + bundlePath);
}
fs.copyFileSync(bundlePath, file.fd);
fs.closeSync(file.fd);
// 恢复数据传输完成后，会通知服务端文件准备就绪
await session.publishFile({
bundleName: file.bundleName,
uri: file.uri,
});
console.info('onFileReady success');
} catch (e) {
console.error('onFileReady failed with err: ' + e);
}
},
onBundleBegin: (err, bundleName) => {
if (err) {
console.info('onBundleBegin err: ' + err);
} else {
console.info('onBundleBegin bundleName: ' + bundleName);
}
},
onBundleEnd: (err, bundleName) => {
if (err) {
console.info('onBundleEnd err: ' + err);
} else {
console.info('onBundleEnd bundleName: ' + bundleName);
}
},
onAllBundlesEnd: (err) => {
if (err) {
console.info('onAllBundlesEnd err: ' + err);
} else {
console.info('onAllBundlesEnd');
}
},
onBackupServiceDied: () => {
console.info('onBackupServiceDied');
},
});
const backupApps = [
"com.example.hiworld",
]
let fpath = await globalThis.context.filesDir + '/localCapabilities.json';
let file = fs.openSync(fpath, fileIO.OpenMode.CREATE | fileIO.OpenMode.READ_WRITE);
let content = "{\"bundleInfos\" :[{\"allToBackup\" : false,\"extensionName\" : \"\"," +
"\"name\" : \"cn.openharmony.inputmethodchoosedialog\",\"needToInstall\" : true,\"spaceOccupied\" : 0," +
"\"versionCode\" : 1000000,\"versionName\" : \"1.0.0\"}],\"deviceType\" : \"default\",\"systemFullName\" : \"OpenHarmony-4.0.6.2(Canary1)\"}";
fs.writeSync(file.fd, content);
fs.fsyncSync(file.fd);
await session.appendBundles(file.fd, backupApps);
console.info('appendBundles success');
// 开发者需要请求安装应用的文件句柄
await session.getFileHandle({
bundleName: restoreApps[0],
uri: "/data/storage/el2/restore/bundle.hap"
});
await session.getFileHandle({
bundleName: restoreApps[0],
uri: "manage.json"
});
await session.getFileHandle({
bundleName: restoreApps[0],
uri: "1.tar"
});
console.info('getFileHandle success');
```
**恢复数据时安装应用所需的能力文件内容示例：**
```json
{
"bundleInfos" :[{
"allToBackup" : true,
"extensionName" : "BackupExtensionAbility",
"name" : "com.example.hiworld",
"needToInstall" : true,
"spaceOccupied" : 0,
"versionCode" : 1000000,
"versionName" : "1.0.0"
}],
"deviceType" : "default",
"systemFullName" : "OpenHarmony-4.0.0.0"
}
```
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或