【HarmonyOS Next之旅】DevEco Studio使用指南(二十九) -＞ 开发云数据库
目录
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 | 字段名称。 输入要求具体如下：
说明 当前Cloud Foundation Kit暂不支持自增类型字段IntAutoIncrement或LongAutoIncrement。 |
| fieldType | M | 字段的数据类型。 当前支持的数据类型：String、Boolean、Byte、Short、Integer、Long、Float、Double、ByteArray、Text、Date。 |
| belongPrimaryKey | O | 设置该字段是否为对象类型的主键，默认值为false。
|
| notNull | O | 设置字段值是否为非空，默认值为false。
|
| isNeedEncrypt | O | 设置字段是否需要加密，开启全程加密数据管理功能，默认值为false。 选择加密后，该字段对应的数据会加密存储在存储区中。
|
| isSensitive | O | 设置字段是否为敏感字段，默认值为false。 选择敏感后，该字段对应的数据会加密存储在存储区中。
|
| defaultValue | O | 字段为非空时，必须设置默认值。
|
例如，我们可为“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 | 索引名称。 输入要求具体如下：
|
| 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 | M | 用户角色，包括：
|
| rights | M | 授予角色的权限，包括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文件。
感谢各位大佬支持！！！
互三啦！！！