HarmonyOS NEXT - 设备升级应用数据迁移适配指导

应用数据迁移功能介绍

 

使用场景

终端设备从HarmonyOS 3.1 Release API 9及之前版本(简称HarmonyOS)升级到HarmonyOS NEXT Developer Preview1及之后版本(简称HarmonyOS NEXT)时,原HarmonyOS中运行的APK应用,升级后需要切换为HarmonyOS NEXT中的HarmonyOS原生应用(简称HarmonyOS应用)。APK应用的部分数据需要转换并迁移到指定位置后,才能被HarmonyOS应用访问。HarmonyOS NEXT提供了“数据迁移框架”和“备份恢复框架”,为开发者提供应用数据的迁移和转换能力。开发者完成适配,APK应用切换为HarmonyOS应用后,可继承原APK应用中适配HarmonyOS应用的数据。

如下图所示,应用需要的数据,包含云端服务器中的数据,本地应用沙箱中的数据和本地公共媒体库中的数据。为了应用的数据可以继承,开发者需要保证云端数据定义兼容APK应用和HarmonyOS应用,确保系统升级后同一账号下的数据可识别。

数据迁移机制

应用沙箱数据迁移机制

终端设备从HarmonyOS升级到HarmonyOS NEXT后,APK应用沙箱数据被搬迁到中间目录。针对应用沙箱数据,HarmonyOS NEXT提供“数据迁移框架”统一调度应用数据迁移任务。

应用数据迁移任务需要执行的步骤包括:应用安装,数据迁移和数据恢复。

  1. 应用安装步骤:
    1. “数据迁移框架”向华为应用市场发送HarmonyOS应用下载和安装请求。
    2. 华为应用市场下载并安装HarmonyOS应用。
  2. 数据迁移步骤:

    在HarmonyOS应用安装完成之后,“数据迁移框架”将应用沙箱数据从中间目录搬迁到备份恢复目录。

  3. 数据恢复步骤:
    1. 在应用数据搬迁到备份恢复目录后,“数据迁移框架”向“备份恢复框架”发送应用数据恢复请求。
    2. “备份恢复框架”拉起应用的“BackupExtensionAbility”独立进程,启动应用数据恢复。
    3. 应用通过“BackupExtensionAbility”从备份恢复目录加载APK应用的数据,处理后保存到HarmonyOS应用沙箱中,完成应用数据恢复。
    4. “备份恢复框架”在应用数据恢复完成后,清空备份恢复目录。

后续HarmonyOS应用通过访问HarmonyOS应用沙箱获取应用的数据。

公共媒体库中数据迁移机制

公共媒体库中的数据,在终端设备从HarmonyOS升级到HarmonyOS NEXT后,会整体搬迁直接继承。应用可以使用HarmonyOS NEXT提供的API,访问公共媒体库中的数据。媒体库的使用指导可以参考:媒体文件管理服务

适配流程

 

适配流程包括:适配准备、应用适配、开发者自验证、应用上架和端到端验证。

图1 适配流程图

1. 适配准备阶段

在适配准备阶段,开发者需要分析清楚HarmonyOS中APK应用和HarmonyOS NEXT中HarmonyOS应用的数据范围和差异。

在开发之前,需要通过OTA升级的形式,将终端设备升级到HarmonyOS NEXT Developer Preview1及之后版本。

2.1 应用适配

在适配准备工作完成后,进入应用适配阶段。开发者需要在HarmonyOS应用的代码中,实现“BackupExtensionAbility”,使应用接入到“备份恢复框架”中,完成应用数据的转换和迁移。在“BackupExtensionAbility”中需要进行适配,从备份恢复目录下,加载APK应用数据,将需要迁移的数据处理后,保存到HarmonyOS应用沙箱中。

当前指导(应用数据迁移适配指导)将指导开发者在设备升级场景下接入“备份恢复框架”。更多“备份恢复框架”的资料可以参考:应用接入数据备份恢复

注意

