HarmonyOS NEXT - 应用数据备份恢复

应用数据备份恢复概述

 

用户在使用应用的过程中，会产生对应的应用数据，如配置信息、业务数据等。为了保证用户数据不会因为应用升级、迁移等操作而丢失，应用需要接入数据备份恢复。

在开发前，需要先了解ExtensionAbility组件，建议参考ExtensionAbility组件概述。

BackupExtensionAbility是Stage模型中扩展组件ExtensionAbility的派生类，用于提供备份及恢复应用数据的能力。它是一种无界面的扩展组件，随着备份恢复任务的启动而运行，随着备份恢复任务的结束而退出。

不同应用所需实现的场景不同，分为：

• 应用接入数据备份恢复：应用均可以接入数据备份恢复，在接入后，应用可通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复、备份哪些数据。

  应用本身无法触发数据的备份和恢复，仅能进行备份恢复的配置。

应用触发数据备份恢复（仅对系统应用开放）

 

应用接入数据备份恢复

 

应用接入数据备份恢复需要通过BackupExtensionAbility实现。

BackupExtensionAbility，是Stage模型中扩展组件ExtensionAbility的派生类。开发者可以通过修改配置文件定制备份恢复框架的行为，包括是否允许备份恢复，备份哪些文件等。

接口说明

备份恢复扩展能力API的接口使用指导请参见BackupExtensionAbility API参考和BackupExtensionContext API参考。

约束与限制

• 当备份恢复时，所有待备份文件及目录的路径不得超过4095字节，否则将导致未定义行为。
• 当备份目录时，应用进程必须拥有读取该目录及其所有子目录的权限（DAC中的r），否则将导致备份失败。
• 当备份文件时，应用进程必须拥有搜索该文件所有祖父级目录的权限（DAC中的x），否则将导致备份失败。
• 当启动模式标签"launchType"为"singleton"时不支持备份恢复。

开发步骤

开发者可根据自身的业务场景，选择对应的恢复数据方式。以临时路径 /data/storage/el2/base/.backup/restore/ 为例：

假设应用的数据备份路径为：data/storage/el2/base/files/A/ 。那么在恢复时，如果配置了fullBackupOnly为false，数据会被解压到：/data/storage/el2/base/files/A/ 目录下，如果配置了fullBackupOnly为true，数据会被解压到：/data/storage/el2/base/.backup/restore/data/storage/el2/base/files/A/ 目录下。

includes默认值：

 

