1# 键值型数据库跨设备数据同步 (ArkTS) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @ding_dong_dong--> 5<!--Designer: @dboy190; @houpengtao1--> 6<!--Tester: @logic42--> 7<!--Adviser: @ge-yafang--> 8 9 10## 场景介绍 11 12键值型数据库适合不涉及过多数据关系和业务关系的业务数据存储，比SQL数据库存储拥有更好的读写性能，同时因其在分布式场景中降低了解决数据库版本兼容问题的复杂度，和数据端端同步过程中冲突解决的复杂度而被广泛使用。 13 14 15## 基本概念 16 17在使用键值型数据库跨设备数据端端同步前，请先了解以下概念。 18 19 20### 单版本数据库 21 22单版本是指数据在本地是以单个条目为单位的方式保存，当用户修改时，直接在这个条目上进行修改。在数据端端同步后多个设备全局只保留一份数据，多个设备的相同记录（主码相同）会按时间最新保留一条记录，数据不分设备，设备之间修改相同的key会覆盖。端端同步也以此为基础，按照它在本地被写入或更改的顺序将当前最新一次修改逐条同步至远端设备，常用于联系人、天气等应用存储场景。 23 24 25 26 27### 多设备协同数据库 28 29多设备协同分布式数据库建立在单版本数据库之上，对应用程序存入的键值型数据中的Key前面拼接了本设备的DeviceID标识符，这样能保证每个设备产生的数据严格隔离。数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。 30 31底层按照设备的维度管理这些数据，多设备协同数据库支持以设备的维度查询分布式数据，但是不支持修改远端设备同步过来的数据。需要分开查询各设备数据的可以使用设备协同版本数据库。常用于图库缩略图存储场景。 32 33 34 35 36## 端端同步方式 37 38数据管理服务提供了两种同步方式：手动同步和自动同步。键值型数据库可选择其中一种方式实现同应用跨设备数据端端同步。 39 40### 手动同步 41 42由应用程序调用sync接口来触发，需要指定端端同步的设备列表和同步模式。同步模式分为PULL_ONLY（将远端数据拉取到本端）、PUSH_ONLY（将本端数据推送到远端）和PUSH_PULL（将本端数据推送到远端同时也将远端数据拉取到本端）。[带有Query参数的端端同步接口](../reference/apis-arkdata/js-apis-distributedKVStore.md#sync-1)，支持按条件过滤的方法进行端端同步，将符合条件的数据同步到远端。 43 44### 自动同步 45 46<!--RP5--> 47在[跨设备Call调用实现的多端协同](../application-models/hop-multi-device-collaboration.md#通过跨设备call调用实现多端协同)场景中，在应用程序更新数据后，由分布式数据库自动将本端数据推送到远端，同时也将远端数据拉取到本端来完成数据同步，应用不需要主动调用sync接口。<!--RP5End--> 48 49 50## 运作机制 51 52底层通信组件完成设备发现和认证，会通知上层应用程序设备上线。收到设备上线的消息后数据管理服务可以在两个设备之间建立加密的数据传输通道，利用该通道在两个设备之间进行数据端端同步。 53 54 55### 数据跨设备端端同步机制 56 57 58 59如图所示，通过put、delete接口触发自动端端同步，将分布式数据通过通信适配层发送给对端设备，实现分布式数据的自动端端同步。 60 61手动同步则是手动调用sync接口触发端端同步，将分布式数据通过通信适配层发送给对端设备。 62 63 64### 数据变化通知机制 65 66增、删、改数据时，会给订阅者发送数据变化的通知。主要分为本地数据变化通知和分布式数据变化通知。 67 68- **本地数据变化通知**：本地设备的应用内订阅数据变化通知，数据库增删改数据时，会收到通知。 69 70- **分布式数据变化通知**：同一应用订阅组网内其他设备数据变化的通知，其他设备增删改数据时，本设备会收到通知。 71 72 73## 约束限制 74 75- 设备协同数据库，针对每条记录，Key的长度≤896 Byte，Value的长度<4 MB。 76 77- 单版本数据库，针对每条记录，Key的长度≤1 KB，Value的长度<4 MB。 78 79- 键值型数据库不支持应用程序自定义冲突解决策略。 80 81- 每个应用程序可以同时打开最多16个键值型分布式数据库。 82 83- 单个数据库可以注册最多8个订阅数据变化的回调。 84 85 86## 接口说明 87 88以下是单版本键值型分布式数据库跨设备数据端端同步功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见[分布式键值数据库](../reference/apis-arkdata/js-apis-distributedKVStore.md)。 89 90| 接口名称 | 描述 | 91| -------- | -------- | 92| createKVManager(config: KVManagerConfig): KVManager | 创建一个KVManager对象实例，用于管理数据库对象。 | 93| getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void | 指定options和storeId，创建并得到指定类型的KVStore数据库。 | 94| put(key: string, value: Uint8Array \| string \| number \| boolean, callback: AsyncCallback<void>): void | 插入和更新数据。 | 95| on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void | 订阅数据库中数据的变化。 | 96| get(key: string, callback: AsyncCallback<boolean \| string \| number \| Uint8Array>): void | 查询指定Key键的值。 | 97| sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void | 在手动模式下，触发数据库端端同步。 | 98 99 100## 开发步骤 101 102此处以单版本键值型数据库跨设备数据端端同步的开发为例。以下是具体的开发流程和开发步骤。 103 104 105 106> **说明：** 107> 108> 数据只允许向数据安全标签不高于对端设备安全等级的设备同步数据，具体规则可见[跨设备同步访问控制机制](access-control-by-device-and-data-level.md#跨设备同步访问控制机制)。 109 1101. 导入模块。 111 112 ```ts 113 import { distributedKVStore } from '@kit.ArkData'; 114 ``` 115 1162. 请求权限。 117 118 1. 需要申请ohos.permission.DISTRIBUTED_DATASYNC权限，配置方式请参见[声明权限](../security/AccessToken/declare-permissions.md)。 119 2. 同时需要在应用首次启动时弹窗向用户申请授权，使用方式请参见[向用户申请授权](../security/AccessToken/request-user-authorization.md)。 120 1213. 根据配置调用createKVManager()方法构造分布式数据库管理类实例。 122 123 1. 根据应用上下文创建kvManagerConfig对象。 124 2. 创建分布式数据库管理器实例。 125 126 127 ```ts 128 // Stage模型获取context 129 import { window } from '@kit.ArkUI'; 130 import { UIAbility } from '@kit.AbilityKit'; 131 import { BusinessError } from '@kit.BasicServicesKit'; 132 133 let kvManager: distributedKVStore.KVManager | undefined = undefined; 134 135 class EntryAbility extends UIAbility { 136 onWindowStageCreate(windowStage:window.WindowStage) { 137 let context = this.context; 138 } 139 } 140 141 // FA模型获取context 142 import { featureAbility } from '@kit.AbilityKit'; 143 import { BusinessError } from '@kit.BasicServicesKit'; 144 145 let context = featureAbility.getContext(); 146 147 // 获取context之后，构造分布式数据库管理类实例 148 try { 149 const kvManagerConfig: distributedKVStore.KVManagerConfig = { 150 bundleName: 'com.example.datamanagertest', 151 context: context 152 } 153 kvManager = distributedKVStore.createKVManager(kvManagerConfig); 154 console.info('Succeeded in creating KVManager.'); 155 // 继续创建获取数据库 156 } catch (e) { 157 let error = e as BusinessError; 158 console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`); 159 } 160 161 if (kvManager !== undefined) { 162 // 进行后续创建数据库等相关操作 163 // ... 164 } 165 ``` 166 1674. 调用getKVStore()方法获取并得到指定类型的键值型数据库。 168 169 1. 声明需要创建的分布式数据库ID描述（例如示例代码中的'storeId'）。 170 2. 创建分布式数据库，建议关闭自动端端同步功能（autoSync:false），方便后续对端端同步功能进行验证，需要端端同步时主动调用sync接口。 171 172 173 ```ts 174 let kvStore: distributedKVStore.SingleKVStore | undefined = undefined; 175 try { 176 let child1 = new distributedKVStore.FieldNode('id'); 177 child1.type = distributedKVStore.ValueType.INTEGER; 178 child1.nullable = false; 179 child1.default = '1'; 180 let child2 = new distributedKVStore.FieldNode('name'); 181 child2.type = distributedKVStore.ValueType.STRING; 182 child2.nullable = false; 183 child2.default = 'zhangsan'; 184 185 let schema = new distributedKVStore.Schema(); 186 schema.root.appendChild(child1); 187 schema.root.appendChild(child2); 188 schema.indexes = ['$.id', '$.name']; 189 // 0表示COMPATIBLE模式，1表示STRICT模式。 190 schema.mode = 1; 191 // 支持在检查Value时，跳过skip指定的字节数，且取值范围为[0,4M-2]。 192 schema.skip = 0; 193 194 const options: distributedKVStore.Options = { 195 createIfMissing: true, 196 encrypt: false, 197 backup: false, 198 autoSync: false, 199 // kvStoreType不填时，默认创建多设备协同数据库 200 // 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION, 201 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 202 // schema 可以不填，在需要使用schema功能时可以构造此参数，例如：使用谓词查询等。 203 schema: schema, 204 securityLevel: distributedKVStore.SecurityLevel.S3 205 }; 206 kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => { 207 if (err) { 208 console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`); 209 return; 210 } 211 console.info('Succeeded in getting KVStore.'); 212 kvStore = store; 213 if (kvStore !== undefined) { 214 // 请确保获取到键值数据库实例后，再进行相关数据操作 215 // 进行后续相关数据操作，包括数据的增、删、改、查、订阅数据变化等操作 216 // ... 217 } 218 }); 219 } catch (e) { 220 let error = e as BusinessError; 221 console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`); 222 } 223 ``` 224 2255. 调用on()方法订阅分布式数据变化，如需关闭订阅分布式数据变化，调用[off('dataChange')](../reference/apis-arkdata/js-apis-distributedKVStore.md#offdatachange)关闭。 226 227 ```ts 228 try { 229 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => { 230 console.info(`dataChange callback call data: ${data}`); 231 }); 232 } catch (e) { 233 let error = e as BusinessError; 234 console.error(`An unexpected error occurred. code:${error.code},message:${error.message}`); 235 } 236 ``` 237 2386. 调用put()方法将数据写入分布式数据库。 239 240 1. 构造需要写入分布式数据库的Key（键）和Value（值）。 241 2. 将键值数据写入分布式数据库。 242 243 244 ```ts 245 const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 246 // 如果未定义Schema则Value可以传其他符合要求的值。 247 const VALUE_TEST_STRING_ELEMENT = '{"id":0, "name":"lisi"}'; 248 try { 249 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => { 250 if (err !== undefined) { 251 console.error(`Failed to put data. Code:${err.code},message:${err.message}`); 252 return; 253 } 254 console.info('Succeeded in putting data.'); 255 }); 256 } catch (e) { 257 let error = e as BusinessError; 258 console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`); 259 } 260 ``` 261 2627. 调用get()方法查询分布式数据库数据。 263 264 1. 构造需要从单版本分布式数据库中查询的Key（键）。 265 2. 从单版本分布式数据库中获取数据。 266 267 268 ```ts 269 try { 270 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => { 271 if (err !== undefined) { 272 console.error(`Failed to put data. Code:${err.code},message:${err.message}`); 273 return; 274 } 275 console.info('Succeeded in putting data.'); 276 kvStore = kvStore as distributedKVStore.SingleKVStore; 277 kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => { 278 if (err != undefined) { 279 console.error(`Failed to get data. Code:${err.code},message:${err.message}`); 280 return; 281 } 282 console.info(`Succeeded in getting data. Data:${data}`); 283 }); 284 }); 285 } catch (e) { 286 let error = e as BusinessError; 287 console.error(`Failed to get data. Code:${error.code},message:${error.message}`); 288 } 289 ``` 290 2918. 调用sync()方法同步数据到其他设备。 292 293 选择同一组网环境下的设备以及同步模式（需用户在应用首次启动的弹窗中确认选择同步模式），进行数据端端同步。 294 295 > **说明：** 296 > 297 > 在手动端端同步的方式下，其中的deviceIds通过调用[devManager.getAvailableDeviceListSync](../reference/apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 298 299 ```ts 300 import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 301 302 let devManager: distributedDeviceManager.DeviceManager; 303 try { 304 // create deviceManager 305 devManager = distributedDeviceManager.createDeviceManager(context.applicationInfo.name); 306 // deviceIds由deviceManager调用getAvailableDeviceListSync方法得到 307 let deviceIds: string[] = []; 308 if (devManager != null) { 309 let devices = devManager.getAvailableDeviceListSync(); 310 for (let i = 0; i < devices.length; i++) { 311 deviceIds[i] = devices[i].networkId as string; 312 } 313 } 314 try { 315 // 1000表示最大延迟时间为1000ms 316 kvStore.sync(deviceIds, distributedKVStore.SyncMode.PUSH_ONLY, 1000); 317 } catch (e) { 318 let error = e as BusinessError; 319 console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`); 320 } 321 322 } catch (err) { 323 let error = err as BusinessError; 324 console.error("createDeviceManager errCode:" + error.code + ",errMessage:" + error.message); 325 } 326 ``` 327 328## 相关实例 329 330针对键值型数据库开发，有以下相关实例可供参考： 331 332- [分布式组网认证（ArkTS）（Full SDK）（API10）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/DistributedAppDev/DistributedAuthentication) 333 334- [分布式数据管理（ArkTS）（Full SDK）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/Kvstore) 335 336- [分布式音乐播放（JS）（Full SDK）（API10）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/JsDistributedMusicPlayer) 337 338- [分布式音乐播放（ArkTS）（Full SDK）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/ArkTSDistributedMusicPlayer) 339 340- [分布式计算器（JS）（Full SDK）（API10）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/DistributeCalc) 341 342- [分布式计算器（ArkTS）（Full SDK）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SuperFeature/DistributedAppDev/ArkTSDistributedCalc) 343 344- [分布式五子棋（ArkTS）（Full SDK）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/Solutions/Game/DistributedDataGobang) 345 346- [分布式手写板（ArkTS）（Full SDK）（API10）](https://gitee.com/openharmony/codelabs/tree/master/Distributed/DistributeDraw)
