Accessing Backup and Restore

You can use BackupExtensionAbility to enable an application to access the backup and restore framework.

BackupExtensionAbility is a class derived from ExtensionAbility in the stage model. The application that has accessed the backup and restore framework can customize the backup and restore behavior, including whether to enable backup and restore and specifying the data to be backed up, in a profile.

Available APIs

For details about how to use the APIs of BackupExtensionAbility, see BackupExtensionAbility.

Constraints

• The path of the file or directory to be backed up or restored cannot exceed 4095 bytes. Otherwise, undefined behavior may occur.
• If a directory needs to be backed up, the application process must have the permission to read the directory and all its subdirectories (r in DAC). Otherwise, the backup fails.
• If a file needs to be backed up, the application process must have the permission to retrieve all the ancestor directories of the file (x in DAC). Otherwise, the backup fails.

How to Develop

1. Add extensionAbilities to the application's module.json5 file.

   In module.json5, add the extensionAbilities field, set type to backup, and add a record with name set to ohos.extension.backup under metadata.

   Example:

   {
       "extensionAbilities": [
           {
               "description": "$string:ServiceExtAbility",
               "icon": "$media:icon",
               "name": "BackupExtensionAbility",
               "type": "backup",
               "visible": true,
               "metadata": [
                   {
                       "name": "ohos.extension.backup",
                       "resource": "$profile:backup_config"
                   }
               ],
               // In the BackupExtension.ts file, inherit from BackupExtensionAbility and override the onBackup and onRestore methods.
               // If there is no special requirement, you do not have to override onBackup and onRestore. In this case, the backup and restore service backs up or restores data based on the unified backup and restore rules.
               "srcEntrance": "./ets/BackupExtension/BackupExtension.ts", 
           }      
       ]
   }
   

2. Add a metadata profile.

   The metadata profile defines the files to be transferred during the backup and restore process. The profile is located in the resources/profile directory of the project, and the file name must be the same as the value of metadata.resource in the module.json5 file.

   Example:

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

3. Customize BackupExtensionAbility inherited by the class in the BackupExtension.ts file and override onBackup or onRestore to back up preprocessed application data or process the data to be restored.

   Use an empty implementation if there is no special requirement. In this case, the backup and restore service backs up or restores data based on the unified backup and restore rules.

   The following example shows an empty implementation of the BackupExtension.ts file.

   import BackupExtensionAbility, {BundleVersion} from '@ohos.application.BackupExtensionAbility';
   import Logger from '../common/Logger';
   
   const TAG = `FileBackupExtensionAbility`;
   export default class BackupExtension extends  BackupExtensionAbility {
     async onBackup ()   {
       Logger.info(TAG, `onBackup ok`);
     }
   
     async onRestore (bundleVersion : BundleVersion) {
       Logger.info(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
       Logger.info(TAG, `onRestore end`);
     }
   }
   

Description of the Metadata Profile

NOTE

When setting fullBackupOnly, note the following:

• If fullBackupOnly is set to false, the restored files will overwrite the file with the same name in the directory.
• If fullBackupOnly is set to true, the restored data is decompressed in the /data/storage/el2/backup/restore/ directory. You can access the data via OnRestore to restore it.

You can set fullBackupOnly based on service requirements. If fullBackupOnly is set to true, you need to implement the data restore logic in OnRestore.

For example, if the application backup path is data/storage/el2/base/files/A/, the data restored will be decompressed to the /data/storage/el2/backup/restore/data/storage/el2/base/files/A/ directory.

includes default:

{
    "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/"
    ]
}