1. 在应用配置文件module.json5中注册extensionAbilities相关配置

   新增"extensionAbilities"字段，其中注册类型"type"设置为"backup"，元数据信息"metadata"新增一个"name"为"ohos. extension. backup"的条目。

   BackupExtensionAbility配置文件示例：
   
    

   {
       "extensionAbilities": [
           {
               "description": "$string:ServiceExtAbility",
               "icon": "$media:icon",
               "name": "BackupExtensionAbility",
               "type": "backup",
               "exported": false,
               "metadata": [
                   {
                       "name": "ohos.extension.backup",
                       "resource": "$profile:backup_config"
                   }
               ],
               // 在BackupExtension.ets文件里自定义继承BackupExtensionAbility，重写其中的onBackup/onBackupEx和               // onRestore/onRestoreEx方法，推荐使用onBackupEx/onRestoreEx。
               // 如果没有特殊要求可以空实现，则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。
               "srcEntry": "./ets/BackupExtension/BackupExtension.ets", 
           }      
       ]
   }
   

   新增元数据资源配置文件

   在元数据资源配置文件中，定义备份恢复时需要传输的文件。元数据资源配置文件名称需要与module.json5中"metadata.resource"例如"backup_config.json"名称保持一致，其保存位置在工程的resources/base/profile文件夹下。

   元数据资源配置文件示例：
   
    

   {
       "allowToBackupRestore": true,
       "includes": [
           "/data/storage/el2/base/files/users/"
       ],
       "excludes": [
           "/data/storage/el2/base/files/users/hidden/"
       ],
       "fullBackupOnly": false,
       "restoreDeps": "",
   }
   

   开发者可以在BackupExtension.ets文件中自定义类继承的BackupExtensionAbility，通过重写其onBackup/onBackupEx和onRestore/onRestoreEx方法，使其达到在备份预加工应用数据或者在恢复阶段加工待恢复文件。

   如果没有特殊要求可以空实现，则备份恢复服务会按照统一的备份恢复数据规则进行备份恢复。

   下面的示例展示了一个空实现的BackupExtension.ets文件。
   
    

   //onBackup && onRestore
   import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
   import {hilog} from '@kit.PerformanceAnalysisKit';
   
   const TAG = `FileBackupExtensionAbility`;
   export default class BackupExtension extends  BackupExtensionAbility {
     //onBackup
     async onBackup ()   {
       hilog.info(0x0000, TAG, `onBackup ok`);
     }
     //onRestore
     async onRestore (bundleVersion : BundleVersion) {
       hilog.info(0x0000, TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
       hilog.info(0x0000, TAG, `onRestore end`);
     }
   }
   

   //onBackupEx && onRestoreEx
   import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
   
   interface ErrorInfo {
     type: string,
     errorCode: number,
     errorInfo: string
   }
   
   class BackupExt extends BackupExtensionAbility {
     //onBackupEx
     async onBackupEx(backupInfo: string): Promise<string> {
       console.log(`onBackupEx ok`);
       let errorInfo: ErrorInfo = {
         type: "ErrorInfo",
         errorCode: 0,
         errorInfo: "app diy error info"       
       }
       return JSON.stringify(errorInfo);
     }
   
     // onRestoreEx
     async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> {
       console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
       let errorInfo: ErrorInfo = {
         type: "ErrorInfo",
         errorCode: 0,
         errorInfo: "app diy error info"
       }
       return JSON.stringify(errorInfo);
     }
   }
   

   元数据资源配置文件说明

   属性名称	数据类型	必填	含义
   allowToBackupRestore	布尔值	是	是否允许备份恢复，默认为false。
   includes	字符串数组	否	应用沙箱中需要备份的文件和目录。 当模式串以非/开始时，表示一个相对于根路径的相对路径。 当includes已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用下述代码段内容作为默认值。
   excludes	字符串数组	否	includes中无需备份的例外项。格式同includes。 当excludes已配置时，备份恢复框架会采用开发者配置的模式串，否则将会采用空数组作为默认值。
   fullBackupOnly	布尔值	否	是否使用应用默认恢复目录，默认值为false。当值为true时，恢复数据时会通过临时路径进行缓存，临时路径可通过backupDir获取。当值为false或者不配置该字段时，恢复数据会以'/'为根目录解压数据。
   restoreDeps	字符串	否	不推荐使用，应用恢复时依赖其他应用数据，默认值为""，需要配置依赖应用名称。当前仅支持最多一个依赖项。配置的依赖仅在一次恢复任务上下文生效，如果一次恢复任务中没有检测到依赖应用，则忽略该依赖描述继续执行恢复任务。依赖应用未恢复或者恢复失败都会导致本应用恢复失败。
   extraInfo	json串	否	额外信息可通过该字段传递。

   说明

   1、有关fullBackupOnly字段的说明

2. 当fullBackupOnly为false时，恢复数据会以 / 为根目录解压数据，同路径下的同名文件会被覆盖。
3. 当fullBackupOnly为true时，恢复数据会以临时目录为根目录解压数据，开发者需要在OnRestore/OnRestoreEx内自行实现恢复数据的逻辑，进行最终的恢复。
    

   开发者可根据自身的业务场景，选择对应的恢复数据方式。以临时路径 /data/storage/el2/base/.backup/restore/ 为例：

   假设应用的数据备份路径为：data/storage/el2/base/files/A/ 。那么在恢复时，如果配置了fullBackupOnly为false，数据会被解压到：/data/storage/el2/base/files/A/ 目录下，如果配置了fullBackupOnly为true，数据会被解压到：/data/storage/el2/base/.backup/restore/data/storage/el2/base/files/A/ 目录下。

includes默认值：

 

{
    "includes": [
    "data/storage/el1/database/",
    "data/storage/el1/base/files/",
    "data/storage/el1/base/preferences/",
    "data/storage/el1/base/haps/<module-name>/files/",
    "data/storage/el1/base/haps/<module-name>/preferences/",
    "data/storage/el2/database/",
    "data/storage/el2/base/files/",
    "data/storage/el2/base/preferences/",
    "data/storage/el2/base/haps/<module-name>/files/",
    "data/storage/el2/base/haps/<module-name>/preferences/",
    "data/storage/el2/distributedfiles/"
    ]
}