概念

场景介绍

跨设备数据同步功能（即分布式功能），指将数据同步到一个组网环境中的其他设备。常用于用户应用程序数据内容在可信认证的不同设备间，进行自由同步、修改和查询。

例如：当设备1上的应用A在分布式数据库中增、删、改数据后，设备2上的应用A也可以获取到该数据库变化。可在分布式图库、备忘录、联系人、文件管理器等场景中使用。

不同应用间订阅数据库变化通知，则请参考 跨应用数据共享 实现。

根据跨设备同步数据生命周期的不同，可以分为：

• 临时数据生命周期较短，通常保存到内存中。比如游戏应用产生的过程数据，建议使用分布式数据对象。
• 持久数据生命周期较长，需要保存到存储的数据库中，根据数据关系和特点，可以选择关系型数据库或者键值型数据库。比如图库应用的各种相册、封面、图片等属性信息，建议使用关系型数据库；图库应用的具体图片缩略图，建议使用键值型数据库。

基本概念

在分布式场景中，会涉及多个设备，组网内设备之间看到的数据是否一致称为分布式数据库的一致性。

分布式数据库一致性可以分为强一致性、弱一致性和最终一致性。

• 强一致性：是指某一设备成功增、删、改数据后，组网内任意设备可立即读取数据获得更新后的值。
• 弱一致性：是指某一设备成功增、删、改数据后，组网内设备可能读取到本次更新后的数据，也可能读取不到，不能保证在多长时间后每个设备的数据一定是一致的。
• 最终一致性：是指某一设备成功增、删、改数据后，组网内设备可能读取不到本次更新后的数据，但在某个时间窗口之后组网内设备的数据能够达到一致状态。

强一致性对分布式数据的管理要求非常高，在服务器的分布式场景可能会遇到。因为移动终端设备的不常在线、以及无中心的特性，所以同应用跨设备数据同步不支持强一致性，只支持最终一致性。

跨设备同步访问控制机制

数据跨设备同步时，数据管理基于设备等级和数据安全标签进行访问控制，具体可见跨设备同步访问控制机制。

键值型数据库跨设备数据同步

场景介绍

键值型数据库适合不涉及过多数据关系和业务关系的业务数据存储，比SQL数据库存储拥有更好的读写性能，同时因其在分布式场景中降低了解决数据库版本兼容问题的复杂度，和数据同步过程中冲突解决的复杂度而被广泛使用。

基本概念

在使用键值型数据库跨设备数据同步前，请先了解以下概念。

单版本数据库

单版本是指数据在本地是以单个条目为单位的方式保存，当数据在本地被用户修改时，不管它是否已经被同步出去，均直接在这个条目上进行修改。多个设备全局只保留一份数据，多个设备的相同记录（主码相同）会按时间最新保留一条记录，数据不分设备，设备之间修改相同的key会覆盖。同步也以此为基础，按照它在本地被写入或更改的顺序将当前最新一次修改逐条同步至远端设备，常用于联系人、天气等应用存储场景。

多设备协同数据库
多设备协同分布式数据库建立在单版本数据库之上，对应用程序存入的键值型数据中的Key前面拼接了本设备的DeviceID标识符，这样能保证每个设备产生的数据严格隔离。数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。

底层按照设备的维度管理这些数据，多设备协同数据库支持以设备的维度查询分布式数据，但是不支持修改远端设备同步过来的数据。需要分开查询各设备数据的可以使用设备协同版本数据库。常用于图库缩略图存储场景。

同步方式

数据管理服务提供了两种同步方式：手动同步和自动同步。键值型数据库可选择其中一种方式实现同应用跨设备数据同步。

手动同步
由应用程序调用sync接口来触发，需要指定同步的设备列表和同步模式。同步模式分为PULL_ONLY（将远端数据拉取到本端）、PUSH_ONLY（将本端数据推送到远端）和PUSH_PULL（将本端数据推送到远端同时也将远端数据拉取到本端）。 带有Query参数的同步接口 ，支持按条件过滤的方法进行同步，将符合条件的数据同步到远端。

