1# @ohos.data.cloudData (Device-Cloud Synergy) 2 3The **cloudData** module provides the capability of synchronizing the structured data (in RDB stores) between the device and cloud. The cloud serves as the central node of data. The devices synchronize data with the data in the cloud to implement cloud data backup and data consistency between the devices with the same account. 4 5This module provides the following common functions: 6 7- [Config](#config): provides methods for configuring device-cloud synergy, including enabling and disabling cloud synchronization, clearing data, and notifying data changes. 8 9> **NOTE** 10> 11> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 12> 13> - The APIs provided by this module are system APIs. 14 15## Modules to Import 16 17```ts 18import cloudData from '@ohos.data.cloudData'; 19``` 20 21## ClearAction 22 23Enumerates the actions to take to clear the downloaded cloud data locally. 24 25**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 26 27| Name | Description | 28| --------- | ---------------------------- | 29| CLEAR_CLOUD_INFO | Clear only the cloud identifier of the data downloaded from the cloud. The related data is still stored as local data.| 30| CLEAR_CLOUD_DATA_AND_INFO |Clear the data downloaded from the cloud, excluding the cloud data that has been modified locally. | 31 32## Config 33 34Provides APIs for implementing device-cloud synergy, including enabling and disabling device-cloud synchronization, clearing data, and notifying data changes. 35 36### enableCloud 37 38static enableCloud(accountId: string, switches: {[bundleName: string]: boolean}, callback: AsyncCallback<void>):void 39 40Enables device-cloud synergy. This API uses an asynchronous callback to return the result. 41 42**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 43 44**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 45 46**Parameters** 47 48| Name | Type | Mandatory| Description | 49| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | 50| accountId | string | Yes | ID of the cloud account. | 51| switches | {[bundleName: string]: boolean} | Yes | Device-cloud synergy switches for applications. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.| 52| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 53 54**Example** 55 56```ts 57import { BusinessError } from '@ohos.base'; 58 59let account = 'test_id'; 60let switches: Record<string, boolean> = { 'test_bundleName1': true, 'test_bundleName2': false }; 61try { 62 cloudData.Config.enableCloud(account, switches, (err) => { 63 if (err === undefined) { 64 console.info('Succeeded in enabling cloud'); 65 } else { 66 console.error(`Failed to enable.Code: ${err.code}, message: ${err.message}`); 67 } 68 }); 69} catch (e) { 70 let error = e as BusinessError; 71 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 72} 73``` 74 75### enableCloud 76 77static enableCloud(accountId: string, switches: {[bundleName: string]: boolean}): Promise<void> 78 79Enables device-cloud synergy. This API uses a promise to return the result. 80 81**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 82 83**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 84 85**Parameters** 86 87| Name | Type | Mandatory| Description | 88| --------- | ------------------------------- | ---- | ------------------------------------------------------------ | 89| accountId | string | Yes | ID of the cloud account. | 90| switches | {[bundleName: string]: boolean} | Yes | Device-cloud synergy switches for applications. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.| 91 92**Return value** 93 94| Type | Description | 95| ------------------- | ------------------------- | 96| Promise<void> | Promise that returns no value.| 97 98**Example** 99 100```ts 101import { BusinessError } from '@ohos.base'; 102 103let account = 'test_id'; 104let switches: Record<string, boolean> = { 'test_bundleName1': true, 'test_bundleName2': false }; 105try { 106 cloudData.Config.enableCloud(account, switches).then(() => { 107 console.info('Succeeded in enabling cloud'); 108 }).catch((err: BusinessError) => { 109 console.error(`Failed to enable.Code: ${err.code}, message: ${err.message}`); 110 }); 111} catch (e) { 112 let error = e as BusinessError; 113 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 114} 115``` 116 117### disableCloud 118 119static disableCloud(accountId: string, callback: AsyncCallback<void>):void 120 121Disables device-cloud synergy. This API uses an asynchronous callback to return the result. 122 123**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 124 125**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 126 127**Parameters** 128 129| Name | Type | Mandatory| Description | 130| --------- | ------------------------- | ---- | -------------------- | 131| accountId | string | Yes | ID of the cloud account.| 132| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 133 134**Example** 135 136```ts 137import { BusinessError } from '@ohos.base'; 138 139let account = 'test_id'; 140try { 141 cloudData.Config.disableCloud(account, (err) => { 142 if (err === undefined) { 143 console.info('Succeeded in disabling cloud'); 144 } else { 145 console.error(`Failed to disableCloud. Code: ${err.code}, message: ${err.message}`); 146 } 147 }); 148} catch (e) { 149 let error = e as BusinessError; 150 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 151} 152``` 153 154### disableCloud 155 156static disableCloud(accountId: string): Promise<void> 157 158Disables device-cloud synergy. This API uses a promise to return the result. 159 160**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 161 162**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 163 164**Parameters** 165 166| Name | Type | Mandatory| Description | 167| --------- | ------ | ---- | -------------------- | 168| accountId | string | Yes | ID of the cloud account.| 169 170**Return value** 171 172| Type | Description | 173| ------------------- | ------------------------- | 174| Promise<void> | Promise that returns no value.| 175 176**Example** 177 178```ts 179import { BusinessError } from '@ohos.base'; 180 181let account = 'test_id'; 182try { 183 cloudData.Config.disableCloud(account).then(() => { 184 console.info('Succeeded in disabling cloud'); 185 }).catch((err: BusinessError) => { 186 console.error(`Failed to disableCloud. Code: ${err.code}, message: ${err.message}`); 187 }); 188} catch (e) { 189 let error = e as BusinessError; 190 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 191} 192``` 193 194### changeAppCloudSwitch 195 196static changeAppCloudSwitch(accountId: string,bundleName:string,status:boolean, callback: AsyncCallback<void>):void 197 198Changes the device-cloud synergy switch for an application. This API uses an asynchronous callback to return the result. 199 200**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 201 202**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 203 204**Parameters** 205 206| Name | Type | Mandatory| Description | 207| --------- | ------------------------------- | ---- | ---------------------------- | 208| accountId | string | Yes | ID of the cloud account.| 209| bundleName| string | Yes | Bundle name of the application.| 210| status | boolean | Yes | Setting of the device-cloud synergy switch for the application. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.| 211| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 212 213**Example** 214 215```ts 216import { BusinessError } from '@ohos.base'; 217 218let account = 'test_id'; 219let bundleName = 'test_bundleName'; 220try { 221 cloudData.Config.changeAppCloudSwitch(account, bundleName, true, (err) => { 222 if (err === undefined) { 223 console.info('Succeeded in changing App cloud switch'); 224 } else { 225 console.error(`Failed to change App cloud switch. Code: ${err.code}, message: ${err.message}`); 226 } 227 }); 228} catch (e) { 229 let error = e as BusinessError; 230 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 231} 232``` 233 234### changeAppCloudSwitch 235 236static changeAppCloudSwitch(accountId: string,bundleName:string,status:boolean): Promise<void> 237 238Changes the device-cloud synergy switch for an application. This API uses a promise to return the result. 239 240**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 241 242**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 243 244**Parameters** 245 246| Name | Type | Mandatory| Description | 247| --------- | ------------------------------- | ---- | ---------------------------- | 248| accountId | string | Yes | ID of the cloud account.| 249| bundleName| string | Yes | Bundle name of the application.| 250| status | boolean | Yes | Setting of the device-cloud synergy switch for the application. The value **true** means to enable the device-cloud synergy; the value **false** means the opposite.| 251 252**Return value** 253 254| Type | Description | 255| ------------------- | ------------------------- | 256| Promise<void> | Promise that returns no value.| 257 258**Example** 259 260```ts 261import { BusinessError } from '@ohos.base'; 262 263let account = 'test_id'; 264let bundleName = 'test_bundleName'; 265try { 266 cloudData.Config.changeAppCloudSwitch(account, bundleName, true).then(() => { 267 console.info('Succeeded in changing App cloud switch'); 268 }).catch((err: BusinessError) => { 269 console.error(`Failed to change App cloud switch. Code is ${err.code}, message is ${err.message}`); 270 }); 271} catch (e) { 272 let error = e as BusinessError; 273 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 274} 275``` 276 277### notifyDataChange 278 279static notifyDataChange(accountId: string,bundleName:string, callback: AsyncCallback<void>):void 280 281Notifies the data changes in the cloud. This API uses an asynchronous callback to return the result. 282 283**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 284 285**System capability**: SystemCapability.DistributedDataManager.CloudSync.Server 286 287**Parameters** 288 289| Name | Type | Mandatory| Description | 290| ---------- | ------------------------- | ---- | -------------------- | 291| accountId | string | Yes | ID of the cloud account.| 292| bundleName | string | Yes | Bundle name of the application. | 293| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 294 295**Example** 296 297```ts 298import { BusinessError } from '@ohos.base'; 299 300let account = 'test_id'; 301let bundleName = 'test_bundleName'; 302try { 303 cloudData.Config.notifyDataChange(account, bundleName, (err) => { 304 if (err === undefined) { 305 console.info('Succeeded in notifying the change of data'); 306 } else { 307 console.error(`Failed to notify the change of data. Code: ${err.code}, message: ${err.message}`); 308 } 309 }); 310} catch (e) { 311 let error = e as BusinessError; 312 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 313} 314``` 315 316### notifyDataChange 317 318static notifyDataChange(accountId: string,bundleName:string): Promise<void> 319 320Notifies the data changes in the cloud. This API uses a promise to return the result. 321 322**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 323 324**System capability**: SystemCapability.DistributedDataManager.CloudSync.Server 325 326**Parameters** 327 328| Name | Type | Mandatory| Description | 329| ---------- | ------ | ---- | -------------------- | 330| accountId | string | Yes | ID of the cloud account.| 331| bundleName | string | Yes | Bundle name of the application. | 332 333**Return value** 334 335| Type | Description | 336| ------------------- | ------------------------- | 337| Promise<void> | Promise that returns no value.| 338 339**Example** 340 341```ts 342import { BusinessError } from '@ohos.base'; 343 344let account = 'test_id'; 345let bundleName = 'test_bundleName'; 346try { 347 cloudData.Config.notifyDataChange(account, bundleName).then(() => { 348 console.info('Succeeded in notifying the change of data'); 349 }).catch((err: BusinessError) => { 350 console.error(`Failed to notify the change of data. Code: ${err.code}, message: ${err.message}`); 351 }); 352} catch (e) { 353 let error = e as BusinessError; 354 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 355} 356``` 357 358### clear 359 360static clear(accountId: string, appActions: {[bundleName: string]: ClearAction}, callback: AsyncCallback<void>):void 361 362Clears the cloud data locally. This API uses an asynchronous callback to return the result. 363 364**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 365 366**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 367 368**Parameters** 369 370| Name | Type | Mandatory| Description | 371| ---------- | --------------------------------------------------- | ---- | -------------------------------- | 372| accountId | string | Yes | ID of the cloud account. | 373| appActions | {[bundleName: string]: [ClearAction](#clearaction)} | Yes | Information about the application whose data is to be cleared and the action to take.| 374| callback | AsyncCallback<void> | Yes | Callback invoked to return the result. | 375 376**Example** 377 378```ts 379import { BusinessError } from '@ohos.base'; 380 381let action = cloudData.ClearAction; 382let account = "test_id"; 383type dataType = Record<string, cloudData.ClearAction> 384let appActions: dataType = { 385 'test_bundleName1': action.CLEAR_CLOUD_INFO, 386 'test_bundleName2': action.CLEAR_CLOUD_DATA_AND_INFO 387}; 388try { 389 cloudData.Config.clear(account, appActions, (err) => { 390 if (err === undefined) { 391 console.info('Succeeding in clearing cloud data'); 392 } else { 393 console.error(`Failed to clear cloud data. Code: ${err.code}, message: ${err.message}`); 394 } 395 }); 396} catch (e) { 397 let error = e as BusinessError; 398 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 399} 400``` 401 402### clear 403 404static clear(accountId: string, appActions: {[bundleName: string]: ClearAction}): Promise<void> 405 406Clears the cloud data locally. This API uses a promise to return the result. 407 408**Required permissions**: ohos.permission.CLOUDDATA_CONFIG 409 410**System capability**: SystemCapability.DistributedDataManager.CloudSync.Config 411 412**Parameters** 413 414| Name | Type | Mandatory| Description | 415| ---------- | --------------------------------------------------- | ---- | -------------------------------- | 416| accountId | string | Yes | ID of the cloud account. | 417| appActions | {[bundleName: string]: [ClearAction](#clearaction)} | Yes | Information about the application whose data is to be cleared and the action to take.| 418 419**Return value** 420 421| Type | Description | 422| ------------------- | ------------------------- | 423| Promise<void> | Promise that returns no value.| 424 425**Example** 426 427```ts 428import { BusinessError } from '@ohos.base'; 429 430let action = cloudData.ClearAction; 431let account = "test_id"; 432type dataType = Record<string, cloudData.ClearAction>; 433let appActions: dataType = { 434 'test_bundleName1': action.CLEAR_CLOUD_INFO, 435 'test_bundleName2': action.CLEAR_CLOUD_DATA_AND_INFO 436}; 437try { 438 cloudData.Config.clear(account, appActions).then(() => { 439 console.info('Succeeding in clearing cloud data'); 440 }).catch((err: BusinessError) => { 441 console.error(`Failed to clear cloud data. Code: ${err.code}, message: ${err.message}`); 442 }); 443} catch (e) { 444 let error = e as BusinessError; 445 console.error(`An unexpected error occurred. Code: ${error.code}, message: ${error.message}`); 446} 447``` 448