开发云数据库
1、云数据库概述
云数据库是一款端云协同的数据库产品，是AGC云开发（AGC Serverless）关键服务之一，为AGC构建了MBaas（Mobile Backend as a Service，移动后端即服务）能力。云数据库提供了端云数据的协同管理、统一的数据模型和丰富的数据管理API接口等能力，端侧可以编写少量的代码实现AGC云端云数据库的交互。
云数据库采用基于对象模型的数据存储结构，与常见的关系数据库（MySQL，Oracle等）类似，包含数据表、表字段、表字段值、主键，以及表操作权限。唯一不同在于存储区，数据以对象的形式存储在不同的存储区中，每一个对象，都是一条完整的数据记录。存储区是一个独立的数据存储区域，每个存储区拥有完全相同的对象类型定义（也就是数据表），可以根据业务能力为不同用户划分不同的存储区。
云数据库对象类型、存储区以及数据，可以通过AGC控制台定义、创建和管理，也可以通过一站式集成开发工具DevEco Studio定义、创建和管理。云数据库支持多种数据类型，包括字符串、数值、文本、日期等。
云数据库还提供了多重数据安全策略，基于隐私或者敏感数据的全程加密管理能力，加密字段的数据在端侧会被加密，然后再以密文形式发送并存储到云数据库中。同时，提供基于角色的权限管理模型，预置4种角色和3种权限，来保证数据的安全，同时简化了权限管理操作。
2、数据库模型概述
云数据库是一款基于对象模型的数据库，采用存储区、对象类型和对象三级结构。每个应用在开通云数据库服务后，都会实例化一个云数据库实例，该实例中可以创建多个对象类型（数据表）、多个存储区。一个对象类型的数据可以对应一个存储区，也可以对应多个存储区。
对象类型（ObjectType）：用于定义存储对象的集合，不同的对象类型对应的不同数据结构。每创建一个对象类型，云数据库会在每个存储区实例化一个与之结构相应的对象类型，用于存储对应的数据。
存储区（CloudDBZone）：是一个独立的数据存储区域，多个数据存储区相互独立。每个存储区拥有完全相同的对象类型定义，开发者可以根据业务需要自定义存储区中存储的对象。
对象（CloudDBZoneObject）：是云数据库基本操作单元，每个对象，都是一条完整的数据记录。
1）数据类型
云数据库支持多种数据类型，如下表所示：
| 数据类型 | 描述 | 取值范围 | 说明 |
|---|---|---|---|
| String | 字符串类型 | 最大长度200 | 字符串长度超过200，请使用Text类型。 |
| Boolean | 布尔类型 | true：真；false：假。 | - |
| Byte | 单字节整型 | -128 ～ +128 | - |
| Short | 双字节整型 | -32,768 ～ +32,767 | - |
| Integer | 四字节整型 | -2,147,483,648 ～ +2,147,483,647 | - |
| Long | 八字节整型 | -9,223,372,036,854,775,808 ～ 9,223,372,036,854,775,807 | - |
| Float | 单精度浮点数 | -3.40E+38 ～ +3.40E+38，6位十进制有效数字。 | - |
| Double | 双精度浮点数 | -1.79E+308 ～ +1.79E+308，15位十进制有效数字。 | - |
| ByteArray | 字节数组 | - | 一般用于文件类型的数据存储，如图片、文档和视频等。 |
| Text | 文本类型 | - | - |
| Date | 日期类型 | - | - |
| IntAutoIncrement | 自增类型，从1开始自增，Integet类型。 | 1 ～ 2,147,483,647 | |
| LongAutIncrement | 自增类型，从1开始自增，Long类型。 | 1 ～ 9,223,372,036,854,775,807 |
2） 权限管理
云数据库支持对所有用户的访问进行鉴权，保障应用数据的安全。云侧访问云数据库的用户角色默认为管理员角色，即从AGC控制台、云函数和Server端访问云数据库角色，该角色默认拥有所有权限。端侧为应用程序运行端，端侧的数据操作有严格的安全规则限制，其数据的读写权限根据云侧权限配置表进行控制。
云数据库预置4种角色和3种权限，如下表所示：
| 角色 | query | upsert | delete | 说明 |
|---|---|---|---|---|
| 所有人 | ✅ | ✅ | ✅ | 代表所有用户，包含认证和非认证用户。该角色默认拥有query权限，可自定义配置upsert和delete权限，但不建议将upsert和delete权限配置给所有人角色。当对象类型中设置了加密字段之后，表示开启全程加密功能，此时所有人角色将不会拥有query、upsert和delete权限，且不允许修改。 |
| 认证用户 | ✅ | ✅ | ✅ | 经过AGC登录认证的用户。该角色默认拥有query权限，可自定义配置upsert和delete权限。当对象类型中设置了加密字段之后，表示开启全程加密功能，此时认证用户角色将不会拥有query、upsert和delete权限，且不允许修改。 |
| 数据创建者 | ✅ | ✅ | ✅ | 经过认证的数据创建用户。该角色默认拥有所有权限，且可自定义配置所有权限。每条数据都有其对应的数据创建人（即应用用户），每个数据创建者仅可以upsert或者delete自己创建的数据，不能upsert或者delete他人创建的数据。数据创建者的信息保存在数据记录的系统表中。 |
| 管理员 | ✅ | ✅ | ✅ | 应用开发者，主要是指通过AGC控制台或FaaS（Function as a Service，函数即服务）侧访问云数据库的角色。该角色默认拥有所有权限，且可自定义配置所有权限。管理员可以管理并配置其他角色的权限。 |
3、开发云数据库
1）创建对象类型
- 展开云侧工程目录，右击“clouddb/objecttype”目录，选择“New > Cloud DB Object Type”。
- 在弹出的新建对象类型窗口中输入对象类型名称（下文以喂养记录“Feeding”对象类型为例）后，点击OK按钮完成创建。对象类型命名必须符合以下规范：
- 只能包含大小写字母，数字，下划线，并且至少包含字母类型。
- 必须以字母开头，以字母或者数字结尾，不允许以“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。
- DevEco Studio工具会根据通用云开发模板内置的对象类型模板新建对象类型JSON文件”Feeding.json“，并会在编码区自动打开该文件。文件结构属性包括对象类型名称（objectTypeName）、对象类型配置字段信息（fields）、对象类型索引信息（indexes）、对象类型角色权限（permissions）。
- 根据业务需要在“fields”中配置对象类型字段信息，字段属性如下表所示。
| 参数 | 必须（M）/可选（O） | 说明 |
|---|---|---|
| fieldName | M | 字段名称。 |
| filedType | M | 字段的数据类型。 |
| belongPrimaryKey | O | 设置该字段是否为对象类型的主键，默认值为false。 |
| notNull | O | 设置字段值是否为非空，默认为false。 |
| isNeedEncrypt | O | 设置字段是否需要加密，开启全程加密数据管理功能，默认值为false。 |
| isSensitive | O | 设置字段是否为敏感字段，默认值为false。 |
| defaultValue | O | 字段为非空时，必须设置默认值。 |
为Feeding对象类型配置如下字段：
| filedName | fieldType | belongPrimaryKey | notNull | isNeedEncrypt | defaultValue |
|---|---|---|---|---|---|
| id | Integer | true | true | ||
| type | String | ||||
| leftDuration | Integer | ||||
| rightDuration | Interger | ||||
| totalDuration | Integer | ||||
| startTime | Date |
"fields": [{"fieldName": "id", "fieldType": "Integer", "notNull": true, "belongPrimaryKey": true},{"fieldName": "type", "fieldType": "String", "notNull": true, "defaultValue": "母乳"},{"fieldName": "leftDuration", "fieldType": "Integer"},{"fieldName": "rightDuration", "fieldType": "Integer"},{"fieldName": "totalDuration", "fieldType": "Integer"},{"fieldName": "startTime", "fieldType": "Date"}
]
- 根据业务需要在“indexes”中为该对象类型配置索引、索引包含的字段、以及索引包含的字段的排序方式。索引属性如下表所示。
| 参数 | 必须（M）/可选（O） | 说明 |
|---|---|---|
| indexName | M | 索引名称。 |
| indexList > fieldName | M | 索引包含的字段。 |
| indexList > sortType | M | 索引包含的字段的排序方式，支持升序或降序。 |
为Feeding对象类型配置如下索引：
| indexName | fieldName | sortType |
|---|---|---|
| IND_20251034 | id | DESC |
"indexes": [{"indexName": "IND_20251034", "indexList": [{"fieldName":"id","sortType":"DESC"}]}
]
- 根据实际业务在“permissions”中设置各角色是否具有该对象类型的Read、Upsert（包含新增和修改）和Delete权限。角色权限属性如下表所示。
| 参数 | 必须（M）/可选（O） | 说明 |
|---|---|---|
| role | M | 用户角色。 |
| rights | M | 授予角色的权限，包括Read、Upsert（包括新增和修改）和Delete权限。 |
为Feeding对象类型配置如下权限：
| 角色 | 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"]}
]
2）添加数据条目
为对象类型添加数据条目，并配置数据所在的存储区，当前支持手动创建和自动生成数据条目文件，建议使用DevEco Studio工具提供的自动生成数据条目文件。右击对象类型JSON文件，选择“Generate Data Entry”，依旧以对象类型“Feeding”为例，包含“id”、“type”、“leftDuration”、“rightDuration”、“totalDuration”、“startTime”字段。
- 在弹出的“New Cloud DB Data Entry”窗口内，为即将生成的数据条目文件定义名称。此处取默认值“d_Feeding”为例。
- 会根据DevEco Studio工具预置通用云开发模板提供的数据条目模板自动在“clouddb/dataentry”目录下为对象类型“Welcome”生成数据条目文件“d_Feeding”，该文件中已为开发者预置了默认的存储区，所属对象类型名称（“Welcome”），以及对象类型的字段名（“id”、“type”、“leftDuration”、“rightDuration”、“totalDuration”、“startTime”）。
- cloudDBZoneName：配置存储区名称，支持自定义，需要开发者记住存储区名称，在使用API访问云数据库时需要使用该值获取对象类型数据。
- objectTypeName：对象类型名称。
- objects：配置当前对象类型中所有字段的值，即写入数据。一个对象即为一条数据，可以通过新建一个对象来为字段赋新值，也可以修改某个对象下字段的值。需要注意的是，主键或加密字段的值不支持修改。
{"cloudDBZoneName": "default","objectTypeName": "Feeding","objects": [{"id": 1,"type": "母乳","leftDuration": 10,"rightDuration": 10,"totalDuration": 10,"startTime": 1747104297569},{"id": 2,"type": "母乳","leftDuration": 20,"rightDuration": 20,"totalDuration": 20,"startTime": 1747104297569}]
}
3）部署云数据库
完成对象类型创建以及对象类型数据条目创建后，开发者可以通过右击对象类型或者数据条目直接将对象类型和数据条目部署到AGC云端。DevEco Studio工具支持单个对象类型和数据条目部署，也支持批量部署。
- 单个对象类型部署，右击对象类型名称。若批量部署，需要右击“clouddb”目录，选择“Deploy Cloud DB”。
- 可以在开发工具主界面底部状态栏右侧查看云数据库打包与部署进度。等待部署云数据库，直至出现“Deploy successfully”消息，表示云数据库已成功部署。
- 云数据库部署成功后，DevEco Studio工具会自动从AGC云端下载云数据库的schema文件，并将该文件存储在端侧工程“AppScope/resources/rawfile“目录，文件名称为”schema.json“，该文件是端侧API访问云数据库必须引入的配置文件。
4）查看云数据库部署情况
打开云开发管理面板，点击面板中的“CloudDev > Go to console”或者“Serverless > Cloud DB > Go to console”打开AGC控制台。两者区别在于第一种方式需要在AGC控制台页面点击左侧“云数据库”菜单，而第二种方式可以直接定位到AGC控制台云数据库子控制台。分别点击“对象类型”、“存储区”与“数据”页签，查看通过DevEco Studio工具开发并部署的云数据库资源是否已经成功部署到AGC云端。