应用的“BackupExtensionAbility”执行完后,“备份恢复框架”会清空备份恢复目录,开发者请在应用的“BackupExtensionAbility”执行结束前,完成所有所需数据的转换和迁移。

后续HarmonyOS应用通过访问HarmonyOS应用沙箱获取应用的数据。

备份恢复目录如下表中所示:

备份恢复目录

/data/storage/el1/base/.backup/restore/{APK包名}/de/

/data/storage/el2/base/.backup/restore/{APK包名}/ce/

/data/storage/el2/base/.backup/restore/{APK包名}/A/data/

/data/storage/el2/base/.backup/restore/{APK包名}/A/obb/

HarmonyOS应用沙箱目录请参考应用沙箱目录

2.2 开发者自验证

HarmonyOS NEXT Developer Beta1及之后版本,厂商合作伙伴可通过IssueReporter平台提交工单,向华为方技术支持人员申请“迁移调试”工具,模拟进行数据迁移验证。公共开发者请通过“华为开发者联盟官网”->“支持”,在线提单方式获取。

HarmonyOS NEXT Developer Beta1之前版本,开发者可以通过系统内置“迁移调试”工具,模拟进行数据迁移验证。

3. 应用上架

HarmonyOS应用适配成功后,在进行端到端验证之前,需要将HarmonyOS应用上架到华为应用市场。HarmonyOS应用上架指导请参考:发布HarmonyOS应用指导

4. 端到端验证

在HarmonyOS应用上架到华为应用市场之后,华为方技术支撑人员会为开发者推送回退版本。如果终端设备为HarmonyOS NEXT,开发者需要将终端设备回退到HarmonyOS,在HarmonyOS中使用APK应用生成数据。应用数据准备完成后,请通过OTA升级形式,将终端设备升级到华为方提供的HarmonyOS NEXT。验证HarmonyOS NEXT中的HarmonyOS应用是否成功继承原APK应用的数据。

 

应用数据迁移适配指导

环境准备

 

环境要求

开发者需要通过OTA升级的形式,将终端设备升级到HarmonyOS NEXT Developer Beta1及之后版本。

工具要求

工具

版本

说明

“迁移调试”工具

205.0.0.115及之后版本

模拟验证数据迁移

DevEco Studio

DevEco Studio NEXT Developer Beta3及之后版本

请参考:DevEco Studio使用指南

Compatible SDK

5.0.0(12)

请参考:版本说明

创建新工程
 

本章节从创建新工程开始,指导开发者接入“备份恢复框架”,已经创建工程的开发者可以跳过本节。

  1. 打开DevCco Studio编译器,在菜单栏点击File > New > Create Project,创建新工程。

  2. 在创建工程界面选择创建Empty Ability工程,单击Next按钮进入下一步。

  3. 在Configure Your Project界面,根据开发者的需求,创建自己的工程,Compatible SDK栏请选择:5.0.0(12)。选择完毕之后,点击Finish按钮完成工程创建。

  4. 工程创建成功之后进入如下界面。


 BackupExtensionAbility的实现

 

开发者可以在BackupExtension.ts文件中自定义类继承BackupExtensionAbility,通过重写其中的onBackup和onRestore方法,自定义应用数据的转换和迁移。终端设备从HarmonyOS升级到HarmonyOS NEXT数据迁移场景中,onRestore回调接口中的参数bundleVersion.name前缀为“0.0.0.0”。

注意

onRestore 接口是同步接口,其内部所有的异步操作请进行同步等待。

