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