数据(Item)是伙伴云存储的核心,数据是由不同字段的值组成的对象(类似于关系型数据库中的行记录)。为了让数据更灵活、更易用、更具扩展性,我们设计了独特的数据结构。数据的核心属性是 fields,表示数据的值。

创建(更新)数据

创建(更新)数据只需要将数据各个字段的值提交到服务端,就可以完成对数据的保存。提交的数据是一个以字段ID为键名的字典,以下是数据创建所提交的内容:

{
    "fields" : {
        "1000000" : 100,
        "1000001" : "文本字段内容",
        "1000002" : [
            1,
            2
        ],
        "1000003" : [
            300000,
            300001
        ]
    }
}

不同类型的字段所提交的格式也有所区别:

字段类型 值类型 值说明 值示例
文本(text) string 文本内容 "文本字段内容"
数字(number) integer 整数或浮点数 100
日期(date) string 文本格式的时间 "2016-11-11 11:11:11"
选项(category) 支持 选项ID集合 [1, 2, 3]
用户(user) array 工作区成员ID集合 [30001, 30002, 30003]
关联(relation) array 关联的数据ID集合 [10001, 10002, 10003]
图片(image) array 上传的图片ID集合 [20001, 20002, 20003]
文件(file) array 上传文件ID集合 [20001, 20002, 20003]

在更新的场景中,使用特殊的空值 null,表示删除指定字段的值。例如需要删除字段ID等于1000的值时,提交的内容是:"1000":null。

查询数据

查询数据的使用场景往往需要更多的信息,并且数据格式也需要统一并且可扩展的。因此,查询数据得到的结果的数据格式较创建时,设计上复杂一些。fields 字段格式是数组(为了体现字段在表格中的的顺序)。数组的每一项是一个 字段值 对象,以下是一个 字段值 对象:

{
    "field_id": 6000,
    "type": "text",
    "values": [
        {
            "value": "文本字段内容"
        }
    ]
}

其中 values 是 字段值 对象的核心属性,表示当前字段的值。values 是数组格式,其中包含一个或多值(不同字段类型不同)。不同类型的字段返回的格式也有所区别:

字段类型 是否支持多值 值说明 值示例
文本(text) 不支持 文本内容 "values": [
{"value": "文本字段内容"}
]
数字(number) 不支持 整数或浮点数 "values": [
{"value": 100}
]
计算(caculation) 不支持 整数或浮点数 "values": [
{"value": 100}
]
日期(date) 不支持 文本格式的时间 "values": [
{"value": "2016-11-11 11:11:11"}
]
选项(category) 支持 选项对象集合 "values": [
{"id": 1, "text": "选项1", "color": "red"},
{"id": 2, "text": "选项2", "color": "red"},
{"id": 3, "text": "选项3", "color": "red"}
]
用户(user) 支持 工作区成员对象集合 "values": [
{"user_id": 30001, "name": "用户1"},
{"user_id": 30002, "name": "用户2"},
{"user_id": 30003, "name": "用户3"}
]
关联(relation) 支持 关联的数据对象集合 "values": [
{"item_id": 10001, "title": "数据1"},
{"item_id": 10002, "title": "数据2"},
{"item_id": 10003, "title": "数据3"}
]
图片(image) 支持 上传的图片对象集合 "values": [
{"file_id": 20001, "name": "图片1.jpg"},
{"file_id": 20002, "name": "图片2.jpg"},
{"file_id": 20003, "name": "图片3.jpg"}
]
文件(file) 支持 上传文件对象集合 "values": [
{"file_id": 20001, "name": "文件1.jpg"},
{"file_id": 20002, "name": "文件2.jpg"},
{"file_id": 20003, "name": "文件3.jpg"}
]

当字段没有值的时候,不会在 fields 中返回。