API 接口
获取文档列表
根据简单的排序、分组条件,获取某内容集合的文档数据
请求路径
GET /{collectionName}/?limit={limit}&skip={skip}&fields={fields}&sort={sort}
响应体
字段 | 类型 | 说明 |
---|---|---|
requestId | String | 请求 ID |
data | Object | 返回结果 |
code | String | 发生错误时的错误码 |
message | String | 发生错误时的错误信息 |
total | Number | 文档总数量 |
响应示例
{
"data": [
{
"_id": "ecdacfc05f3f28a800000bf51126de2f",
"name": "test",
"arr": ["sss", "sss", "ssss"],
"markdown": "markdown 文本",
"textarea": "ssssssssssssssssssssssssssssss",
"_createTime": 1597974695982,
"_updateTime": 1597974695982
}
],
"offset": 0,
"limit": 10,
"requestId": "1742eb3145c_11",
"total": 1
}
查询文档列表
获取符合查询条件的文档列表
请求路径
POST /{collectionName}/find?limit={limit}&skip={skip}&fields={fields}&sort={sort}
请求体
如下所示,query
为查询条件, 并支持使用Query Command
{
"query": {
"price": { "$ge": 100 }
}
}
响应
{
"data": [
{
"_id": "ecdacfc05f3f28a800000bf51126de2f",
"name": "test",
"arr": ["sss", "sss", "ssss"],
"markdown": "markdown 文本",
"textarea": "ssssssssssssssssssssssssssssss",
"_createTime": 1597974695982,
"_updateTime": 1597974695982
}
],
"requestId": "1742eb3145c_11",
"total": 1,
"offset": 0,
"limit": 10
}
获取单个文档
获取指定 Id 的文档
请求路径
GET /{collectionName}/{docId}
参数说明
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
docId | String | 是 | 内容文档 Id |
响应
{
"data": {
"_id": "ecdacfc05f3f28a800000bf51126de2f",
"name": "test",
"arr": ["sss", "sss", "ssss"],
"markdown": "markdown 文本",
"textarea": "ssssssssssssssssssssssssssssss",
"_createTime": 1597974695982,
"_updateTime": 1597974695982
},
"requestId": "175d6218c00_6"
}
创建新的文档
创建新的内容文档
请求路径
POST /{collectionName}
请求体
请求体如下所示,data
为由新建文档组成的数组,支持一次创建多个文档
{
"data": [
{
"name": "商品名称",
"price": 100
}
]
}
响应
{
"id": "b5416b755f476d450088360c0054b6fb",
"requestId": "1742f02d897_42"
}
更新单个文档
更新文档的内容,更新操作时,文档的最终结果为传入的 data
与现有文档内容的合并值,即同名字段替换原值。
请求路径
docId
为需要更新的文档
PATCH /{collectionName}/{docId}
请求体
请求体如下所示,data
为需要更新的内容,并且支持使用 Update Command
{
"data": {
"name": "商品名称",
"price": 100
}
}
响应
{
"updated": 1,
"requestId": "1742ef4477b_12"
}
批量更新文档
批量更新符合查询条件的数据为指定的内容
请求路径
PATCH /{collectionName}/
请求体
query
为查询条件,data
为更新的内容,如下面的示例,将 name
为 oldName
所有的内容, 更新name
为 newName
,同时,query
也支持 Query Command
{
"query": {
"name": "oldName"
},
"data": {
"name": "newName"
}
}
响应
字段 | 类型 | 说明 |
---|---|---|
updated | Number | 更新成功的文档数量 |
matched | Number | 符合条件的文档数量 |
upsert_id | String | 替换更新 插入新 doc 时存在,其余情况为 null |
{
"requestId": "2a3ec45e223a4",
"updated": 1,
"matched": 1,
"upsert_id": null
}
替换单个文档
替换指定的文档为新的内容,替换操作只支持对单个文档进行。
请求路径
docId
为需要替换的文档
PUT /{collectionName}/{docId}
请求体
请求体如下所示,data
为需要更新的内容
{
"data": {
"name": "商品名称",
"price": 100
}
}
响应
{
"updated": 1,
"upsertedId": null,
"requestId": "175d648919d_e"
}
删除单个文档
删除某个项目下某内容类型的指定文档
请求路径
docId
为需要删除的文档的 _id
DELETE /{collectionName}/{docId}
响应
{
"deleted": 1,
"requestId": "175d649a89f_a"
}
批量删除文档
批量删除符合查询条件的内容文档
请求路径
DELETE /{collectionName}/
请求体
如下所示,query
为查询条件, 并支持使用Query Command
{
"query": {
"price": { "$gt": 100 }
}
}
响应
字段 | 类型 | 说明 |
---|---|---|
deleted | Number | 删除成功的文档数 |
{
"requestId": "23f416d4f8722",
"deleted": 1
}
Query Command
下面仅列出了部分 Command,全部 Command 请查看数据库 SDK 文档
$eq
表示字段等于某个值。
语法:{ <field>: { $eq: <value> }}
{
"data": {
"name": {
"$eq": "cms"
}
}
}
$ne
表示字段等于某个值。
语法:{ <field>: { $ne: <value> }}
{
"data": {
"name": {
"$ne": "luke"
}
}
}
$gt
表示字段大于某个值。
语法:{ <field>: { $gt: <value> }}
{
"data": {
"age": {
"$gt": 18
}
}
}
$gte
表示字段大于或等于某个值。
语法:{ <field>: { $gte: <value> }}
{
"data": {
"age": {
"$gte": 18
}
}
}
$lt
表示字段小于某个值。
语法:{ <field>: { $lt: <value> }}
{
"data": {
"age": {
"$lt": 18
}
}
}
$lte
表示字段小于或等于某个值。
语法:{ <field>: { $lte: <value> }}
{
"data": {
"age": {
"$lte": 18
}
}
}
$in
字段值在给定的数组中。
语法:{ <field>: { $in: [<value1>, <value2>, ... <valueN>] }}
{
"data": {
"category": {
"$in": ["science", "computer"]
}
}
}
$nin
字段值不在给定的数组中。
语法:{ <field>: { $nin: [<value1>, <value2>, ... <valueN>] }}
{
"data": {
"category": {
"$nin": ["science", "computer"]
}
}
}
$and
表示需同时满足指定的两个或以上的条件。
语法:{ $and: [{ <expression1> }, { <expression2> } , ... , { <expressionN> }] }
{
"data": {
"$and": [
{
"price": {
"$lt": 200
}
},
{
"price": {
"$gt": 100
}
}
]
}
}
$or
表示需满足所有指定条件中的至少一个。
语法:{ $or: [{ <expression1> }, { <expression2> }, ... , { <expressionN> }] }
{
"data": {
"$or": [
{
"price": {
"$lt": 200
}
},
{
"price": {
"$gt": 100
}
}
]
}
}
$nor
表示逻辑 "都不" 的关系,表示需不满足指定的所有条件。
语法:{ $nor: [{ <expression1> }, { <expression2> }, ... { <expressionN> }] }
{
"data": {
"$nor": [
{
"price": {
"$lt": 200
}
},
{
"price": {
"$gt": 100
}
}
]
}
}
Update Command
下面仅列出了部分 Command,全部 Command 请查看数据库 SDK 文档
$set
用于设定字段等于指定值,支持以点操作符表示法访问数组的元素和访问嵌入文档的字段
语法:{ $set: { <field>: <value>, ... } }
{
"data": {
"$set": {
"text": "a",
"style.color": "red",
}
}
}
$inc
用于指示字段自增某个值,这是个原子操作
语法:{ $inc: { <field1>: <amount1≥, <field2>: <amount2>, ... }}
{
"data": {
"$inc": {
"price": 1000
}
}
}
$mul
用于指示字段自乘某个值
语法:{ $mul: { <field>: <number1> }}
{
"data": {
"$mul": {
"price": 1.5
}
}
}
$unset
用于表示删除某个字段
语法:{ $unset: { <field1>: "" }}
{
"data": {
"$unset": {
"rating": ""
}
}
}
$push
向数组尾部追加元素,支持传入单个元素或数组
语法:{ $push: { <field>: <value1> }}
{
"data": {
"$push": {
"tags": {
"$each": ["tag1", "tag2", "tag3"]
}
}
}
}
$pop
删除数组尾部元素
语法:{ $pop: { <field>: <-1 | 1> }}
1 表示从数组尾部剔除 元素,-1 表示从数组头部剔除元素
{
"data": {
"$pop": {
"tags": 1
}
}
}
点操作符
云开发数据库支持点操作符表示法访问数组的元素、嵌套文档的字段
数组
"<array>.<index>"
如下面的数组,可以使用 contribs.2
获取 colors
数组的第三个元素 C
{
colors: [ "A", "B", "C" ]
}
嵌套文档
"<embedded document>.<field>"
如下面的文档,可以使用 address.city
获取 city
的值,使用 contact.phone.number
获取 number
的值
{
address: { city: "Sans" },
contact: { phone: { type: "cell", number: "111-222-3333" } }
}