diff --git a/zh-cn/application-dev/file-management/Readme-CN.md b/zh-cn/application-dev/file-management/Readme-CN.md index ccf665fea3e8c62f374d221a021d0ddb076ee854..8f09386ab05ecda526746e59e139a056c1fcb14a 100644 --- a/zh-cn/application-dev/file-management/Readme-CN.md +++ b/zh-cn/application-dev/file-management/Readme-CN.md @@ -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) diff --git a/zh-cn/application-dev/file-management/app-file-backup-extension.md b/zh-cn/application-dev/file-management/app-file-backup-extension.md new file mode 100644 index 0000000000000000000000000000000000000000..c95985a0e15a42e767eab45ea488f1e3c691a930 --- /dev/null +++ b/zh-cn/application-dev/file-management/app-file-backup-extension.md @@ -0,0 +1,80 @@ +# 应用接入数据备份恢复 + +应用接入数据备份恢复需要通过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 | 字符串数组 | 否 | 应用沙箱中需要备份的文件和目录。
数组中的每一项均为模式串,可包含SHELL风格通配符(`*`,`?`,`[`)。
当模式串以非/开始时,表示一个相对于根路径的相对路径。
当`includes`已配置时,备份恢复框架会采用开发者配置的模式串,否则将会采用下述代码段内容作为默认值。 | +| excludes | 字符串数组 | 否 | `includes`中无需备份的例外项。格式同`includes`。
当`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/", + ] +} +``` diff --git a/zh-cn/application-dev/file-management/app-file-backup-overview.md b/zh-cn/application-dev/file-management/app-file-backup-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..9768041c3bd7e9240cabdafd71c40bc4b7857591 --- /dev/null +++ b/zh-cn/application-dev/file-management/app-file-backup-overview.md @@ -0,0 +1,15 @@ +# 应用数据备份恢复概述 + +用户在使用应用的过程中,会产生对应的应用数据,如配置信息、业务数据等。为了保证用户数据不会因为应用升级、迁移等操作而丢失,应用需要接入数据备份恢复。 + +在开发前,需要先了解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 diff --git a/zh-cn/application-dev/file-management/app-file-backup.md b/zh-cn/application-dev/file-management/app-file-backup.md new file mode 100644 index 0000000000000000000000000000000000000000..55ee7590b542b12d2d7011f3084d4742f505ecf1 --- /dev/null +++ b/zh-cn/application-dev/file-management/app-file-backup.md @@ -0,0 +1,334 @@ +# 应用触发数据备份/恢复(仅对系统应用开放) + +备份恢复是为设备上应用数据、公共数据和系统服务提供的完整的数据备份和恢复解决方案。系统应用开发者可以根据需求,按下述指导开发应用,以触发备份/恢复数据。 + +- [获取能力文件](#获取能力文件):获取当前系统用户内所有应用与备份恢复相关基础信息的能力文件。能力文件在应用备份/恢复数据时不可缺少。 + +- [应用备份数据](#应用备份数据):根据能力文件提供的应用信息,选择需要备份的应用数据并进行备份。 + +- [应用恢复数据](#应用恢复数据):根据能力文件提供的应用信息,选择需要恢复的应用数据并进行恢复。 + +- [应用恢复数据时安装应用](#应用恢复数据时安装应用):应用恢复数据的拓展功能,当用于恢复数据的应用未安装时,建议使用此功能,设备将先安装应用再恢复数据。 + +## 开发说明 + +备份恢复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