1# 通过DataShareExtensionAbility实现数据共享 (ArkTS)(仅对系统应用开放) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @woodenarow--> 5<!--Designer: @woodenarow; @xuelei3--> 6<!--Tester: @chenwan188; @logic42--> 7<!--Adviser: @ge-yafang--> 8 9 10## 场景介绍 11 12跨应用访问数据时，可以通过DataShareExtensionAbility拉起数据提供方的应用以实现对数据的访问。 13 14此种方式支持跨应用拉起数据提供方的DataShareExtension，数据提供方的开发者可以在回调中实现灵活的业务逻辑。用于跨应用复杂业务场景。 15 16 17## 运作机制 18 19数据共享可分为数据的提供方和访问方两部分。 20 21- 数据提供方：[DataShareExtensionAbility](../reference/apis-arkdata/js-apis-application-dataShareExtensionAbility-sys.md)，可以选择性实现数据的增、删、改、查，以及文件打开等功能，并对外共享这些数据。 22 23- 数据访问方：由[createDataShareHelper()](../reference/apis-arkdata/js-apis-data-dataShare-sys.md#datasharecreatedatasharehelper)方法所创建的工具类，利用工具类便可以访问提供方提供的这些数据。 24 25**图1** 数据共享运作机制 26 27 28- DataShareExtensionAbility模块为数据提供方，实现跨应用数据共享的相关业务。 29 30- DataShareHelper模块为数据访问方，提供各种访问数据的接口，包括增删改查等。 31 32- 数据访问方与提供方通过IPC进行通信，数据提供方可以通过数据库实现，也可以通过其他数据存储方式实现。 33 34- ResultSet模块通过共享内存实现，用于存储查询数据得到的结果集，并提供了遍历结果集的方法。 35 36## 实现说明 37 38 39### 数据提供方应用的开发（仅限系统应用） 40 41[DataShareExtensionAbility](../reference/apis-arkdata/js-apis-application-dataShareExtensionAbility-sys.md)提供以下API，根据需要重写对应回调方法。 42 43| 接口名称 | 描述 | 44| ---------------------------------------- | -------------------- | 45| onCreate(want: Want, callback: AsyncCallback<void>): void | DataShare客户端连接DataShareExtensionAbility服务端时，服务端需要在此回调中实现初始化业务逻辑，该方法可以选择性重写。 | 46| insert(uri: string, value: ValuesBucket, callback: AsyncCallback<number>): void | 客户端请求插入数据时回调此接口，服务端需要在此回调中实现插入数据功能，该方法可以选择性重写。 | 47| update(uri: string, predicates: dataSharePredicates.DataSharePredicates, value: ValuesBucket, callback: AsyncCallback<number>): void | 客户端请求更新数据时回调此接口，服务端需要在此回调中实现更新数据功能，该方法可以选择性重写。 | 48| batchUpdate(operations: Record<string, Array<UpdateOperation>>): Promise<Record<string, Array<number>>> | 客户端请求批量更新数据时回调此接口，服务端需要在此回调中实现批量更新数据功能，该方法可以选择性重写。 | 49| delete(uri: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>): void | 客户端请求删除数据时回调此接口，服务端需要在此回调中实现删除数据功能，该方法可以选择性重写。 | 50| query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<DataShareResultSet>): void | 客户端请求查询数据时回调此接口，服务端需要在此回调中实现查询数据功能，该方法可以选择性重写。 | 51| batchInsert(uri: string, values: Array<ValuesBucket>, callback: AsyncCallback<number>): void | 客户端请求批量插入数据时回调此接口，服务端需要在此回调中实现批量插入数据的功能，该方法可以选择性重写。 | 52| normalizeUri(uri: string, callback: AsyncCallback<string>): void | 客户端给定的URI转换为服务端使用的URI时回调此接口，该方法可以选择性重写。 | 53| denormalizeUri(uri: string, callback: AsyncCallback<string>): void | 服务端使用的URI转换为客户端传入的初始URI时服务端回调此接口，该方法可以选择性重写。 | 54 55开发者在实现一个数据共享服务时，需要在DevEco Studio工程中手动新建一个DataShareExtensionAbility，具体步骤如下。 56 571. 在工程Module对应的ets目录下，右键选择“New > Directory”，新建一个目录并命名为DataShareExtAbility。 58 592. 在DataShareExtAbility目录，右键选择“New > ArkTS File”，新建一个文件并命名为DataShareExtAbility.ets。 60 613. 在DataShareExtAbility.ets文件中，导入DataShareExtensionAbility模块，开发者可根据应用需求选择性重写其业务实现。例如数据提供方只提供插入、删除和查询服务，则可只重写这些接口，并导入对应的基础依赖模块；如果需要增加权限校验，可以在重写的回调方法中使用IPC提供的[getCallingPid](../reference/apis-ipc-kit/js-apis-rpc.md#getcallingpid)、[getCallingUid](../reference/apis-ipc-kit/js-apis-rpc.md#getcallinguid)、[getCallingTokenId](../reference/apis-ipc-kit/js-apis-rpc.md#getcallingtokenid8)方法获取访问者信息来进行权限校验。 62 63 ```ts 64 import { DataShareExtensionAbility, dataShare, dataSharePredicates, relationalStore, DataShareResultSet, ValuesBucket } from '@kit.ArkData'; 65 import { Want } from '@kit.AbilityKit'; 66 import { BusinessError } from '@kit.BasicServicesKit'; 67 ``` 68 694. 数据提供方的业务实现由开发者自定义。例如可以通过数据库、读写文件或访问网络等各方式实现数据提供方的数据存储。 70 71 ```ts 72 const DB_NAME = 'DB00.db'; 73 const TBL_NAME = 'TBL00'; 74 const DDL_TBL_CREATE = "CREATE TABLE IF NOT EXISTS " 75 + TBL_NAME 76 + ' (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, isStudent BOOLEAN, Binary BINARY)'; 77 78 let rdbStore: relationalStore.RdbStore; 79 let result: string; 80 81 export default class DataShareExtAbility extends DataShareExtensionAbility { 82 // 重写onCreate接口 83 onCreate(want: Want, callback: Function) { 84 result = this.context.cacheDir + '/datashare.txt'; 85 // 业务实现使用RDB 86 relationalStore.getRdbStore(this.context, { 87 name: DB_NAME, 88 securityLevel: relationalStore.SecurityLevel.S3 89 }, (err:BusinessError, data:relationalStore.RdbStore) => { 90 rdbStore = data; 91 rdbStore.executeSql(DDL_TBL_CREATE, [], (err) => { 92 if (err) { 93 console.error(`ExecuteSql failed, code is ${err.code}, message is ${err.message}`); 94 return; 95 } 96 console.info('DataShareExtAbility onCreate, executeSql done.'); 97 }); 98 if (callback) { 99 callback(); 100 } 101 }); 102 } 103 104 // 重写query接口 105 query(uri: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: Function) { 106 if (predicates === null || predicates === undefined) { 107 console.error('invalid predicates'); 108 return; 109 } 110 try { 111 rdbStore.query(TBL_NAME, predicates, columns, (err:BusinessError, resultSet:relationalStore.ResultSet) => { 112 if (resultSet !== undefined) { 113 console.info(`resultSet.rowCount:${resultSet.rowCount}`); 114 } 115 if (callback !== undefined) { 116 callback(err, resultSet); 117 } 118 }); 119 } catch (err) { 120 let code = (err as BusinessError).code; 121 let message = (err as BusinessError).message; 122 console.error(`Failed to query. Code:${code},message:${message}`); 123 } 124 } 125 // 重写batchUpdate接口 126 batchUpdate(operations:Record<string, Array<dataShare.UpdateOperation>>, callback:Function) { 127 let recordOps : Record<string, Array<dataShare.UpdateOperation>> = operations; 128 let results : Record<string, Array<number>> = {}; 129 let a = Object.entries(recordOps); 130 for (let i = 0; i < a.length; i++) { 131 let key = a[i][0]; 132 let values = a[i][1]; 133 let result : number[] = []; 134 for (const value of values) { 135 rdbStore.update(TBL_NAME, value.values, value.predicates).then(async (rows) => { 136 console.info('Update row count is ' + rows); 137 result.push(rows); 138 }).catch((err:BusinessError) => { 139 console.error('Update failed, err is ' + JSON.stringify(err)); 140 result.push(-1) 141 }) 142 } 143 results[key] = result; 144 } 145 callback(null, results); 146 } 147 148 batchInsert(uri: string, valueBuckets:Array<ValuesBucket>, callback:Function) { 149 if (valueBuckets == null || valueBuckets.length == undefined) { 150 console.error('invalid valueBuckets'); 151 return; 152 } 153 let resultNum = valueBuckets.length; 154 rdbStore.batchInsert(TBL_NAME, valueBuckets, (err, ret) => { 155 if (callback !== undefined) { 156 callback(err, ret); 157 } 158 }); 159 } 160 161 async normalizeUri(uri: string, callback:Function) { 162 let ret = "normalize+" + uri; 163 let err:BusinessError = { 164 message: "message", 165 code: 0, 166 name: 'name' 167 }; 168 await callback(err, ret); 169 } 170 171 async denormalizeUri(uri: string, callback:Function) { 172 let ret = "denormalize+" + uri; 173 174 let err:BusinessError = { 175 message: "message", 176 code: 0, 177 name: 'name' 178 }; 179 await callback(err, ret); 180 } 181 // 可根据应用需求，选择性重写各个接口 182 }; 183 ``` 184 1855. 在module.json5中定义DataShareExtensionAbility。 186 187 **表1** module.json5对应属性字段 188 189 | 属性名称 | 备注说明 | 必填 | 190 | -------- | -------- | -------- | 191 | name | Ability名称，对应Ability派生的ExtensionAbility类名。 | 是 | 192 | type | Ability类型，DataShare对应的Ability类型为“dataShare”，表示基于datashare模板开发的。 | 是 | 193 | uri | 通信使用的URI，是客户端链接服务端的唯一标识。 | 是 | 194 | exported | 对其他应用是否可见，设置为true时，才能与其他应用进行通信传输数据。 | 是 | 195 | readPermission | 访问数据时需要的权限，不配置默认不进行读权限校验。<br>注意：当前DataShareExtensionAbility的权限约束方式与静默访问的权限约束方式不同，请注意区分，切勿混淆，具体可参考[静默访问章节](share-data-by-silent-access.md)。 | 否 | 196 | writePermission | 修改数据时需要的权限，不配置默认不进行写权限校验。<br>注意：当前DataShareExtensionAbility的权限约束方式与静默访问的权限约束方式不同，请注意区分，切勿混淆，具体可参考[静默访问章节](share-data-by-silent-access.md)。 | 否 | 197 | metadata | 增加静默访问所需的额外配置项，包含name和resource字段。<br /> name类型固定为"ohos.extension.dataShare"，是配置的唯一标识。 <br /> resource类型固定为"$profile:data_share_config"，表示配置文件的名称为data_share_config.json。 | 若Ability启动模式为"singleton"，则metadata必填，Ability启动模式可见[abilities对象的内部结构-launchType](../quick-start/module-structure.md#abilities对象的内部结构)；其他情况下无需填写。 | 198 199 **module.json5配置样例：** 200 201 ```json 202 // 以下配置以settingsdata为例，应用需根据实际情况配置各个字段 203 "extensionAbilities": [ 204 { 205 "srcEntry": "./ets/DataAbility/DataExtAbility.ets", 206 "name": "DataExtAbility", 207 "icon": "$media:icon", 208 "description": "$string:description_datashareextability", 209 "type": "dataShare", 210 "uri": "datashare://com.ohos.settingsdata.DataAbility", 211 "exported": true, 212 // 实际请按照应用具体场景需要的安全权限配置，如配置应用自定义权限、系统权限或用户授权权限，当前权限仅为示例 213 "readPermission": "ohos.permission.MANAGE_SECURE_SETTINGS", 214 "writePermission": "ohos.permission.MANAGE_SECURE_SETTINGS", 215 "metadata": [{"name": "ohos.extension.dataShare", "resource": "$profile:data_share_config"}] 216 } 217 ] 218 ``` 219 220 **表2** data_share_config.json对应属性字段 221 222 | 属性名称 | 备注说明 | 必填 | 223 | ------------------- | ------------------------------------------------------------ | ---- | 224 | tableConfig | 配置标签。包括uri和crossUserMode。<br>**-uri：** 指定配置生效的范围，uri支持以下三种格式，优先级为**表配置>库配置>\***，如果同时配置，高优先级会覆盖低优先级 。<br /> 1. "*" : 所有的数据库和表。<br /> 2. "datashare:///{bundleName}/{moduleName}/{storeName}" : 指定数据库。<br /> 3. "datashare:///{bundleName}/{moduleName}/{storeName}/{tableName}" : 指定表<br>**-crossUserMode：** 标识数据是否为多用户共享，配置为1则多用户数据共享，配置为2则多用户数据隔离。 | 是 | 225 | isSilentProxyEnable | 标识该ExtensionAbility是否启用静默访问。<br />false：代表禁用静默访问。<br />true：代表打开静默访问。<br />不填写默认为true，即默认启用静默访问。<br />如果该应用下存在多个ExtensionAbility，其中一个配置了该属性为false，代表应用禁用静默访问。<br />如果数据提供方调用过enableSilentProxy和disableSilentProxy接口，则按照接口的设置结果来启用或禁用静默访问。否则会读取该配置来启用或禁用静默访问。 | 否 | 226 | launchInfos | 包括storeId和tableNames。<br>该配置中表粒度的数据变更时，通过所属extensionAbilities中的uri拉起extension。若业务方需要在非主动数据变更时做处理，则配置此项，拉起extension即时处理；若不需要，则可以不配置。<br>**-storeId：** 数据库名。该配置需要去掉数据库名后缀，如：数据库名为test.db时，配置信息填入test即可。<br>**-tableNames：** 数据库表名集合。集合内单个表数据变更就会拉起extension。 | 否 | 227 228 **data_share_config.json配置样例** 229 230 ```json 231 { 232 "tableConfig":[ 233 { 234 "uri":"*", 235 "crossUserMode":1 236 }, 237 { 238 "uri":"datashare:///com.ohos.settingsdata/entry/DB00", 239 "crossUserMode":1 240 }, 241 { 242 "uri":"datashare:///com.acts.datasharetest/entry/DB00/TBL00", 243 "crossUserMode":2 244 } 245 ], 246 "isSilentProxyEnable":true, 247 "launchInfos":[ 248 { 249 "storeId": "test", 250 "tableNames":["test1", "test2"] 251 } 252 ] 253 } 254 ``` 255 256 257### 数据访问方应用的开发 258 2591. 导入基础依赖包。 260 261 ```ts 262 import { UIAbility } from '@kit.AbilityKit'; 263 import { dataShare, dataSharePredicates, DataShareResultSet, ValuesBucket } from '@kit.ArkData'; 264 import { window } from '@kit.ArkUI'; 265 import { BusinessError } from '@kit.BasicServicesKit'; 266 ``` 267 2682. 定义与数据提供方通信的URI字符串。<br/> URI即为上文数据提供方在配置文件中配置的标识。URI支持添加后缀参数来设置具体的访问对象，URI添加后缀参数需在URI结尾以"?"符号开始参数。<br/> - 当前仅支持设置"user"参数。<br/> - "user"仅支持设置为整型，表示数据提供方的用户ID。不填写时，默认为数据访问方所在的用户ID。user的定义及获取参照[user](../reference/apis-basic-services-kit/js-apis-osAccount.md#getactivatedosaccountlocalids9)。<br/> - 目前跨用户访问需要数据访问方配有跨用户访问权限ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS才可成功访问。目前跨用户访问功能仅支持增删改查功能，订阅通知功能不支持跨用户。 269 270 ```ts 271 // 作为参数传递的URI，与module.json5中定义的URI的区别是多了一个"/"，是因为作为参数传递的URI中，在第二个与第三个"/"中间，存在一个DeviceID的参数 272 let dseUri = ('datashare:///com.ohos.settingsdata.DataAbility'); 273 ``` 274 2753. 使用createDataShareHelper()方法传入URI创建DataShareHelper对象。 276 277 ```ts 278 let dsHelper: dataShare.DataShareHelper | undefined = undefined; 279 let abilityContext: Context; 280 281 export default class EntryAbility extends UIAbility { 282 onWindowStageCreate(windowStage: window.WindowStage) { 283 abilityContext = this.context; 284 dataShare.createDataShareHelper(abilityContext, dseUri, (err, data) => { 285 dsHelper = data; 286 }); 287 } 288 } 289 ``` 290 2914. 获取到DataShareHelper对象后，便可利用其提供的接口访问提供方提供的服务，如使用insert()、delete()、update()或query()接口进行数据的增、删、改、查等。 292 293 ```ts 294 // 构建一条数据 295 let key1 = 'name'; 296 let key2 = 'age'; 297 let key3 = 'isStudent'; 298 let key4 = 'Binary'; 299 let valueName1 = 'ZhangSan'; 300 let valueName2 = 'LiSi'; 301 let valueAge1 = 21; 302 let valueAge2 = 18; 303 let valueIsStudent1 = false; 304 let valueIsStudent2 = true; 305 let valueBinary = new Uint8Array([1, 2, 3]); 306 let valuesBucket: ValuesBucket = { key1: valueName1, key2: valueAge1, key3: valueIsStudent1, key4: valueBinary }; 307 let updateBucket: ValuesBucket = { key1: valueName2, key2: valueAge2, key3: valueIsStudent2, key4: valueBinary }; 308 let predicates = new dataSharePredicates.DataSharePredicates(); 309 let valArray = ['*']; 310 311 let record: Record<string, Array<dataShare.UpdateOperation>> = {}; 312 let operations1: Array<dataShare.UpdateOperation> = []; 313 let operations2: Array<dataShare.UpdateOperation> = []; 314 let operation1: dataShare.UpdateOperation = { 315 values: valuesBucket, 316 predicates: predicates 317 }; 318 operations1.push(operation1); 319 let operation2: dataShare.UpdateOperation = { 320 values: updateBucket, 321 predicates: predicates 322 }; 323 operations2.push(operation2); 324 record["uri1"] = operations1; 325 record["uri2"] = operations2; 326 327 if (dsHelper != undefined) { 328 // 插入一条数据 329 (dsHelper as dataShare.DataShareHelper).insert(dseUri, valuesBucket, (err:BusinessError, data:number) => { 330 console.info(`dsHelper insert result:${data}`); 331 }); 332 // 更新数据 333 (dsHelper as dataShare.DataShareHelper).update(dseUri, predicates, updateBucket, (err:BusinessError, data:number) => { 334 console.info(`dsHelper update result:${data}`); 335 }); 336 // 查询数据 337 (dsHelper as dataShare.DataShareHelper).query(dseUri, predicates, valArray, (err:BusinessError, data:DataShareResultSet) => { 338 console.info(`dsHelper query result:${data}`); 339 }); 340 // 删除指定的数据 341 (dsHelper as dataShare.DataShareHelper).delete(dseUri, predicates, (err:BusinessError, data:number) => { 342 console.info(`dsHelper delete result:${data}`); 343 }); 344 // 批量更新数据 345 (dsHelper as dataShare.DataShareHelper).batchUpdate(record).then((data: Record<string, Array<number>>) => { 346 // 遍历data获取每条数据的更新结果， value为更新成功的数据记录数，若小于0，说明该次更新失败 347 let a = Object.entries(data); 348 for (let i = 0; i < a.length; i++) { 349 let key = a[i][0]; 350 let values = a[i][1]; 351 console.info(`Update uri:${key}`); 352 for (const value of values) { 353 console.info(`Update result:${value}`); 354 } 355 } 356 }); 357 // 关闭DataShareHelper实例 358 (dsHelper as dataShare.DataShareHelper).close(); 359 } 360 ``` 361 362## 相关实例 363 364针对数据共享开发，有以下相关实例可供参考： 365 366- [系统应用跨应用数据共享（ArkTS）（Full SDK）（API9）](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/SystemFeature/DataManagement/CrossAppDataShare)
