当前位置：首页 > article >正文

【HarmonyOS Next之旅】DevEco Studio使用指南(二十九) -＞开发云数据库

article 2025/9/15 21:02:22

1 -> 开发流程

2 -> 创建对象类型

3 -> 添加数据条目

3.1 -> 手动创建数据条目文件

3.2 -> 自动生成数据条目文件

4 -> 部署云数据库

1 -> 开发流程

云数据库是一款端云协同的数据库产品，提供端云数据的协同管理、统一的数据模型和丰富的数据管理API接口等能力。云数据库采用基于对象模型的数据存储结构。数据以对象(Object)的形式存储在不同的存储区中，每一个对象，都是一条完整的数据记录。对象类型(ObjectType)用于定义存储对象的集合，不同的对象类型对应的不同数据结构。存储区(Zone)是一个独立的数据存储区域，每个存储区拥有完全相同的对象类型定义。

可以使用DevEco Studio在端云一体化云侧工程下开发云数据库，总体流程如下。

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

2 -> 创建对象类型

对象类型(ObjectType)用于定义存储对象的集合，不同的对象类型对应的不同数据结构。每创建一个对象类型，云数据库会在每个存储区实例化一个与之结构相对应的对象类型，用于存储对应的数据。

创建对象类型的操作如下：

1. 右击“clouddb/objecttype”目录，选择“New > Cloud DB Object Type”。

2. 输入对象类型名称(下文以“objecttype1”为例)后，点击“OK”。

说明

对象类型名称必须符合如下规范：

只能包含字母（A-Z或a-z）、数字（0-9）和下划线（_），并且至少包含字母类型。
必须以字母开头，以字母或者数字结尾，不允许以“sqlite_”开头，不允许以下划线（_）结尾。
不允许使用如下系统保留名称： naturalbase_metadata、objecttypeinfohelper、t_data_upgrade_info、t_index_schema、t_nstore_config、t_schema_negotiate_info、t_metadata_schema、t_nstore_permission、t_system_config。

“clouddb/objecttype”目录下生成并打开新建的对象类型JSON文件“objecttype1.json”。

3. 在“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。
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个字符。

例如，我们可为“objecttype1”对象类型配置如下字段。

fieldName	fieldType	belongPrimaryKey	notNull	isNeedEncrypt	defaultValue
author	String	true	true	-	-
shadowFlag	Boolean	-	true	-	true
bookName	String	-	-	-	-
id	Integer	-	-	-	-
price	Double	-	-	-	-
publishTime	Date	-	-	-	-

4. 在“indexes”中为该对象类型配置索引、索引包含的字段、以及索引包含的字段的排序方式。

参数	必选(M)/可选(O)	说明
indexName	M	索引名称。输入要求具体如下：索引的名称长度必须大于或等于1个字符，小于或等于30个字符，只能包含以下3种类型，并且至少包含“字母”类型：字母（A-Z或a-z）数字（0-9）特殊字符：_ 索引名称必须以字母开头。索引名称中不区分字母的大小写。修改对象类型时，仅支持新增或者删除索引。当删除索引后，本次提交前不允许新增同名索引。每个对象类型可以设置小于或等于16个索引。数据类型为ByteArray和Text的字段不支持设置为索引。
indexList > fieldName	M	索引包含的字段。支持设置组合索引，由多个字段组合成为索引，一个组合索引包含的字段不超过5个。
indexList > sortType	M	索引包含的字段的排序方式，支持升序或降序。

例如，我们可为“objecttype1”对象类型配置如下两个索引。

indexName	fieldName	sortType
id_Index	id	ASC
price_Index	price	DESC

5. 在“permissions”中设置各角色是否具有该对象类型的Read、Upsert(包含新增和修改)和Delete权限。

参数

必选(M)/可选(O)

说明

role

用户角色，包括：

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

授予角色的权限，包括Read、Upsert(包含新增和修改)和Delete权限。

说明

各角色只能完成对应权限的操作，超出权限范围的操作云侧将返回“permission denied”错误。由于端云一体化工程的初始化代码未配置AccessToken，故“CloudProgram/clouddb/objecttype/Post.json”中给World角色添加了Upsert和Delete权限。

例如，我们可按下表为各个角色配置“objecttype1”对象类型的权限。

角色	Read	Upsert	Delete
World	√	–	–
Authenticated	√	√	–
Creator	√	√	√
Administrator	√	√	√

3 -> 添加数据条目

创建完对象类型后，您可在对象类型内添加数据条目(DataEntry)，并配置数据所在的存储区。

支持手动创建和自动生成数据条目文件。

3.1 -> 手动创建数据条目文件

1. 右击“clouddb/dataentry”目录，选择“New > Cloud DB Data Entry”。

2. 在“Associated Cloud DB Object Type”栏选择需添加数据条目的对象类型，在“Enter Cloud DB Data Entry Name”栏定义数据条目文件名，完成后点击“OK”。

例如，选择刚刚创建的对象类型“objecttype1”，数据条目文件取默认名“d_objecttype1”。

