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