以下步骤以空工程为例,介绍如何实现BackupExtensionAbility:

  1. entry/src/main/ets/目录下,点击 New > Directory 创建backupExtension目录。

  2. 点击entry/src/main/ets/backupExtension/目录,点击 New > File 创建BackupExtension.ets文件。

  3. 参考示例代码实现BackupExtensionAbility,应用的数据转换和迁移逻辑,请在指定位置填充实现。

    import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
    
    const TAG = `BackupExtensionAbility`;
    
    /**
     * serviceExt进程入口
     */
    export default class BackupExtension extends  BackupExtensionAbility {
      onBackup () {
        console.log(TAG,`onBackup ok`);
      }
    
      /**
       * 数据恢复处理接口。接口是同步接口,其内部所有的异步操作请进行同步等待。
       *
       * @param bundleVersion 版本信息
       */
      async onRestore (bundleVersion : BundleVersion): Promise<void> {
        console.log(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
        if (bundleVersion.name.startsWith("0.0.0.0")){
          // 在此处实现终端设备从HarmonyOS 4.0升级到HarmonyOS NEXT后,应用数据的转换和迁移
          // 涉及异步操作请进行同步等待
          console.log(TAG, `HarmonyOS to HarmonyOS NEXT scenario`);
        } else {
          // 在此处实现从HarmonyOS NEXT设备迁移到HarmonyOS NEXT设备后,应用数据的处理。无特殊要求,可以空实现
          // 涉及异步操作请进行同步等待
          console.log(TAG, `Other scenario`);
        }
      }
    }
    
     
      

    注意

    单个应用设定的最长数据迁移时间为十五分钟,超过十五分钟还未完成应用数据迁移的应用,应用数据迁移会失败。

APK应用沙箱目录与备份恢复目录映射关系见下表中所示:

APK应用沙箱目录

备份恢复目录

备份恢复目录获取方式

/data/user_de/{userId}/{APK包名}/

/data/storage/el1/base/.backup/restore/{APK包名}/de/

this.context.area = contextConstant.AreaMode.EL1;

let deSourcePath = this.context.backupDir + "restore/{APK包名}/de/"

/data/user/{userId}/{APK包名}/

/data/storage/el2/base/.backup/restore/{APK包名}/ce/

this.context.area = contextConstant.AreaMode.EL2;

let ceSourcePath = this.context.backupDir + "restore/{APK包名}/ce/"

/data/media/{userId}/Android/data/{APK包名}/

/data/storage/el2/base/.backup/restore/{APK包名}/A/data/

this.context.area = contextConstant.AreaMode.EL2;

let dataSourcePath = this.context.backupDir + "restore/{APK包名}/A/data/"

/data/media/{userId}/Android/obb/{APK包名}/

/data/storage/el2/base/.backup/restore/{APK包名}/A/obb/

this.context.area = contextConstant.AreaMode.EL2;

let obbSourcePath = this.context.backupDir + "restore/{APK包名}/A/obb/"

元数据资源配置文件适配

 

开发者通过元数据资源配置文件,启用备份恢复,并定义备份恢复框架需要传输的文件。

以下步骤以空工程为例,介绍如何配置元数据资源文件:

  1. entry/src/main/resources/base/profile/目录下,点击 New > File 创建backup_config.json文件。

  2. 参考示例代码实现元数据资源文件配置。
     
    {
      "allowToBackupRestore": true,
      "extraInfo": {
        "supportScene": [
          "hmos2next"
        ]
      }
    }
    

    module.json5适配

     

    开发者需要在应用配置文件module.json5中进行注册,其中注册类型type需要设置为backup,元数据信息metadata需要新增一个name为ohos.extension.backup的条目。

    注意

    extensionAbilities需要配置在entry内的module.json5才能正常访问。

    以下步骤以空工程为例,介绍如何配置module.json5文件:

  3. 开发者需要在entry内的module.json5里面进行注册,参考示例代码实现元数据资源文件配置。
     
    "extensionAbilities": [
      {
        "description": "DemoBackupExtension",
        "icon": "$media:app_icon",
        "name": "BackupExtensionAbility",
        "srcEntry": "./ets/backupExtension/BackupExtension.ets",  // 对应BackupExtension.ets在代码仓中的位置
        "type": "backup",                                         // 类型需要选择backup
        "exported": false,
        "metadata": [                                             // 对应注册的元数据资源
          {
            "name": "ohos.extension.backup",
            "resource": "$profile:backup_config"
          }
        ]
      }
    ]
    

评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值