OpenHarmony应用开发-DataAbility组件开发指导

素年锦时静待君丶
发布于 2023-4-10 17:36
浏览
0收藏

版本:v3.2 Beta5

DataAbility组件概述

DataAbility,即"使用Data模板的Ability",主要用于对外部提供统一的数据访问抽象,不提供用户交互界面。DataAbility可由PageAbility、ServiceAbility或其他应用启动,即使用户切换到其他应用,DataAbility仍将在后台继续运行。

使用DataAbility有助于应用管理其自身和其他应用存储数据的访问,并提供与其他应用共享数据的方法。DataAbility既可用于同设备不同应用的数据共享,也支持跨设备不同应用的数据共享。

数据的存放形式多样,可以是数据库,也可以是磁盘上的文件。DataAbility对外提供对数据的增、删、改、查,以及打开文件等接口,这些接口的具体实现由开发者提供。

相关实例

基于DataAbility组件的开发,以下相关实例可供参考:

DataAbility组件配置

URI介绍

DataAbility的提供方和使用方都通过URI(Uniform Resource Identifier)来标识一个具体的数据,例如数据库中的某个表或磁盘上的某个文件。OpenHarmony的URI仍基于URI通用标准,格式如下:

OpenHarmony应用开发-DataAbility组件开发指导-鸿蒙开发者社区

  • scheme:协议方案名,固定为"dataability",代表Data Ability所使用的协议类型。
  • authority:设备ID。如果为跨设备场景,则为目标设备的ID;如果为本地设备场景,则不需要填写。
  • path:资源的路径信息,代表特定资源的位置信息。
  • query:查询参数。
  • fragment:可以用于指示要访问的子资源。

URI示例:

  • 跨设备场景:dataability://device_id/com.domainname.dataability.persondata/person/10
  • 本地设备:dataability:///com.domainname.dataability.persondata/person/1

 说明: 本地设备的"device_id"字段为空,因此在"dataability:“后面有三个”/"。

部分配置项介绍

与PageAbility类似,DataAbility的相关配置在config.json配置文件的"module"对象的"abilities"对象中,与PageAbility的区别在于"type"属性及"uri"属性。

表1 DataAbility的部分配置项说明

Json重要字段

备注说明

“name”

Ability名称。

“type”

UIAbility类型,DataAbility的类型为"data"。

“uri”

通信使用的URI。

“visible”

对其他应用是否可见,设置为true时,DataAbility才能与其他应用进行通信传输数据。

config.json配置样例

"abilities": [{
  "srcPath": "DataAbility",
  "name": ".DataAbility",
  "icon": "$media:icon",
  "srcLanguage": "ets",
  "description": "$string:description_dataability",
  "type": "data",
  "visible": true,
  "uri": "dataability://ohos.samples.etsdataability.DataAbility"
}]

DataAbility支持的配置项及详细说明详见​​module对象内部结构​​。

DataAbility的生命周期

应用开发者可以根据业务场景重写生命周期相关接口。DataAbility生命周期接口说明见下表。

表1 DataAbility相关生命周期API功能介绍

接口名

描述

onInitialized?(info: AbilityInfo): void

在Ability初始化调用,通过此回调方法执行RDB等初始化操作。