自动同步
在跨设备Call调用实现的多端协同场景中，在应用程序更新数据后，由分布式数据库自动将本端数据推送到远端，同时也将远端数据拉取到本端来完成数据同步，应用不需要主动调用sync接口。

运作机制

底层通信组件完成设备发现和认证，会通知上层应用程序设备上线。收到设备上线的消息后数据管理服务可以在两个设备之间建立加密的数据传输通道，利用该通道在两个设备之间进行数据同步。

数据跨设备同步机制

如图所示，通过put、delete接口触发自动同步，将分布式数据通过通信适配层发送给对端设备，实现分布式数据的自动同步；

手动同步则是手动调用sync接口触发同步，将分布式数据通过通信适配层发送给对端设备。

数据变化通知机制

增、删、改数据库时，会给订阅者发送数据变化的通知。主要分为本地数据变化通知和分布式数据变化通知。

• 本地数据变化通知：本地设备的应用内订阅数据变化通知，数据库增删改数据时，会收到通知。
• 分布式数据变化通知：同一应用订阅组网内其他设备数据变化的通知，其他设备增删改数据时，本设备会收到通知。

约束限制

• 设备协同数据库，针对每条记录，Key的长度≤896 Byte，Value的长度<4 MB。
• 单版本数据库，针对每条记录，Key的长度≤1 KB，Value的长度<4 MB。
• 键值型数据库不支持应用程序自定义冲突解决策略。
• 每个应用程序最多支持同时打开16个键值型分布式数据库。
• 单个数据库最多支持注册8个订阅数据变化的回调。

接口说明

以下是单版本键值型分布式数据库跨设备数据同步功能的相关接口，大部分为异步接口。异步接口均有callback和Promise两种返回形式，下表均以callback形式为例，更多接口及使用方式请见分布式键值数据库。

开发步骤

此处以单版本键值型数据库跨设备数据同步的开发为例。以下是具体的开发流程和开发步骤。

说明
数据只允许向数据安全标签不高于对端设备安全等级的设备同步数据，具体规则可见跨设备同步访问控制机制。

1. 导入模块。

import { distributedKVStore } from '@kit.ArkData';

2. 请求权限。

• 需要申请ohos.permission.DISTRIBUTED_DATASYNC权限，配置方式请参见 声明权限 。
• 同时需要在应用首次启动时弹窗向用户申请授权，使用方式请参见 向用户申请授权 。

3. 根据配置构造分布式数据库管理类实例。

• 根据应用上下文创建kvManagerConfig对象。
• 创建分布式数据库管理器实例。

// Stage模型获取context
import { window } from '@kit.ArkUI';
import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let kvManager: distributedKVStore.KVManager | undefined = undefined;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage:window.WindowStage) {
    let context = this.context;
  }
}
 
 // FA模型获取context
import { featureAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
 
let context = featureAbility.getContext();

// 获取context之后，构造分布式数据库管理类实例
try {
  const kvManagerConfig: distributedKVStore.KVManagerConfig = {
    bundleName: 'com.example.datamanagertest',
    context: context
  }
  kvManager = distributedKVStore.createKVManager(kvManagerConfig);
  console.info('Succeeded in creating KVManager.');
  // 继续创建获取数据库
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
}

if (kvManager !== undefined) {
  kvManager = kvManager as distributedKVStore.KVManager;
  // 进行后续创建数据库等相关操作
  // ...
}

4. 获取并得到指定类型的键值型数据库。

• 声明需要创建的分布式数据库ID描述（例如示例代码中的’storeId’）。
• 创建分布式数据库，建议关闭自动同步功能（autoSync:false），方便后续对同步功能进行验证，需要同步时主动调用sync接口。

let kvStore: distributedKVStore.SingleKVStore | undefined = undefined;
try {
  let child1 = new distributedKVStore.FieldNode('id');
  child1.type = distributedKVStore.ValueType.INTEGER;
  child1.nullable = false;
  child1.default = '1';
  let child2 = new distributedKVStore.FieldNode('name');
  child2.type = distributedKVStore.ValueType.STRING;
  child2.nullable = false;
  child2.default = 'zhangsan';

  let schema = new distributedKVStore.Schema();
  schema.root.appendChild(child1);
  schema.root.appendChild(child2);
  schema.indexes = ['$.id', '$.name'];
  // 0表示COMPATIBLE模式，1表示STRICT模式。
  schema.mode = 1;
  // 支持在检查Value时，跳过skip指定的字节数，且取值范围为[0,4M-2]。
  schema.skip = 0;

  const options: distributedKVStore.Options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: false,
    // kvStoreType不填时，默认创建多设备协同数据库
    // 多设备协同数据库：kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    // schema 可以不填，在需要使用schema功能时可以构造此参数，例如：使用谓词查询等。
    schema: schema,
    securityLevel: distributedKVStore.SecurityLevel.S1
  };
  kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => {
    if (err) {
      console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in getting KVStore.');
    kvStore = store;
    // 请确保获取到键值数据库实例后，再进行相关数据操作
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}
if (kvStore !== undefined) {
  kvStore = kvStore as distributedKVStore.SingleKVStore;
    // 进行后续相关数据操作，包括数据的增、删、改、查、订阅数据变化等操作
    // ...
}

5. 订阅分布式数据变化，如需关闭订阅分布式数据变化，调用 off(‘dataChange’) 关闭。

try {
  kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data) => {
    console.info(`dataChange callback call data: ${data}`);
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. code:${error.code},message:${error.message}`);
}

6. 将数据写入分布式数据库。

• 构造需要写入分布式数据库的Key（键）和Value（值）。
• 将键值数据写入分布式数据库。

const KEY_TEST_STRING_ELEMENT = 'key_test_string';
// 如果未定义Schema则Value可以传其他符合要求的值。
const VALUE_TEST_STRING_ELEMENT = '{"id":0, "name":"lisi"}';
try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
}

7. 查询分布式数据库数据。

• 构造需要从单版本分布式数据库中查询的Key（键）。
• 从单版本分布式数据库中获取数据。

try {
  kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
    if (err !== undefined) {
      console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
      return;
    }
    console.info('Succeeded in putting data.');
    kvStore = kvStore as distributedKVStore.SingleKVStore;
    kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => {
      if (err != undefined) {
        console.error(`Failed to get data. Code:${err.code},message:${err.message}`);
        return;
      }
      console.info(`Succeeded in getting data. Data:${data}`);
    });
  });
} catch (e) {
  let error = e as BusinessError;
  console.error(`Failed to get data. Code:${error.code},message:${error.message}`);
}

8. 同步数据到其他设备。
选择同一组网环境下的设备以及同步模式（需用户在应用首次启动的弹窗中确认选择同步模式），进行数据同步。
 

说明
在手动同步的方式下，其中的deviceIds通过调用 devManager.getAvailableDeviceListSync 方法得到。

import { distributedDeviceManager } from '@kit.DistributedServiceKit';
 
let devManager: distributedDeviceManager.DeviceManager;
try {
  // create deviceManager
  devManager = distributedDeviceManager.createDeviceManager(context.applicationInfo.name);
  // deviceIds由deviceManager调用getAvailableDeviceListSync方法得到
  let deviceIds: string[] = [];
  if (devManager != null) {
    let devices = devManager.getAvailableDeviceListSync();
    for (let i = 0; i < devices.length; i++) {
      deviceIds[i] = devices[i].networkId as string;
    }
  }
  try {
    // 1000表示最大延迟时间为1000ms
    kvStore.sync(deviceIds, distributedKVStore.SyncMode.PUSH_ONLY, 1000);
  } catch (e) {
    let error = e as BusinessError;
    console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
  }

} catch (err) {
  let error = err as BusinessError;
  console.error("createDeviceManager errCode:" + error.code + ",errMessage:" + error.message);
}