如下图，“clouddb/dataentry”目录下生成并打开新建的数据条目JSON文件“d_objecttype1”，该文件中已为您预置好所属对象类型名称(“objecttype1”)与对象类型的字段名(“id”、“bookName”、“author”、“price”、“publishTime”、“shadowFlag”)。

3. 配置存储区和字段的值(即数据)。

“cloudDBZoneName”：配置存储区名称。上图示例中的“default”表示添加数据条目至default存储区。支持修改，如下图“cloudDBZoneName1”。另外，在使用API访问云数据库编码时需要引用该字段。
“objects”：配置当前对象类型中所有字段的值，即写入数据。一个对象(object)即为一条数据，您可以通过新建一个对象(object)来为字段赋新值，也可以修改某个对象(object)下字段的值(主键或加密字段的值不支持修改)。如下图，写入了两条数据。

字段	数据条目1	数据条目2
author	Nancy	Peter
shadowFlag	true	false
bookName	My Favorite Book	Your First English Book
id	10	20
price	10.5	20.5
publishTime	19961007	19961007

3.2 -> 自动生成数据条目文件

1. 右击对象类型JSON文件，选择“Generate Data Entry”。

依旧以对象类型“objecttype1”为例，其包含了“id”、“bookName”、“author”、“price”、“publishTime”、“shadowFlag”六个字段。

2. 在弹出的“New Cloud DB Data Entry”框内，为即将生成的数据条目文件定义名称。此处取默认值“d_objecttype1”为例。

如下图，“clouddb/dataentry”目录下自动为对象类型“objecttype1”生成数据条目文件“d_objecttype1”，该文件中已为您预置好所属对象类型名称(“objecttype1”)与对象类型的字段名(“id”、“bookName”、“author”、“price”、“publishTime”、“shadowFlag”)。

3. 配置存储区和字段的值(即数据)。

“cloudDBZoneName”：配置存储区名称。上图示例中的“default”表示添加数据条目至default存储区。支持修改，如下图“cloudDBZoneName1”。另外，在使用API访问云数据库编码时需要引用该字段。
“objects”：配置当前对象类型中所有字段的值，即写入数据。一个对象(object)即为一条数据，您可以通过新建一个对象(object)来为字段赋新值，也可以修改某个对象(object)下字段的值(主键或加密字段的值不支持修改)。如下图，写入了两条数据。

字段	数据条目1	数据条目2
author	Nancy	Peter
shadowFlag	true	false
bookName	My Favorite Book	Your First English Book
id	10	20
price	10.5	20.5
publishTime	19961007	19961007

4 -> 部署云数据库

完成数据条目创建后，可以直接部署该数据条目。也可以等所有对象类型和数据条目开发完成后，再统一批量部署到AGC云端。

说明

部署到AGC云端的存储区数量不得超过4个，否则会导致部署失败，提示“clouddb deploy failed. Reason is the number of CloudDBZone exceeds the limit.”错误。如AGC云端当前已存在4个存储区，请将数据部署到已有的存储区，或者删除已有存储区后再部署新的存储区。需要注意的是，删除存储区，该存储区内的数据也将一并删除，且不可恢复。
对象类型中的fieldType等字段信息，部署到AGC云端后，请勿在本地再做修改。例如，fieldType设置为String，对象类型部署成功后，又在本地修改fieldType为Integer，再次部署将失败，提示“clouddb deploy failed. Reason is existing fields cannot be modified.”错误。如需更改fieldType等字段信息，请先删除云端部署的对象类型。需要注意的是，删除云端对象类型，对象类型内添加的数据也将一并删除，且不可恢复。

部署云数据库的操作如下：

1. 右击“clouddb”目录，选择“Deploy Cloud DB”。

2. 可在底部状态栏右侧查看云数据库打包与部署进度。

耐心等待，直至出现“Deploy successfully”消息，表示云数据库已成功部署。

说明

云数据库部署成功后，DevEco Studio将自动从云侧下载云数据库的schema文件至“AppScope/resources/rawfile/schema.json”路径，该文件是云数据库端侧API必须引入的配置文件。

3. 在菜单栏选择“Tools > CloudDev”。

4. 在打开的CloudDev面板中，点击“Serverless > Cloud DB”下的“Go to console”，进入当前项目的云数据库服务页面。

5. 分别点击“对象类型”、“存储区”与“数据”页签，可查看到本地开发的云数据库资源均已成功部署至AGC云端。

部署成功后，便可以从端侧访问云数据库了。

还可以在AGC控制台继续编辑以上部署的云数据库资源。

对象类型“Post”所属存储区“Demo”、“objecttype1”所属存储区“cloudDBZoneName1”：

“d_Post.json”内的数据条目、“d_objecttype1.json”内的数据条目：

说明

部署对象类型或数据条目JSON文件，实际是部署JSON文件内包含的对象类型或数据条目。因此，在AGC控制台查看到的将是一个个对象类型或者一条条数据，而非JSON文件。

感谢各位大佬支持！！！

互三啦！！！