HarmonyOS Next 端云一体化（2）

本章节主要讲一下端云一体化中的数据库操作

介绍

云数据库是端云协同的数据库产品，具备端云数据协同管理、统一数据模型及丰富数据管理 API 接口等能力。它采用基于对象模型 的

数据存储结构，数据以对象（Object） 形式存于不同存储区，每个对象为一条完整数据记录。 对象类型（ObjectType） 定义存储对

象集合，不同对象类型对应不同数据结构。存储区（Zone） 是独立的数据存储区域，每个存储区的对象类型定义完全相同。

学习流程

我们会按照以下流程来进行学习。

新建存储区：也就是新建数据库
创建对象类型：创建一个用于存储数据条目的对象类型。
添加数据条目：在刚刚创建的对象类型内添加一条条数据，并配置数据所在的存储区。
部署云数据库：数据成功添加后，您可以直接将该数据部署至 AGC 云端。您也可以等所有对象类型和数据条目开发完成后，再统一批量部署到 AGC 云端。

存储区

我们这里新建一个存储区 Study 用来存放稍后用到的数据。

然后我们在 DevEco Studio 的云端配置中指定存储区。

clouddb/db-config.json

{
    "defaultCloudDBZoneName": "Study", // 存储区的名称
    "defaultDataStorageLocation": "CN"
}

创建对象类型

什么是创建对象类型

创建对象类型可以理解为就是为我们的数据定义类型。类似于使用接口或者 class 来定义数据，但是这里操作的范围要更大。

定义基本的数据类型，如数字、字符串、布尔、日期时间等。
定义字段的权限，因为这个对象类型本身是数据表，定义权限相当于设置了哪一类用户拥有哪些权限。如读取、编辑、新增、删除等
定义索引，考虑数据量大需要比较方便的查找到要操作的数据，需要定义索引。

比如，我们需要根据书籍数据来定义类型。 Book

字段	类型	说明
id	number	id
name	string	书名
price	number	价格
publish	date	出版日期
hot	boolean	是否热门
cover	string	封面

对象类型的规范

新建 Book 对象类型文件

这个对文件需要按照以下格式来编写。其中的字段的一些规范需要特别注意。

{
  "objectTypeName": 对象实体名称
  "fields": 对象中的属性
  "indexes": 索引
  "permissions" 权限
}

objectTypeName

表示实体对象的名称，我们这里可以是 Book

{
  "objectTypeName": "Book"
}

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"
    }
  ]
}

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"
        }
      ]
    }
  ]
}

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"]
    }
  ]
}

创建数据条目

我们搭建好了对象类型，现在可以根据它来插入数据了。

新建数据文件
插入数据这里可以看到一些基本数据
```
{
  "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"
    }
  ]
}
```
字段解释
- cloudDBZoneName：配置存储区名称。
- objects：配置当前对象类型中所有字段的值，即写入数据。一个对象（object）即为一条数据，您可以通过新建一个对象（object）来为字段赋新值，也可以修改某个对象（object）下字段的值（主键或加密字段的值不支持修改）

部署云数据库

刚才我们都是在本地搭建的数据库，现在我们需要将这些数据同步到 AGC 平台的数据库上。

部署的方式也很简单

部署

成本

刷新 AGC 平台上的数据库

总结

本文详细介绍了 HarmonyOS 云数据库的基本操作流程：

存储区（Zone）创建
- 创建名为 Study 的存储区
- 在 DevEco Studio 中配置存储区信息
对象类型（ObjectType）定义
- 详细讲解了对象类型的规范和组成部分
- 包含 objectTypeName、fields、indexes 和 permissions 四个主要部分
- 以 Book 对象为例，展示了完整的对象类型定义过程
数据操作
- 创建数据条目的具体步骤
- 展示了如何在 JSON 文件中定义数据内容
- 说明了 cloudDBZoneName 和 objects 的配置方法
云端部署
- 介绍了如何将本地数据库部署到 AGC 平台
- 展示了部署过程和成本预估
- 说明了如何在 AGC 平台上刷新数据库

通过这些步骤，我们完成了一个基本的云数据库的创建、配置和部署过程，为后续的端云协同开发打下了基础。

如果你兴趣想要了解更多的鸿蒙应用开发细节和最新资讯，欢迎在评论区留言或者私信或者看我个人信息，可以加入技术交流群。

HarmonyOS Next 端云一体化（2）