1# 分布式数据服务开发指导 2 3## 场景介绍 4 5分布式数据服务主要实现用户设备中应用程序数据内容的分布式同步。当设备1上的应用A在分布式数据库中增、删、改数据后，设备2上的应用A也可以获取到该数据库变化。可在分布式图库、信息、通讯录、文件管理器等场景中使用。 6 7 8## 接口说明 9 10具体分布式数据相关功能接口请见[分布式数据管理](../reference/apis/js-apis-distributed-data.md)。 11 12 13**表1** 分布式数据服务关键API功能介绍 14 15| 接口名称 | 描述 | 16| ------------------------------------------------------------ | ----------------------------------------------- | 17| createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void<br/>createKVManager(config: KVManagerConfig): Promise<KVManager> | 创建一个`KVManager`对象实例，用于管理数据库对象。 | 18| getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void<br/>getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T> | 指定`Options`和`storeId`，创建并获取`KVStore`数据库。 | 19| put(key: string, value: Uint8Array\|string\|number\|boolean, callback: AsyncCallback<void>): void<br/>put(key: string, value: Uint8Array\|string\|number\|boolean): Promise<void> | 插入和更新数据。 | 20| delete(key: string, callback: AsyncCallback<void>): void<br/>delete(key: string): Promise<void> | 删除数据。 | 21| get(key: string, callback: AsyncCallback<Uint8Array\|string\|boolean\|number>): void<br/>get(key: string): Promise<Uint8Array\|string\|boolean\|number> | 查询数据。 | 22| on(event: 'dataChange', type: SubscribeType, observer: Callback<ChangeNotification>): void<br/>on(event: 'syncComplete', syncCallback: Callback<Array<[string,number]>>): void | 订阅数据库中数据的变化。 | 23| sync(deviceIdList: string[], mode: SyncMode, allowedDelayMs?: number): void | 在手动模式下，触发数据库同步。 | 24 25 26 27 28## 开发步骤 29 30以单版本分布式数据库为例，说明开发步骤。 31 321. 导入模块。 33 34 ```js 35 import distributedData from '@ohos.data.distributedData'; 36 ``` 372. 请求权限（同步操作时进行该步骤）。 38 39 需要在`config.json`文件里进行配置请求权限，示例代码如下： 40 41 ```json 42 { 43 "module": { 44 "reqPermissions": [ 45 { 46 "name": "ohos.permission.DISTRIBUTED_DATASYNC" 47 } 48 ] 49 } 50 } 51 ``` 52 这个权限还需要在应用首次启动的时候弹窗获取用户授权，可以通过如下代码实现： 53 54 ```js 55 import featureAbility from '@ohos.ability.featureAbility'; 56 57 function grantPermission() { 58 console.info('grantPermission'); 59 let context = featureAbility.getContext(); 60 context.requestPermissionsFromUser(['ohos.permission.DISTRIBUTED_DATASYNC'], 666, function (result) { 61 console.info(`result.requestCode=${result.requestCode}`) 62 63 }) 64 console.info('end grantPermission'); 65 } 66 67 grantPermission(); 68 ``` 69 703. 根据配置构造分布式数据库管理类实例。 71 72 1. 根据应用上下文创建`kvManagerConfig`对象。 73 2. 创建分布式数据库管理器实例。 74 75 以下为创建分布式数据库管理器的代码示例： 76 ```js 77 let kvManager; 78 try { 79 const kvManagerConfig = { 80 bundleName : 'com.example.datamanagertest', 81 userInfo : { 82 userId : '0', 83 userType : distributedData.UserType.SAME_USER_ID 84 } 85 } 86 distributedData.createKVManager(kvManagerConfig, function (err, manager) { 87 if (err) { 88 console.log("createKVManager err: " + JSON.stringify(err)); 89 return; 90 } 91 console.log("createKVManager success"); 92 kvManager = manager; 93 }); 94 } catch (e) { 95 console.log("An unexpected error occurred. Error:" + e); 96 } 97 ``` 98 994. 获取/创建分布式数据库。 100 101 1. 声明需要创建的分布式数据库ID描述。 102 2. 创建分布式数据库，建议关闭自动同步功能（`autoSync:false`），需要同步时主动调用`sync`接口。 103 104 以下为创建分布式数据库的代码示例： 105 ```js 106 let kvStore; 107 try { 108 const options = { 109 createIfMissing : true, 110 encrypt : false, 111 backup : false, 112 autoSync : false, 113 kvStoreType : distributedData.KVStoreType.SINGLE_VERSION, 114 securityLevel : distributedData.SecurityLevel.S0, 115 }; 116 kvManager.getKVStore('storeId', options, function (err, store) { 117 if (err) { 118 console.log("getKVStore err: " + JSON.stringify(err)); 119 return; 120 } 121 console.log("getKVStore success"); 122 kvStore = store; 123 }); 124 } catch (e) { 125 console.log("An unexpected error occurred. Error:" + e); 126 } 127 ``` 128 129 > **说明：** 130 > 131 > 组网设备间同步数据的场景，建议在应用启动时打开分布式数据库，获取数据库的句柄。在该句柄（如示例中的`kvStore`）的生命周期内无需重复创建数据库，可直接使用句柄对数据库进行数据的插入等操作。 132 1335. 订阅分布式数据变化。 134 135 以下为订阅单版本分布式数据库数据变化通知的代码示例: 136 ```js 137 kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) { 138 console.log("dataChange callback call data: " + JSON.stringify(data)); 139 }); 140 ``` 141 1426. 将数据写入分布式数据库。 143 144 1. 构造需要写入分布式数据库的`Key`（键）和`Value`（值）。 145 2. 将键值数据写入分布式数据库。 146 147 以下为将字符串类型键值数据写入分布式数据库的代码示例： 148 149 ```js 150 const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 151 const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 152 try { 153 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { 154 if (err != undefined) { 155 console.log("put err: " + JSON.stringify(err)); 156 return; 157 } 158 console.log("put success"); 159 }); 160 }catch (e) { 161 console.log("An unexpected error occurred. Error:" + e); 162 } 163 ``` 164 1657. 查询分布式数据库数据。 166 167 1. 构造需要从单版本分布式数据库中查询的`Key`（键）。 168 2. 从单版本分布式数据库中获取数据。 169 170 以下为从分布式数据库中查询字符串类型数据的代码示例： 171 ```js 172 const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 173 const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 174 try { 175 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) { 176 if (err != undefined) { 177 console.log("put err: " + JSON.stringify(err)); 178 return; 179 } 180 console.log("put success"); 181 kvStore.get(KEY_TEST_STRING_ELEMENT, function (err,data) { 182 console.log("get success data: " + data); 183 }); 184 }); 185 }catch (e) { 186 console.log("An unexpected error occurred. Error:" + e); 187 } 188 ``` 189 1908. 同步数据到其他设备。 191 192 选择同一组网环境下的设备以及同步模式，进行数据同步。 193 194 > **说明**： 195 > 196 > 其中`deviceManager`模块的接口均为系统接口。 197 198 以下为单版本分布式数据库进行数据同步的代码示例： 199 ```js 200 import deviceManager from '@ohos.distributedHardware.deviceManager'; 201 202 let devManager; 203 // create deviceManager 204 deviceManager.createDeviceManager("bundleName", (err, value) => { 205 if (!err) { 206 devManager = value; 207 // deviceIds由deviceManager调用getTrustedDeviceListSync方法得到 208 let deviceIds = []; 209 if (devManager != null) { 210 var devices = devManager.getTrustedDeviceListSync(); 211 for (var i = 0; i < devices.length; i++) { 212 deviceIds[i] = devices[i].deviceId; 213 } 214 } 215 try{ 216 // 1000表示最大延迟时间为1000ms 217 kvStore.sync(deviceIds, distributedData.SyncMode.PUSH_ONLY, 1000); 218 }catch (e) { 219 console.log("An unexpected error occurred. Error:" + e); 220 } 221 } 222 }); 223 ``` 224## 相关实例 225 226针对分布式数据开发，有以下相关实例可供参考： 227 228- [`DistributedCalc`：分布式计算器（JS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/samples_monthly_0730/common/DistributeCalc) 229- [`DistributedCalc`：分布式计算器（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/samples_monthly_0730/Preset/DistributeCalc) 230- [`DDMQuery`：结果集与谓词（eTS）（API8）](https://gitee.com/openharmony/applications_app_samples/tree/samples_monthly_0730/data/DDMQuery) 231- [`KvStore`：分布式数据库（eTS）（API8）（Full SDK）](https://gitee.com/openharmony/applications_app_samples/tree/samples_monthly_0730/data/Kvstore) 232- [分布式数据库（JS）（API8）](https://gitee.com/openharmony/codelabs/tree/master/Data/JsDistributedData)