• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Accessing Backup and Restore
2
3You can use **BackupExtensionAbility** to enable an application to access the backup and restore framework.
4
5**BackupExtensionAbility** 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
9For details about how to use the APIs, see [BackupExtensionAbility](../reference/apis-core-file-kit/js-apis-application-backupExtensionAbility.md#backupextensionability) and [Backup and Restore Extension Capability](../reference/apis-core-file-kit/js-apis-file-backupextensioncontext.md).
10
11## Constraints
12
13- The path of the file or directory to be backed up or restored cannot exceed 4095 bytes. Otherwise, undefined behavior may occur.
14- 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.
15- 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.
16- The path of the file or directory to be backed up or restored does not support relative paths (**../**) and soft links.
17
18## How to Develop
19
201. Add `extensionAbilities` to the application's `module.json5` file.
21
22   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-ability-kit/js-apis-bundleManager-metadata.md)**.
23
24   Example:
25
26   ```json
27   {
28       "extensionAbilities": [
29           {
30               "description": "$string:ServiceExtAbility",
31               "icon": "$media:icon",
32               "name": "BackupExtensionAbility",
33               "type": "backup",
34               "exported": false,
35               "metadata": [
36                   {
37                       "name": "ohos.extension.backup",
38                       "resource": "$profile:backup_config"
39                   }
40               ],
41               // In the BackupExtension.ets file, define BackupExtensionAbility in extensionAbilities and override onBackup or onBackupEx
42               // and onRestore or onRestoreEx methods. The onBackupEx and onRestoreEx methods are recommended.
43               // Empty implementation can be used 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.
44               "srcEntry": "./ets/BackupExtension/BackupExtension.ets",
45           }
46       ]
47   }
48   ```
49
502. Add a metadata profile.
51
52   The metadata profile defines the files to be transferred during the backup and restore process. The profile is located in the **resources/base/profile** directory of the project, and the file name must be the same as the value of **metadata.resource**, for example, **backup_config.json** in the **module.json5** file.
53
54   Metadata profile example:
55
56   ```json
57   {
58       "allowToBackupRestore": true,
59       "includes": [
60           "/data/storage/el2/base/files/users/"
61       ],
62       "excludes": [
63           "/data/storage/el2/base/files/users/hidden/"
64       ],
65       "fullBackupOnly": false,
66       "restoreDeps": ""
67   }
68   ```
69
703. Customize **BackupExtensionAbility** in the **BackupExtension.ets** file and override **onBackup**/**onBackupEx** or **onRestore**/**onRestoreEx** to back up preprocessed application data or process the data to be restored.
71
72   Empty implementation can be used 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.
73
74   The following example shows an empty implementation of the `BackupExtension.ets` file.
75
76    ```ts
77    //onBackup && onRestore
78    import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
79    import {hilog} from '@kit.PerformanceAnalysisKit';
80
81    const TAG = `FileBackupExtensionAbility`;
82    export default class BackupExtension extends  BackupExtensionAbility {
83      //onBackup
84      async onBackup ()   {
85        hilog.info(0x0000, TAG, `onBackup ok`);
86      }
87      //onRestore
88      async onRestore (bundleVersion : BundleVersion) {
89        hilog.info(0x0000, TAG, `onRestore ok ${JSON.stringify(bundleVersion)}`);
90        hilog.info(0x0000, TAG, `onRestore end`);
91      }
92    }
93    ```
94
95    ```ts
96    //onBackupEx && onRestoreEx
97    import { BackupExtensionAbility, BundleVersion } from '@kit.CoreFileKit';
98
99    interface ErrorInfo {
100      type: string,
101      errorCode: number,
102      errorInfo: string
103    }
104
105    class BackupExt extends BackupExtensionAbility {
106      //onBackupEx
107      async onBackupEx(backupInfo: string): Promise<string> {
108        console.log(`onBackupEx ok`);
109        let errorInfo: ErrorInfo = {
110          type: "ErrorInfo",
111          errorCode: 0,
112          errorInfo: "app diy error info"
113        }
114        return JSON.stringify(errorInfo);
115      }
116
117      // onRestoreEx
118      async onRestoreEx(bundleVersion : BundleVersion, restoreInfo: string): Promise<string> {
119        console.log(`onRestoreEx ok ${JSON.stringify(bundleVersion)}`);
120        let errorInfo: ErrorInfo = {
121          type: "ErrorInfo",
122          errorCode: 0,
123          errorInfo: "app diy error info"
124        }
125        return JSON.stringify(errorInfo);
126      }
127    }
128    ```
129
130### Description of the Metadata Profile
131
132| Field            | Type  | Mandatory| Description                                                        |
133| -------------------- | ---------- | ---- | ------------------------------------------------------------ |
134| allowToBackupRestore | Boolean    | Yes  | Whether to enable backup and restore. The default value is **false**.                             |
135| includes             | String array| No  | Files and directories to be backed up in the application sandbox directory.<br>The pattern string that does not start with a slash (/) indicates a relative path.<br>When configuring `includes`, ensure that the configured path range is included in the supported paths listed in the following code snippet.<br>If `includes` is not configured, the backup and restore framework uses the **includes** default (as listed in the code snippet below).|
136| 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>When configuring `excludes`, ensure that it is within the subset of `includes`.<br>If `excludes` is not configured, the backup and restore framework uses an empty array by default.|
137| fullBackupOnly       | Boolean    | No  | Whether to use the default restore directory of the application. The default value is **false**. If the value is **true**, data will be cached in a temporary directory obtained by [backupDir](../reference/apis-core-file-kit/js-apis-file-backupextensioncontext.md) in the data restore process. If it is **false** or not specified, the restored data is decompressed in **/**.|
138| restoreDeps          | String    | No  | **(Not recommended)** Dependencies for the application to restore. The default value is "". You need to configure the names of the dependent applications. Currently, only one dependency is supported. The configured dependency takes effect only in the context of one restore task. If no dependent application is detected, the dependency description will be ignored and the restore task continues. The application restore will fail if the dependent application is not restored or fails to be restored.|
139| extraInfo            | JSON string    | No  | Additional information to be passed.                                  |
140
141> **NOTE**
142>
143> When setting **fullBackupOnly**, observe the following:
144>
145> - If **fullBackupOnly** is set to **false**, the restored data will be decompressed in the root directory **/**, and the file with the same name in the directory will be overwritten.
146> - If **fullBackupOnly** is set to **true**, the restored data will be decompressed in a temporary directory. You need to implement the data restoration logic in **OnRestore** or **OnRestoreEx**.
147>
148> You can determine the data restore mode to use based on service requirements.
149>
150> Example:
151> Assume that the application backup path is **data/storage/el2/base/files/A/**. If **fullBackupOnly** is **false**, the restored data will be decompressed to the **/data/storage/el2/base/files/A/** directory. If **fullBackupOnly** is **true**, data will be decompressed to the temporary directory **[backupDir](../reference/apis-core-file-kit/js-apis-file-backupextensioncontext.md)/restore/data/storage/el2/base/files/A/**.
152
153The following lists the paths supported by **includes**:
154
155```json
156{
157    "includes": [
158    "data/storage/el1/database/",
159    "data/storage/el1/base/files/",
160    "data/storage/el1/base/preferences/",
161    "data/storage/el1/base/haps/*/files/",
162    "data/storage/el1/base/haps/*/preferences/",
163    "data/storage/el2/database/",
164    "data/storage/el2/base/files/",
165    "data/storage/el2/base/preferences/",
166    "data/storage/el2/base/haps/*/files/",
167    "data/storage/el2/base/haps/*/preferences/",
168    "data/storage/el2/distributedfiles/",
169    "data/storage/el5/database/",
170    "data/storage/el5/base/files/",
171    "data/storage/el5/base/preferences/",
172    "data/storage/el5/base/haps/*/files/",
173    "data/storage/el5/base/haps/*/preferences/"
174    ]
175}
176```
177
178##
179
180
181
182-
183