Orchestra Python API | 使用 create 方法

前言：

Orchestra Python API （下文简称 api） 提供 create 方法用于创建实体，使用该方法，开发者能够轻松愉快地完成新增数据的任务。

可以认为创建一个实体等价于在数据表中创建了一条记录。

创建实体是写入操作，需要了解实体的权限、字段类型和其他属性，才能正确处理权限不足、类型错误等异常。

比如：

实体类型的 enabled 属性为假表示暂停使用，不支持创建操作。

权限角色是 客户 的用户默认不能创建实体，管理员可以在权限设置中更改该特性。

date_time 类型字段的默认格式为 “2023-8-17 10:00:00”，管理员可以在高级设置中更改格式。

date 类型字段的默认格式为 “2023-8-17″，管理员可以在高级设置中更改格式。

entity 类型字段的 remote_entity_types 属性如果不包含 Task，就不能传入 {“id”: 1, “type”: “Task”} 作为该字段的值。

read_only 属性为真的字段在用户会话中不支持创建操作。

正文：

有了以上须知作为前提，我们开始创建实体的课程吧。

create 方法支持两个参数，分别是 entity_type 和 data。

entity_type 是即将创建的实体的类型，为避免异常，开发者可以先判断该类型在图式中是否存在。

以 Task 为例，判断实体类型在图式中是否存在的方法如下：

schema = client.schema
if not client.schema:
    schema = client.read_schema()

existed = "Task" in schema
# existed: True

read_schema 方法会从服务端读取全部图式，一般而言，在一次会话中调用一次 read_schema 就足够了，密集调用会影响服务端的响应速度。

图式 指的是服务端中实体类型及字段的元数据，也可以理解为实体类型和字段的配置，这种配置会决定服务端主程序呈现何种特性、以何种方式运行。

Orchestra Python API 会对返回值做本地缓存，并通过对比本地与服务端图式 md5 值的方式判断是否重载图式。

有些团队会拥有数量庞大的实体类型，即将创建的实体类型如果处于未启用状态也会引起异常，判断方式如下：

enabled = client.schema["Task"]["enabled"]
# enabled: True

接下来我们了解一下第二个参数 data。

create 方法天然地采用批量的方式创建实体，所以 data 参数必须是列表类型，其中的元素必须是字典类型的数据，每个元素对应一个实体数据对象。

create 方法的返回值也是列表类型，返回列表中的每一个元素对应一个新建的实体数据对象。每个数据对象至少包含 id、type 两个属性。

id 是新实体的 id 字段，由服务端创建。不要在 data 参数中包含 id 属性，这样的实体数据对象会被服务端视作已存在的实体然后忽略。

type 是服务端保留的关键字，不是字段，其数值表示新实体的类型。

无论创建一个实体还是多个实体，data 参数都应该是列表类型，当然返回值也是列表类型。

以创建 Task 实体为例，创建一个 Task 时，data 参数应该是列表类型：

ret = client.create("Task", data=[{"name": "New Task"}])
# ret: [{"id": 1, "type": "Task"}]

创建两个 Task 时，data 参数也应该是列表类型：

ret = client.create("Task", data=[{"name": "Task 1"}, {"name": "Task 2"}])
# ret: [{"id": 1, "type": "Task"}, {"id": 2, "type": "Task"}]

Orchestra Python API 鼓励开发者以循环、迭代的方式批量操作数据以减轻服务端压力。

建议一次操作的数据量控制在 200 个以内，这也是网页端主程序的分页设置所允许的单页最大数据量。

后续我们会针对数据量更大的增删改操作提供专门的工具。

使用 data 参数需要注意：

1. 如果一个字段 的 required 属性为真，就表示该字段不可为空，data 参数的中实体数据必须包含该字段。比如 Version 的 code 字段 的 required 属性为 True，创建 Version 时 data 列表中的实体数据就必须包含 code。

开发者可以通过以下方式查看 required 属性:

code = client.schema["Version"]["fields"]["code"]
required = "required" in code and code["required"]

2. 如果一个字段的 read_only 属性为真，就表示该字段不支持在用户会话中写入，查看方法如下：

code = client.schema["Version"]["fields"]["code"]
read_only = "read_only" in code and code["read_only"]

3. 每种类型的字段都有既定格式，不同类型对应的格式汇总如下：

数据类型 说明
lambda 只读，不支持写入。
summary 只读，不支持写入。
pivot 只读，不支持写入。
checkbox 布尔型。
date 支持 Y-m-d 格式，表示日期类型。
date_time 支持 Y-m-d H:i:s 格式，表示日期时间类型。
integer 整数型。
duration 整数型，表示时长，默认单位是小时。
footage 正整数型。
number 整数型。
percent 整数型，如果要表示 99%，就需要输入 99。
text 字符串类型。
password 字符串型。
timecode 字符串型，需要遵守 00：00：00：00 的格式。
color 字符串类型，需要遵守 255,255,255 或 255,255,255,255 的格式。
uuid 字符串型，遵守 uuid 32位字符串格式。
email 字符串型，遵守 email 书写格式。
entity_type 字符串型，必须是图式中的实体类型。
list 字符串型，但数值必须是字段图式的 values 属性中的值。
status 字符串型，必须是是字段图式的 values 属性中的值。
currency 浮点型，支持最大 10 位数，小数精度 2 位。
float 浮点型。
url_template 字符串型，需要遵守一般路径格式。
image 字符串型，需要遵守一般路径格式。
url 路径型，支持 mac、linux、win、网络存储路径格式以及类似 “/a/b/c.exr 1001-10021” 的 frame range 格式。
entity 实体型，一般以字典的方式表示，必须包含 id 和 type 两个键。
multi_entity 实体列表型，一般以列表的方式表示，列表可以为空，也可以包含任意数量的实体类型数据。
serializable 可序列化类型，一般表示为字典或者列表，但可序列化的数据都可以作为参数。

注意：默认情况下，调用 create 方法会生成 事件日志（EventLogEntry）。

开发者需要阅读源码掌握 API 的异常处理，以免踩坑，使用 API 操作数据的效率远高于网页端的拖拽、点击操作。