跳到主要内容

API 接口

获取文档列表#

根据简单的排序、分组条件,获取某内容集合的文档数据

请求路径#

GET /{collectionName}/?limit={limit}&skip={skip}&fields={fields}&sort={sort}

响应体#

字段类型说明
requestIdString请求 ID
dataObject返回结果
codeString发生错误时的错误码
messageString发生错误时的错误信息
totalNumber文档总数量

响应示例

{  "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}

参数说明#

参数类型是否必填说明
docIdString内容文档 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 为更新的内容,如下面的示例,将 nameoldName 所有的内容, 更新namenewName,同时,query 也支持 Query Command

{  "query": {    "name": "oldName"  },  "data": {    "name": "newName"  }}

响应#

字段类型说明
updatedNumber更新成功的文档数量
matchedNumber符合条件的文档数量
upsert_idString替换更新 插入新 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 }  }}

响应#

字段类型说明
deletedNumber删除成功的文档数
{    "requestId": "23f416d4f8722",    "deleted": 1}

Query Command#

tip

下面仅列出了部分 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#

tip

下面仅列出了部分 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" } }}