1# Accessing Backup and Restore 2 3You can use BackupExtensionAbility to enable an application to access the backup and restore framework. 4 5BackupExtensionAbility is a class derived from [ExtensionAbility](../application-models/extensionability-overview.md) in the [stage model](../application-models/stage-model-development-overview.md). 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. 6 7## Available APIs 8 9| Module | Class | Interface | Description | 10| ----------- | ---------------------- | --------------------------------------------- | ----------------------------------------------------------------- | 11| application | BundleVersion | code: number | Application version number. | 12| application | BundleVersion | name: string | Application version name. | 13| application | BackupExtensionAbility | onBackup(): void | Callback provided by BackupExtensionAbility and implemented by the developer for data backup.| 14| application | BackupExtensionAbility | onRestore(bundleVersion: BundleVersion): void | Callback provided by BackupExtensionAbility and implemented by the developer for data restore.| 15| application | BackupExtensionAbility | context: ExtensionContext | BackupExtensionAbility context, which inherits from **Context**. | 16 17For details about how to use the APIs of BackupExtensionAbility, see [BackupExtensionAbility](../reference/apis/js-apis-application-backupExtensionAbility.md#backupextensionability). 18 19## Constraints 20 21- The path of the file or directory to be backed up or restored cannot exceed 4095 bytes. Otherwise, undefined behavior may occur. 22- 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. 23- 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. 24 25## How to Develop 26 271. Add **extensionAbilities** to the application's **module.json5** file. 28 29 In **module.json5**, add the **extensionAbilities** field, set **type** to **backup**, and add a record with **name** set to **ohos.extension.backup** under **[metadata](../reference/apis/js-apis-bundleManager-metadata.md)**. 30 31 Example: 32 33 ```json 34 { 35 "extensionAbilities": [ 36 { 37 "description": "$string:ServiceExtAbility", 38 "icon": "$media:icon", 39 "name": "BackupExtensionAbility", 40 "type": "backup", 41 "visible": true, 42 "metadata": [ 43 { 44 "name": "ohos.extension.backup", 45 "resource": "$profile:backup_config" 46 } 47 ], 48 // In the BackupExtension.ts file, inherit from BackupExtensionAbility and override the onBackup and onRestore methods. 49 // 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. 50 "srcEntrance": "./ets/BackupExtension/BackupExtension.ts", 51 } 52 ] 53 } 54 ``` 55 562. Add a metadata profile. 57 58 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. 59 60 Example: 61 62 ```json 63 { 64 "allowToBackupRestore": true, 65 "includes": [ 66 "/data/storage/el2/base/files/users/" 67 ], 68 "excludes": [ 69 "/data/storage/el2/base/files/users/hidden/" 70 ], 71 "fullBackupOnly": false, 72 "restoreDeps": "", 73 } 74 ``` 75 763. 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. 77 78 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. 79 80 The following example shows an empty implementation of the **BackupExtension.ts** file. 81 82 ```ts 83 import BackupExtensionAbility, {BundleVersion} from '@ohos.application.BackupExtensionAbility'; 84 import Logger from '../common/Logger'; 85 86 const TAG = `FileBackupExtensionAbility`; 87 export default class BackupExtension extends BackupExtensionAbility { 88 async onBackup () { 89 Logger.info(TAG, `onBackup ok`); 90 } 91 92 async onRestore (bundleVersion : BundleVersion) { 93 Logger.info(TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`); 94 Logger.info(TAG, `onRestore end`); 95 } 96 } 97 ``` 98 99### Description of the Metadata Profile 100 101| Field | Type | Mandatory| Description | 102| -------------------- | ---------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 103| allowToBackupRestore | Boolean | Yes | Whether to enable backup and restore. The default value is **false**. | 104| includes | String array| No | Files and directories to be backed up in the application sandbox directory.<br>The value is an array of pattern strings, which can contain shell-style wildcards such as *, ?, and [.<br>The pattern string that does not start with a slash (/) indicates a relative path.<br>If **includes** is not specified, the backup and restore framework uses the **includes** default (as listed in the code snippet below).| 105| excludes | String array| No | Items in **includes** that do not need to be backed up. The value is in the same format as **includes**.<br>If **excludes** is not configured, the backup and restore framework uses an empty array by default. | 106| fullBackupOnly | Boolean | No | Whether to use the default restore directory of the application. The default value is **false**. If the value is **true**, data is decompressed under **/data/storage/el2/backup/restore/** during the data restore process.<br>If the value is **false** or is not specified, data is decompressed under **/**. | 107| restoreDeps | String | No | Names of the applications, on which the application restore depends. Use commas (,) to separate multiple applications. The default value is "". | 108 109> **NOTE** 110> 111> When setting **fullBackupOnly**, note the following: 112> - If **fullBackupOnly** is set to **false**, the restored files will overwrite the file with the same name in the directory. 113> - 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. 114> 115> You can set **fullBackupOnly** based on service requirements. If **fullBackupOnly** is set to **true**, you need to implement the data restore logic in **OnRestore**. 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. 116> 117 118**includes** default: 119 120```json 121{ 122 "includes": [ 123 "data/storage/el1/database/", 124 "data/storage/el1/base/files/", 125 "data/storage/el1/base/preferences/", 126 "data/storage/el1/base/haps/<module-name>/files/", 127 "data/storage/el1/base/haps/<module-name>/preferences/", 128 "data/storage/el2/database/", 129 "data/storage/el2/base/files/", 130 "data/storage/el2/base/preferences/", 131 "data/storage/el2/base/haps/<module-name>/files/", 132 "data/storage/el2/base/haps/<module-name>/preferences/", 133 "data/storage/el2/distributedfiles/" 134 ] 135} 136``` 137 138