HarmonyOS Next 端云一体化（2）
本章节主要讲一下端云一体化中的数据库操作
介绍
云数据库是端云协同的数据库产品，具备端云数据协同管理、统一数据模型及丰富数据管理 API 接口等能力。它采用基于对象模型 的
数据存储结构，数据以对象（Object） 形式存于不同存储区，每个对象为一条完整数据记录。 对象类型（ObjectType） 定义存储对
象集合，不同对象类型对应不同数据结构。存储区（Zone） 是独立的数据存储区域，每个存储区的对象类型定义完全相同。
学习流程
我们会按照以下流程来进行学习。
- 新建存储区：也就是新建数据库
- 创建对象类型：创建一个用于存储数据条目的对象类型。
- 添加数据条目：在刚刚创建的对象类型内添加一条条数据，并配置数据所在的存储区。
- 部署云数据库：数据成功添加后，您可以直接将该数据部署至 AGC 云端。您也可以等所有对象类型和数据条目开发完成后，再统一批量部署到 AGC 云端。
存储区
我们这里新建一个存储区 Study 用来存放稍后用到的数据。
然后我们在 DevEco Studio 的 云端配置中指定存储区。
clouddb/db-config.json
{
"defaultCloudDBZoneName": "Study", // 存储区的名称
"defaultDataStorageLocation": "CN"
}
AI 代码解读
创建对象类型
什么是创建对象类型
创建对象类型可以理解为就是为我们的数据定义类型。类似于使用接口或者 class 来定义数据，但是这里操作的范围要更大。
- 定义基本的数据类型，如数字、字符串、布尔、日期时间等。
- 定义字段的权限，因为这个对象类型本身是数据表，定义权限相当于设置了哪一类用户拥有哪些权限。如读取、编辑、新增、删除等
- 定义索引，考虑数据量大需要比较方便的查找到要操作的数据，需要定义索引。
比如，我们需要根据书籍数据来定义类型。 Book
| 字段 | 类型 | 说明 |
|---|---|---|
| id | number | id |
| name | string | 书名 |
| price | number | 价格 |
| publish | date | 出版日期 |
| hot | boolean | 是否热门 |
| cover | string | 封面 |
对象类型的规范
新建 Book 对象类型文件
这个对文件需要按照以下格式来编写。其中的字段的一些规范需要特别注意。
{
"objectTypeName": 对象实体名称
"fields": 对象中的属性
"indexes": 索引
"permissions" 权限
}
AI 代码解读
objectTypeName
表示实体对象的名称，我们这里可以是 Book
{
"objectTypeName": "Book"
}
AI 代码解读
fields
fields 表示这个对象中属性的一些规则。
| 参数 | 必选(M)/可选(O) | 说明 |
|---|---|---|
| fieldName | M | 字段名称。输入要求具体如下：字段的名称长度必须大于或等于 1 个字符，小于或等于 30 个字符，只能包含以下 3 种类型，并且至少包含“字母”类型：字母（A-Z 或 a-z）数字（0-9）特殊字符：_字段名称必须以字母开头，以字母或者数字结尾。字段名称中不区分字母的大小写。修改对象类型时，支持删除字段。字段名称不允许使用系统保留字段名称： naturalbase_version、naturalbase_deleted、naturalbase_operationtype、naturalbase_creator、naturalbase_accesstime、naturalbase_operationtime、naturalbase_syncstatus、naturalbase_changedfieldsbitmap、naturalbase_lastmodifier、cmin、cmax、xmin、xmax、ctid、oid、tableoid、xc_node_id、tablebucketid、rowid。说明当前 Cloud Foundation Kit 暂不支持自增类型字段 IntAutoIncrement 或 LongAutoIncrement。 |
| fieldType | M | 字段的数据类型。当前支持的数据类型：String、Boolean、Byte、Short、Integer、Long、Float、Double、ByteArray、Text、Date、IntAutoIncrement（数字-自增） |
| belongPrimaryKey | O | 设置该字段是否为对象类型的主键，默认值为 false。至少设置一个字段为主键。支持设置复合主键，由多个字段组合成为主键，一个复合主键包含的字段小于等于 5 个，复合主键字段顺序与字段的顺序一致。数据类型为 ByteArray、Text、Date、Double、Float 和 Boolean 的字段不支持设置为主键。主键的值不允许更改。 |
| notNull | O | 设置字段值是否为非空，默认值为 false。数据类型为 ByteArray 和 Date 的字段不支持设置为非空。主键默认非空，且不允许更改。设置为非空的字段不支持加密和敏感。 |
| isNeedEncrypt | O | 设置字段是否需要加密，开启全程加密数据管理功能，默认值为 false。选择加密后，该字段对应的数据会加密存储在存储区中。主键字段不支持加密。加密的字段不支持设置为非空。加密的字段不支持设置为敏感字段。一个对象类型中包含的加密字段和敏感字段的总数需小于或等于 5 个。字段设置为加密后，不支持导出该字段的数据值。数据类型为 ByteArray、Text 的字段不支持加密。对象类型创建成功后，不支持修改加密属性。 |
| isSensitive | O | 设置字段是否为敏感字段，默认值为 false。选择敏感后，该字段对应的数据会加密存储在存储区中。敏感字段不支持设置为主键。敏感字段不支持设置为非空。敏感字段不支持设置为加密。敏感字段不支持设置为默认值。对象类型创建成功后，不支持修改敏感属性。仅支持数据类型为 Byte、Short、Integer、Long、Float、Double、String 和 Date 的字段设置为敏感字段。敏感字段不支持设置为索引。一个对象类型中包含的加密字段和敏感字段的总数需小于或等于 5 个。 |
| defaultValue | O | 字段为非空时，必须设置默认值。主键不支持设置默认值。加密字段和敏感字段不支持设置默认值。数据类型为 ByteArray、Date 不支持为其设置默认值。数据类型为 Text 的字段设置默认值时，默认值的长度小于或等于 200 个字符。 |
按照我们想要的书籍的规定。可以这样
| fieldName | fieldType | belongPrimaryKey |
|---|---|---|
| id | IntAutoIncrement | true |
| name | String | - |
| price | Double | - |
| publish | Date | - |
| hot | Boolean | - |
| cover | String | - |
{
"objectTypeName": "Book",
"fields": [
{
"fieldName": "id",
"fieldType": "IntAutoIncrement",
"belongPrimaryKey": true,
"notNull": true
},
{
"fieldName": "name",
"fieldType": "String"
},
{
"fieldName": "price",
"fieldType": "Double"
},
{
"fieldName": "publish",
"fieldType": "Date"
},
{
"fieldName": "hot",
"fieldType": "Boolean"
},
{
"fieldName": "cover",
"fieldType": "String"
}
]
}
AI 代码解读
indexes
在indexes中为该对象类型配置索引、索引包含的字段、以及索引包含的字段的排序方式。
| 参数 | 必选(M)/可选(O) | 说明 |
|---|---|---|
| indexName | M | 索引名称。输入要求具体如下：索引的名称长度必须大于或等于 1 个字符，小于或等于 30 个字符，只能包含以下 3 种类型，并且至少包含“字母”类型：字母（A-Z 或 a-z）数字（0-9）特殊字符：_索引名称必须以字母开头。索引名称中不区分字母的大小写。修改对象类型时，仅支持新增或者删除索引。当删除索引后，本次提交前不允许新增同名索引。每个对象类型可以设置小于或等于 16 个索引。数据类型为 ByteArray 和 Text 的字段不支持设置为索引。 |
| indexList > fieldName | M | 索引包含的字段。支持设置组合索引，由多个字段组合成为索引，一个组合索引包含的字段不超过 5 个。 |
| indexList > sortType | M | 索引包含的字段的排序方式，支持 ASC 升序或 DESC 降序。 |
这里我们为书籍的 id 和书籍的名称提供索引。
{
"indexes": [
{
"indexName": "id_Index",
"indexList": [
{
"fieldName": "id",
"sortType": "ASC"
}
]
},
{
"indexName": "price_Index",
"indexList": [
{
"fieldName": "price",
"sortType": "DESC"
}
]
}
]
}
AI 代码解读
permissions
permissions 字段用来设置该数据表的操作权限的。
目前提供的角色和权限有以下分类。
| 参数 | 必选(M)/可选(O) | 说明 |
|---|---|---|
| role | M | 用户角色，包括：World：代表所有用户，包含认证和非认证用户。该角色默认拥有 Read 权限，可自定义配置 Upsert 和 Delete 权限。但是，不建议将 Upsert 和 Delete 权限配置给所有人角色。当对象类型中设置了加密字段之后，表示开启全程加密功能，此时所有人角色将不会拥有 Read、Upsert 和 Delete 权限，且不允许修改。Authenticated：经过 AGC 登录认证的用户。该角色默认拥有 Read 权限，可自定义配置 Upsert 和 Delete 权限。当对象类型中设置了加密字段之后，表示开启全程加密功能，此时认证用户角色将不会拥有 Read、Upsert 和 Delete 权限，且不允许修改。Creator：经过认证的数据创建用户。该角色默认拥有所有权限，且可自定义配置所有权限。每条数据都有其对应的数据创建人（即应用用户），每个数据创建者仅可以 Upsert 或者 Delete 自己创建的数据，不能 Upsert 或者 Delete 他人创建的数据。数据创建者的信息保存在数据记录的系统表中。Administrator：应用开发者，主要是指通过 AGC 控制台或 FaaS（Function as a Service，函数即服务）侧访问云数据库的角色。该角色默认拥有所有权限，且可自定义配置所有权限。Administrator 可以管理并配置其他角色的权限。 |
| rights | M | 授予角色的权限，包括 Read、Upsert（包含新增和修改）和 Delete 权限。 |
接下来，我们为 这些角色设置以下的权限。
| 角色 | Read | Upsert | Delete |
|---|---|---|---|
| World | √ | – | – |
| Authenticated | √ | √ | – |
| Creator | √ | √ | √ |
| Administrator | √ | √ | √ |
代码如下：
{
"permissions": [
{
"role": "World",
"rights": ["Read"]
},
{
"role": "Authenticated",
"rights": ["Read", "Upsert"]
},
{
"role": "Creator",
"rights": ["Read", "Upsert", "Delete"]
},
{
"role": "Administrator",
"rights": ["Read", "Upsert", "Delete"]
}
]
}
AI 代码解读
创建数据条目
我们搭建好了对象类型，现在可以根据它来插入数据了。
新建数据文件
插入数据 这里可以看到一些基本数据
{ "cloudDBZoneName": "Study", "objectTypeName": "Book", "objects": [ { "id": 1, "name": "string1", "price": 10.5, "publish": 1737014949576, "hot": true, "cover": "string1" }, { "id": 2, "name": "string2", "price": 20.5, "publish": 1737014949576, "hot": false, "cover": "string2" } ] }AI 代码解读字段解释
- cloudDBZoneName：配置存储区名称。
- objects：配置当前对象类型中所有字段的值，即写入数据。一个对象（object）即为一条数据，您可以通过新建一个对象（object）来为字段赋新值，也可以修改某个对象（object）下字段的值（主键或加密字段的值不支持修改）
部署云数据库
刚才我们都是在本地搭建的数据库，现在我们需要将这些数据同步到 AGC 平台的数据库上。
部署的方式也很简单
- 部署
- 成本
刷新 AGC 平台上的数据库
总结
本文详细介绍了 HarmonyOS 云数据库的基本操作流程：
存储区（Zone）创建
- 创建名为 Study 的存储区
- 在 DevEco Studio 中配置存储区信息
对象类型（ObjectType）定义
- 详细讲解了对象类型的规范和组成部分
- 包含 objectTypeName、fields、indexes 和 permissions 四个主要部分
- 以 Book 对象为例，展示了完整的对象类型定义过程
数据操作
- 创建数据条目的具体步骤
- 展示了如何在 JSON 文件中定义数据内容
- 说明了 cloudDBZoneName 和 objects 的配置方法
云端部署
- 介绍了如何将本地数据库部署到 AGC 平台
- 展示了部署过程和成本预估
- 说明了如何在 AGC 平台上刷新数据库
通过这些步骤，我们完成了一个基本的云数据库的创建、配置和部署过程，为后续的端云协同开发打下了基础。
如果你兴趣想要了解更多的鸿蒙应用开发细节和最新资讯，欢迎在评论区留言或者私信或者看我个人信息，可以加入技术交流群。