update?(uri: string, valueBucket: rdb.ValuesBucket, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void

更新数据库中的数据。

query?(uri: string, columns: Array<string>, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<ResultSet>): void

查询数据库中的数据。

delete?(uri: string, predicates: dataAbility.DataAbilityPredicates, callback: AsyncCallback<number>): void

删除一条或多条数据。

normalizeUri?(uri: string, callback: AsyncCallback<string>): void

对URI进行规范化。一个规范化的URI可以支持跨设备使用、持久化、备份和还原等,当上下文改变时仍然可以引用到相同的数据项。

batchInsert?(uri: string, valueBuckets: Array<rdb.ValuesBucket>, callback: AsyncCallback<number>): void

向数据库中插入多条数据。

denormalizeUri?(uri: string, callback: AsyncCallback<string>): void

将一个由normalizeUri生产的规范化URI转换成非规范化的URI。

insert?(uri: string, valueBucket: rdb.ValuesBucket, callback: AsyncCallback<number>): void

向数据中插入一条数据。

openFile?(uri: string, mode: string, callback: AsyncCallback<number>): void

打开一个文件。

getFileTypes?(uri: string, mimeTypeFilter: string, callback: AsyncCallback<Array<string>>): void

获取文件的MIME类型。

getType?(uri: string, callback: AsyncCallback<string>): void

获取URI指定数据相匹配的MIME类型。

executeBatch?(ops: Array<DataAbilityOperation>, callback: AsyncCallback<Array<DataAbilityResult>>): void

批量操作数据库中的数据。

call?(method: string, arg: string, extras: PacMap, callback: AsyncCallback<PacMap>): void

自定义方法。

创建DataAbility

实现DataAbility中Insert、Query、Update、Delete接口的业务内容。保证能够满足数据库存储业务的基本需求。BatchInsert与ExecuteBatch接口已经在系统中实现遍历逻辑,依赖Insert、Query、Update、Delete接口逻辑,来实现数据的批量处理。

创建DataAbility的代码示例如下:

import featureAbility from '@ohos.ability.featureAbility'
import dataAbility from '@ohos.data.dataAbility'
import dataRdb from '@ohos.data.rdb'

const TABLE_NAME = 'book'
const STORE_CONFIG = { name: 'book.db' }
const SQL_CREATE_TABLE = 'CREATE TABLE IF NOT EXISTS book(id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, introduction TEXT NOT NULL)'
let rdbStore: dataRdb.RdbStore = undefined

export default {
  onInitialized(abilityInfo) {
    console.info('DataAbility onInitialized, abilityInfo:' + abilityInfo.bundleName)
    let context = featureAbility.getContext()
    dataRdb.getRdbStore(context, STORE_CONFIG, 1, (err, store) => {
      console.info('DataAbility getRdbStore callback')
      store.executeSql(SQL_CREATE_TABLE, [])
      rdbStore = store
    });
  },
  insert(uri, valueBucket, callback) {
    console.info('DataAbility insert start')
    rdbStore.insert(TABLE_NAME, valueBucket, callback)
  },
  batchInsert(uri, valueBuckets, callback) {
    console.info('DataAbility batch insert start')
    for (let i = 0;i < valueBuckets.length; i++) {
      console.info('DataAbility batch insert i=' + i)
      if (i < valueBuckets.length - 1) {
        rdbStore.insert(TABLE_NAME, valueBuckets[i], (err: any, num: number) => {
          console.info('DataAbility batch insert ret=' + num)
        })
      } else {
        rdbStore.insert(TABLE_NAME, valueBuckets[i], callback)
      }
    }
  },
  query(uri, columns, predicates, callback) {
    console.info('DataAbility query start')
    let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
    rdbStore.query(rdbPredicates, columns, callback)
  },
  update(uri, valueBucket, predicates, callback) {
    console.info('DataAbilityupdate start')
    let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
    rdbStore.update(valueBucket, rdbPredicates, callback)
  },
  delete(uri, predicates, callback) {
    console.info('DataAbilitydelete start')
    let rdbPredicates = dataAbility.createRdbPredicates(TABLE_NAME, predicates)
    rdbStore.delete(rdbPredicates, callback)
  }
};

启动DataAbility

启动DataAbility会获取一个工具接口类对象(DataAbilityHelper)。启动DataAbility的示例代码如下:

// 作为参数传递的URI,与config中定义的URI的区别是多了一个"/",有三个"/",具体原因详见。
import featureAbility from '@ohos.ability.featureAbility'

let urivar = "dataability:///com.ix.DataAbility"
let DAHelper = featureAbility.acquireDataAbilityHelper(urivar);

访问DataAbility

访问DataAbility需导入基础依赖包,以及获取与DataAbility子模块通信的URI字符串。

其中,基础依赖包包括:

  • @ohos.ability.featureAbility
  • @ohos.data.dataAbility
  • @ohos.data.rdb

访问DataAbility的示例代码如下:

  1. 创建工具接口类对象。

// 作为参数传递的URI,与config中定义的URI的区别是多了一个"/",有三个"/"
import featureAbility from '@ohos.ability.featureAbility'
import ohos_data_ability from '@ohos.data.dataAbility'
import ohos_data_rdb from '@ohos.data.rdb'

let urivar = "dataability:///com.ix.DataAbility"
let DAHelper = featureAbility.acquireDataAbilityHelper(urivar);
  1. 构建数据库相关的RDB数据。

let valuesBucket = {"name": "gaolu"}
let da = new ohos_data_ability.DataAbilityPredicates()
let valArray =new Array("value1");
let cars = new Array({"batchInsert1" : "value1",});

注:关于DataAbilityPredicates的详细内容,请参考​​DataAbility谓词​​。

  1. 调用insert方法向指定的DataAbility子模块插入数据。

// callback方式调用:
DAHelper.insert(
  urivar,
  valuesBucket,
  (error, data) => {
    console.info("DAHelper insert result: " + data)
  }
);

// promise方式调用(await需要在async方法中使用):
let datainsert = await DAHelper.insert(urivar, valuesBucket).then((data) => {
  console.info("insert success.");
}).catch((error) => {
  console.error("insert failed.");
});
  1. 调用delete方法删除DataAbility子模块中指定的数据。

// callback方式调用:
DAHelper.delete(
  urivar,
  da,
  (error, data) => {
    console.info("DAHelper delete result: " + data)
  }
);

// promise方式调用(await需要在async方法中使用):
let datadelete = await DAHelper.delete(
  urivar,
  da,
);
  1. 调用update方法更新指定DataAbility子模块中的数据。

// callback方式调用:
DAHelper.update(
  urivar,
  valuesBucket,
  da,
  (error, data) => {
    console.info("DAHelper update result: " + data)
  }
);

// promise方式调用(await需要在async方法中使用):
let dataupdate = await DAHelper.update(
  urivar,
  valuesBucket,
  da,
);
  1. 调用query方法在指定的DataAbility子模块中查找数据。

// callback方式调用:
DAHelper.query(
  urivar,
  valArray,
  da,
  (error, data) => {
    console.info("DAHelper query result: " + data)
  }
);

// promise方式调用(await需要在async方法中使用):
let dataquery = await DAHelper.query(
  urivar,
  valArray,
  da
);
  1. 调用batchInsert方法向指定的DataAbility子模块批量插入数据。

// callback方式调用:
DAHelper.batchInsert(
  urivar,
  cars,
  (error, data) => {
    console.info("DAHelper batchInsert result: " + data)
  }
);

// promise方式调用(await需要在async方法中使用):
let databatchInsert = await DAHelper.batchInsert(
  urivar,
  cars
);
  1. 调用executeBatch方法向指定的DataAbility子模块进行数据的批量处理。

// callback方式调用:
DAHelper.executeBatch(
  urivar,
  [
    {
      uri: urivar,
      type: featureAbility.DataAbilityOperationType.TYPE_INSERT,
      valuesBucket: {"executeBatch" : "value1",},
      predicates: da,
      expectedCount:0,
      predicatesBackReferences: null,
      interrupted:true,
    }
  ],
  (error, data) => {
    console.info("DAHelper executeBatch result: " + data)
  }
);

// promise方式调用(await需要在async方法中使用):
let dataexecuteBatch = await DAHelper.executeBatch(
  urivar,
  [
    {
      uri: urivar,
      type: featureAbility.DataAbilityOperationType.TYPE_INSERT,
      valuesBucket:
      {
        "executeBatch" : "value1",
      },
      predicates: da,
      expectedCount:0,
      predicatesBackReferences: null,
      interrupted:true,
    }
  ]
);

DataAbility的客户端的接口是由工具接口类对象DataAbilityHelper向外提供,相关接口可参考​​DataAbilityHelper模块​​。

DataAbility权限控制

DataAbility提供数据服务,并不是所有的Ability都有权限读写它,DataAbility有一套权限控制机制来保证数据安全。分为静态权限控制和动态权限控制两部分。

静态权限控制

DataAbility作为服务端,在被拉起的时候,会根据config.json里面配置的权限来进行校验,有"readPermission"、"writePermission"和"Permission"三个配置项,可以不配或者为空。示例如下:

"abilities": [{
  "srcPath": "DataAbility",
  "name": ".DataAbility",
  "icon": "$media:icon",
  "srcLanguage": "ets",
  "description": "$string:description_dataability",
  "type": "data",
  "visible": true,
  "uri": "dataability://ohos.samples.etsdataability.DataAbility",
  "readPermission":"ohos.permission.READ_CONTACTS",
  "writePermission":"ohos.permission.WRITE_CONTACTS"
}]

客户端在拉起DataAbility的时候,需要校验客户端是否有权限拉起该DataAbility。客户端的权限配置在config.json配置文件的"module"对象的"reqPermissions"对象中,示例如下:

{
  "module": {
    "reqPermissions":{
      {
        "name":"ohos.permission.READ_CONTACTS"
      },
      {
        "name":"ohos.permission.WRITE_CONTACTS"
      }
    }
  }
}

动态权限控制

静态权限校验只能控制某个DataAbility是否能被另一个Ability或应用拉起,无法精确校验每个读写接口的权限,因为拉起DataAbility的时候,还不知道应用是否需要读写它的数据。

动态权限控制是校验每个数据操作的接口是否有对应的权限。客户端调用数据操作接口所需的权限如下表所示。

表1 接口对应的读写权限配置

需要配置读权限的接口

需要配置写权限的接口

据实际操作配置读写权限的接口

query、normalizeUri、denormalizeUri、openfile(传入mode有’r’)

insert、batchInsert、delete、update、openfile(传入mode有’w’)

executeBatch

对于需要配置读权限的接口,服务端需要配置readPermission,客户端必须申请相应的读权限才能调用相关的接口。

对于需要配置写权限的接口,服务端需要配置writePermission,客户端必须申请相应的写权限才能调用相关的接口。




文章转载自:​​https://docs.openharmony.cn/pages/v3.2Beta/zh-cn/application-dev/application-models/dataability-permission-control.md/​

已于2023-4-10 17:36:04修改
收藏
回复
举报
回复
    相关推荐