简介

只要你的设备，你使用的语言能够发送HTTP请求，那么就可以用来和Bmob进行数据交互，你可以使用REST API做很多事情,比如:

• 一个移动网站可以通过C、Java、Python、PHP、C#等甚至任何语言来获取Bmob上的数据。
• 一个网站可以展示来自Bmob的数据。
• 你可以上传大量的数据，随后可以被一个移动App读取。
• 你可以下载最近的数据来进行你自定义的分析统计。
• 使用任何语言写的程序都可以操作Bmob上的数据。
• 如果你不再需要使用Bmob，你可以导出你所有的数据。

案例源码

这里提供一些开发者写的其他语言调用RestApi的源码或者核心代码。

JAVA访问RestApi：http://wenda.bmob.cn//?/question/51

PHP访问RestApi：http://docs.bmob.cn/data/PHP/a_faststart/doc/index.html

AS3.0访问RestApi：http://wenda.bmob.cn//?/question/193

请求格式

对于POST和PUT请求，请求的主体必须是JSON格式,而且HTTP请求头的 Content-Type 需要设置为 application/json 。

用户验证是通过HTTP请求头来进行的, X-Bmob-Application-Id 头表明你正在访问的是哪个App程序, 而 X-Bmob-REST-API-Key 头是用来授权的。在下面的例子中，你必须使用正确的key替换Your Application ID和Your REST API Key才能正常地发出Curl请求。

响应格式

对于所有REST API请求的响应内容体都是一个JSON对象.

一个请求是否成功是由HTTP状态码表明的， 一个2XX的状态码表示成功，而一个4XX表示请求失败。当一个请求失败时响应的主体仍然是一个JSON对象，但是总会包含code和error这两个字段，你可以用它们来进行调试。举个例子，如果保存一个对象的时候，尝试用不允许的Key，比如包含下划线的_name的话，就会得到如下请求失败的响应信息:

{
    "code": 105,
    "error": "invalid field name: bl!ng"
}

快速参考

API 访问需要在 https://api.bmob.cn 域名下，相对路径前缀 /1/ 表明现在使用的是第 1 版的 API。

对象快速参考

用户快速参考

文件管理快速参考

ACL和角色管理快速参考

app服务快速参考

数据表快速参考

其它功能快速参考

对象

对象格式

通过REST API保存数据需要将对象的数据通过JSON来编码，这个数据是无模式化的（Schema Less）,这意味着你不需要提前标注每个对象上有哪些Key，你只需要随意设置key-value对就可以，Rest API后端会存储它的。

举个例子，假设你正在记录一局游戏的最高分，一个简单的对象可能包含:

{
    "score": 1337,
    "playerName": "Sean Plott",
    "cheatMode": false
}

Key必须是字母和数字组成的字符串,Value可以是任何可以JSON编码的东西.

每个对象都有一个类名，你可以通过类名来区分不同的数据，例如，我们可以把游戏得分对象称之为GameScore.我们推荐你使用 NameYourClassesLikeThis 和 nameYourKeysLikeThis 这样的格式为你的类名和Key命名，这可以使你的代码看起来很漂亮.

当你从Bmob中获取对象时，一些字段会被自动加上: createdAt, updatedAt 和 objectId， 这些字段的名字是保留的，你不能自行设置它们，我们上面设置的对象在获取时应该是下面的样子.

{
    "score": 1337,
    "playerName": "Sean Plott",
    "cheatMode": false,
    "createdAt": "2011-08-20 02:06:57",
    "updatedAt": "2011-08-20 02:06:57",
    "objectId": "e1kXT22L"
}

createdAt和updatedAt都是UTC时间戳,以ISO 8601标准和毫秒级精度储存:YYYY-mm-dd HHss. objectId是一个string,在类中唯一表明了一个对象。

在REST API中class级的在一个资源上的操作只能根据类名来进行，例如，如果类名是GameScore，那么class的URL就是

https://api.bmob.cn/1/classes/GameScore

用户有一个特殊的类级的url:

https://api.bmob.cn/1/users

针对于一个特定对象的操作可以通过组织一个URL来做，例如，对GameScore中的一个objectId为e1kXT22L的对象的操作应使用如下URL:

https://api.bmob.cn/1/classes/GameScore/e1kXT22L

数据类型

到现在为止我们只使用了可以被标准JSON编码的值，Bmob移动客户端SDK库同样支持日期,地理位置数据和指针数据、关系型数据。在REST API中，这些值都被编码了，同时有一个”__type”字段来标识出它们所属的类型，所以如果你采用正确的编码的话就可以读或者写这些字段了。

Date类型包含了一个”iso”字段存储了一个UTC时间戳,以ISO 8601格式和毫秒级的精度来存储时间: YYYY-MM-DDTHHSS.MMMZ，或者 YYYY-MM-DDTHHSS

{
    "__type": "Date",
    "iso": "2011-08-21 18:02:52"
}

Date 与内置的 createdAt 字段和 updatedAt 字段相结合的时候特别有用，举个例子：为了找到在一个特殊时间创建的对象，只需要将Date编码在一个查询的where条件中:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"createdAt":{"$gte":{"__type":"Date","iso":"2011-08-21 18:02:52"}}}' \
    https://api.bmob.cn/1/classes/GameScore

File类型是在上传后返回的JSON数据再加一个Key为”__Type”:”File”, 用来保存到数据列为文件类型的值：

{
    "__type": "File",
    "group": "group1",
    "filename": "1.xml",
    "url": "M00/01/14/sd2lkds0.xml"
}

更新对象时可以为该对象保存上传后返回的文件信息：

curl -X PUT 
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"score":1337,"playerName":"Sean Plott","file":{"__type":"File","group":"group1","filename":"1.xml","url":"M00/01/14/sd2lkds0.xml"
}}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

Pointer 类型是在当前对象要指向另一个对象时使用，它包含了 className 和 objectId 两个作为一个指针正确指向的必填值.

{
  "__type": "Pointer",
  "className": "Game",
  "objectId": "DdUOIIIW"
}

指向用户对象的 Pointer 的 className 为_User, 前面加一个下划线表示开发者不能定义的类名, 而且所指的类是系统内置的。

Relation 类型被用在多对多的类型上, 移动端的库将使用 BmobRelation 作为值, 它有一个 className 字段表示目标对象的类名：

{
  "__type": "Relation",
  "className": "GameScore"
}

当使用查询时， Relation 对象的行为很像是 Pointer 的数组, 任何操作针对于 Pointer 的数组的 (除了 include) 都可以对 Relation 起作用.

当更多的数据类型被加入的时候, 它们都会采用 hashmap 加上一个 type 字段的形式, 所以你不应该使用type作为你自己的JSON对象的Key。

添加数据

请求描述

为了在Bmob上创建一个新的对象，应该向class的URL发送一个POST请求，其中内容体应该是包含对象本身的JSON格式。

请求

• url ：https://api.bmob.cn/1/classes/TableName
• method ：POST
• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  key1 : value1,
  key2 : value2,
  ...
}

成功时响应

• status: 201 Created

• location: https://api.bmob.cn/1/classes/TableName/objectId

• body:

{
    "createdAt": create date,
    "objectId": objectId
}

例子

例如，要创建如上例子中说的对象:

curl -X POST \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"score":1337,"playerName":"Sean Plott","cheatMode":false}' \
    https://api.bmob.cn/1/classes/GameScore

当创建成功时，响应的HTTP状态码的返回值是201 Created，而响应的HTTP头部中Location的值是表示刚创建的该对象的URL:

Status: 201 Created
Location: https://api.bmob.cn/1/classes/GameScore/e1kXT22L

响应的主体是一个JSON对象,包含新对象的objectId和createdAt时间戳：

{
    "createdAt": "2011-08-20 02:06:57",
    "objectId": "e1kXT22L"
}

更新数据

普通更新

请求描述

为了更改一个对象上已经有的数据，你可以发送一个PUT请求到对象相应的URL上，只有你指定的Key的值才会变更为新值，任何你未指定的Key的值都不会更改，所以你可以只更新对象数据的一个子集。

请求

• url ：https://api.bmob.cn/1/classes/

• TableName/objectId

• method ：PUT

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  key1 : value1,
  key2 : value2,
  ...
}

成功时响应

• status: 200 OK

• body:

{
  "updatedAt": "YYYY-mm-dd HH:ii:ss"
}

例子

我们来更改我们对象的一个score的字段:

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"score":73453}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

返回的JSON对象只会包含一个updatedAt字段，表明更新发生的时间：

{
    "updatedAt": "2011-08-21 18:02:52"
}

修改对象的某个值

如果存储的是JSON对象还可以通过以下形式，只修改JSON对象的特定键值，其body为：

{
  key1.keyOfJson : value1,
  key2.keyOfJson : value2,
  ...
}

如果你当前行有一列叫userAttibute,保存的是一个JSON 对象，比如是: {“name”:”John”, “gender”:”男”}，那么我们要修改这个对象的gender值就可以通过以下方式实现：

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"userAttibute.gender":"女"}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

原子计算器

另外，很多应用可能会有需要计数器的功能，比如某条信息被点赞多少次等。Bmob提供了非常便捷的方式来保证原子性的修改某一数值字段的值，body如下，其中value的正负均可。

其中请求的body为：

{
    key1:{"__op":"Increment","amount":value}
    ...
}

例如，如果需要让score每次增加1，而并不需要知道其当前的值，可以使用以下请求：

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"score":{"__op":"Increment","amount":1}}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

删除数据

请求描述

为了在Bmob上删除一个对象，可以发送一个DELETE请求到指定的对象的URL。

请求

• url ：https://api.bmob.cn/1/classes/TableName/objectId

• method ：DELETE

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

成功时响应

• status:200 OK

• body:

{
  "msg": "ok"
}

例子

删除GameScore下objectId为e1kXT22L的方法如下：

curl -X DELETE \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

删除字段的值

请求描述

可以在一个对象中删除一个字段，通过接口自定义的Delete操作

请求

• url ：https://api.bmob.cn/1/classes/TableName/objectId

• method ：PUT

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  key1:{"__op":"Delete"},
  key2:{"__op":"Delete"},
  ...
}

成功时响应

• status: 200 OK

• body:

{
  "updatedAt": "YYYY-mm-dd HH:ii:ss"
}

例子

如果要删除GameScore中objectId为e1kXT22L记录的playerName，可进行如下请求。

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"playerName":{"__op":"Delete"}}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

批量数据操作

请求描述

为了减少因为网络通讯次数太多而带来的时间浪费, Bmob提供批量(batch)操作，在一个请求中对多个普通对象进行添加(create)、更新(update)、删除(delete) 操作，上限为50个。在一个批量(batch)请求中每一个操作都有自己对应的方法、路径和主体, 这些参数可以代替你通常使用的HTTP方法. 这些操作会以发送过去的顺序来执行。

请求

• url ：https://api.bmob.cn/1/batch

• method ：POST

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  "requests": [
          {
            "method": "POST",
            "path": "/1/classes/TableName",
            "body": {
              key1: value1,
              key2: value2,
              ...
            }
          },
          {
            "method": "PUT",
            "token": "tokenValue"(具有ACL规则时),
            "path": "/1/classes/TableName/objectId",
            "body": {
              key1: value1,
              ...
            }
          },
          {
            "method": "DELETE",
            "token": "tokenValue"(具有ACL规则时),
            "path": "/1/classes/TableName/objectId"
          },
          ...
          ]
}

成功时响应

• status: 200 OK

• body:

[
(添加对象返回的信息)
  {
    "success": {
      "createdAt": YYYY-mm-dd HH:ii:ss,
      "objectId": "d746635d0b"
    }
  },
  (修改对象返回的信息)
  {
    "success": {
      "updatedAt": YYYY-mm-dd HH:ii:ss
    }
  },
  (删除对象返回的信息)
  {
    "success": {
      "msg": "ok"
    }
  }
]

例子

比如我们要创建一系列的 GameScore 的对象:

curl -X POST \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -H "Content-Type: application/json" \
  -d '{
        "requests": [
          {
            "method": "POST",
            "path": "/1/classes/GameScore",
            "body": {
              "score": 1337,
              "playerName": "Sean Plott"
            }
          },
          {
            "method": "POST",
            "path": "/1/classes/GameScore",
            "body": {
              "score": 1338,
              "playerName": "ZeroCool"
            }
          }
        ]
      }' 
  https://api.bmob.cn/1/batch

如果我们要修改用户表的某条记录或者删除某条记录，则用以下方法。

curl -X POST \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -H "Content-Type: application/json" \
  -d '{
        "requests": [
          {
            "method": "PUT",
            "token": "pnktnjyb996sj4p156gjtp4im",
            "path": "/1/users/51e3a334e4b0b3eb44adbe1a",
            "body": {
              "score": 999999
            }
          },
          {
            "method": "DELETE",
            "token": "pnktnjyb996sj4p156gjtp4im",
            "path": "/1/users/51a8a4d9e4b0d034f6159a35"
          }
        ]
      }' \
  https://api.bmob.cn/1/batch

查询

数据的查询可能是每个应用都会频繁使用的，它提供了多样的方法来实现不同条件的查询，同时它的使用也是非常的简单和方便。

查询单条数据

请求描述

当你创建了一个对象时，你可以通过发送一个HTTP GET请求到创建对象成功时返回的HTTP请求头中的Location的URL获取它的内容。

请求

• url ：https://api.bmob.cn/1/classes/TableName/objectId，可以加上include值，具体形式为：https://api.bmob.cn/1/classes/TableName/objectId?include=game

• method ：GET

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  key1 : value1,
  key2 : value2,
  ...
}

成功时响应

• status: 200 OK

• body:

{
    key1:value1,
    key2:value2,
    ...
}

例子

为了得到我们上面创建的对象:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

返回的主体是一个JSON对象，它包含所有用户提供的field，并且加上系统保留的createdAt,updatedAt和objectId三个Key的值：

{
    "score": 1337,
    "playerName": "Sean Plott",
    "cheatMode": false,
    "skills": [
        "pwnage",
        "flying"
    ],
    "createdAt": "2011-08-20 02:06:57",
    "updatedAt": "2011-08-20 02:06:57",
    "objectId": "e1kXT22L"
}

当获取的对象有指向其子对象的Pointer类型指针Key时，你可以加入inclue选项来获取指针指向的子对象。按上面的实例，如果GameScore对象有一个game的Key为Pointer类型，并指向了Game游戏对象，那么可以通过GameScore的game这个Key来获取指向的一个Game对象:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'include=game' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

返回的主体是一个JSON对象包含GameScore的所有Key，并有game这个Pointer的Key被扩展为一个Game对象:

{
    "score": 1337,
    "playerName": "Sean Plott",
    "cheatMode": false,
    "skills": [
        "pwnage",
        "flying"
    ],
    "game": {
        "type": "Object",
        "className": "Game",
        "name": "愤怒的小鸡",
    }
    "createdAt": "2011-08-20 02:06:57",
    "updatedAt": "2011-08-20 02:06:57",
    "objectId": "e1kXT22L"
}

查询多条数据

请求描述
为了一次获取多个对象，你可以通过发送一个GET请求到类的URL上，不需要任何URL参数。具体如下。

请求

• url ：https://api.bmob.cn/1/classes/TableName
• method ：GET
• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

成功时响应

• status: 200 OK
• body:

{
  "results": [
    {
      key1:value1,
      key2:value2,
      ...
    },
    {
      key1:value1,
      key2:value2,
      ...
    },
    ...

例子

下面就是简单地获取所有在GameScore类之中的对象:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    https://api.bmob.cn/1/classes/GameScore

返回的值就是一个JSON对象包含了results字段,它的值就是对象的列表:

{
    "results": [
    {
        "playerName": "Jang Min Chul",
        "updatedAt": "2011-08-19 02:24:17",
        "cheatMode": false,
        "createdAt": "2011-08-19 02:24:17",
        "objectId": "51c3ba67e4b0f0e851c16221",
        "score": 80075
    },
    {
        "playerName": "Sean Plott",
        "updatedAt": "2011-08-21 18:02:52",
        "cheatMode": false,
        "createdAt": "2011-08-20 02:06:57",
        "objectId": "e1kXT22L",
        "score": 73453
    }
    ]
}

怎么样，是不是很简单，而且查询的结果不需要任何处理，你直接使用即可。

条件查询

条件查询就是在查询所有数据的请求上通过where参数的形式对查询对象做出约束，只返回我们功期望返回的值。

where参数的值应该是JSON编码过的，就是说，如果你查看真正被发出的URL请求，它应该是先被JSON编码过，然后又被URL编码过。

使用where参数最简单的方式就是包含应有的key的值。举例说,如果我们想要得到Lily的记录，那该请求的URL为：

https://api.bmob.cn/1/classes/GameScore?where={"name":"Lily"}

这是未经编码前我们看到的url，我们需要对URL进行URL编码，编码的的结果为：

https://api.bmob.cn/1/classes/GameScore?where=%7B%22name%22:%22Lily%22%7D

不同的语言开发环境有不同的URL编码接口，如果是使用如Postman这类工具来进行测试的，可以使用一些在线的url编解码工具进行编码后再发送请求，这里推荐一个http://web.chacuo.net/charseturlencode

where的参数值除了上面的准确匹配外，还支持比较运算符的方式，除了给定一个确定值的方式，还可以提供一个hash中包含有key用于比较，where参数支持下面一些选项:

作为示例，为了获取score得分在[1000,3000]之间的对象，我们需要这样做:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"score":{"$gte":1000,"$lte":3000}}' \
    https://api.bmob.cn/1/classes/GameScore

为了获得score得分在10以下并且是一个奇数，我们需要这样做:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"score":{"$in":[1,3,5,7,9]}}' \
    https://api.bmob.cn/1/classes/GameScore

为了获得scoreArray得分包括数组中所有的值，如scoreArray是[1,3, 5, 7]就满足，是[1, 5,10]就不满足:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"scoreArray":{"$all":[1,3,5]}}' \
    https://api.bmob.cn/1/classes/GameScore

为了获取playerName不在列表中的GameScore对象们，我们可以:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"playerName":{"$nin":["Jonathan Walsh","Dario Wunsch","Shawn Simon"]}}' \
    https://api.bmob.cn/1/classes/GameScore

为了获取有分数的对象，我们应该用:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"score":{"$exists":true}}' \
    https://api.bmob.cn/1/classes/GameScore

为了获取没有分数的对象，用:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"score":{"$exists":false}}' \
    https://api.bmob.cn/1/classes/GameScore

你还可以使用模糊查询，支持PCRE正则表达式：

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"playerName":{"$regex":"smile.*"}}' \
    https://api.bmob.cn/1/classes/GameScore

注:模糊查询只对付费用户开放，付费后可直接使用。

如果您的查询条件某个列值要匹配另一个查询的返回值，举例有一个队伍(Team)保存了每个城市的得分情况且用户表中有一列为用户家乡(hometown), 您可以创建一个查询来寻找用户的家乡是得分大于0.5的城市的所有运动员， 就像这样查询:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"hometown":{"$select":{"query":{"className":"Team","where":{"winPct":{"$gt":0.5}}},"key":"city"}}}' \
    https://api.bmob.cn/1/users

反之查询Team中得分小于等于0.5的城市的所有运动员，构造查询如下：

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"hometown":{"$dontSelect":{"query":{"className":"Team","where":{"winPct":{"$gt":0.5}}},"key":"city"}}}' \
    https://api.bmob.cn/1/users

分页查询

你可以用limit和skip来做分页，limit的默认值是100，但是任何1到1000的值都是可选的，就是说，为了获取在400到600之间的对象:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'limit=200' \
    --data-urlencode 'skip=400' \
    https://api.bmob.cn/1/classes/GameScore

排序

你可以用order参数指定一个字段来排序，前面加一个负号的前缀表示降序，这样返回的对象会以score升序排列:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'order=score' \
    https://api.bmob.cn/1/classes/GameScore

而以下这样返回的对象会以score降序排列:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'order=-score' \
    https://api.bmob.cn/1/classes/GameScore

你可以用多个字段进行排序，只要用一个逗号隔开列表就可以，为了获取GameScore，以score的升序和name的降序进行排序:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'order=score,-name' \
    https://api.bmob.cn/1/classes/GameScore

复合查询

如果你想查询对象符合几种查询之一，你可以使用$or或$and操作符，带一个JSON数组作为它的值。例如，如果你想找到player赢了很多或者赢了很少，你可以用如下的方式:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"$or":[{"wins":{"$gt":150}},{"wins":{"$lt":5}}]}' \
    https://api.bmob.cn/1/classes/Player

查询今天内的数据，方式如下:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"$and":[{"createdAt":{"$gte":{"__type": "Date", "iso": "2014-07-15 00:00:00"}}},\
    {"createdAt":{"$lte":{"__type": "Date", "iso": "2014-07-15 23:59:59"}}}]}' \
    https://api.bmob.cn/1/classes/Player

因为createdAt updatedAt服务器自动生成的时间，在服务器保存的是精确到微秒值的时间，所以基于时间类型比较的值要加1秒。

任何在查询上的其他的约束都会对返回的对象生效，所以你可以用$or对其他的查询添加约束。

注意我们不会在 组合查询的子查询 中支持非过滤型的约束(例如:limit skip sort include)，但最外层的查询中是支持非过滤型约束的。

查询结果计数

如果你在使用limit，或者如果返回的结果很多，你可能想要知道到底有多少对象应该返回，而不用把它们全部获得以后再计数，此时你可以使用count参数。举个例子，如果你仅仅是关心一个特定的玩家玩过的游戏数量：

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"playerName":"Jonathan Walsh"}' \
    --data-urlencode 'count=1' \
    --data-urlencode 'limit=0' \
    https://api.bmob.cn/1/classes/GameScore

因为请求了count而且把limit设为了0，返回的值里面只有计数，results为空数组集。

{
    "results": [
    ],
    "count": 1337
}

如果有一个非0的limit的话，既会返回正确的results也会返回count的值。

查询指定列

你可以限定返回的字段，通过传入keys参数，值为用一个逗号分隔的字段名称列表，为了获取对象只包含score和playerName字段(还有特殊的内置字段比如objectId,createdAt和updatedAt)，请求如下：

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'keys=score,playerName' \
    https://api.bmob.cn/1/classes/GameScore

统计相关的查询

Bmob的统计查询，提供以下关键字或其组合的查询操作：

为避免和用户创建的列名称冲突，Bmob约定以上统计关键字（sum, max, min)的查询结果值都用 _(关键字)+首字母大写的列名 的格式，如计算玩家得分列名称为score总和的操作，则返回的结果集会有一个列名为_sumScore。average返回的列为 _avg+首字母大写的列名 ，有groupcount的情形下则返回_count。

以上关键字除了groupcount是传Boolean值true或false，having传的是和where类似的json字符串，但having只应该用于过滤分组查询得到的结果集，即having只应该包含结果集中的列名如 {"_sumScore":{"$gt":100}} ，其他关键字必须是字符串而必须是表中包含的列名，多个列名用,分隔。

以上关键字可以自由组合并可以与前面查询语句中的where, order, limit, skip等组合使用。

比如，GameScore表是游戏玩家的信息和得分表，有playerName(玩家名称)、score(玩家得分)等你自己创建的列，还有Bmob的默认列objectId, createdAt, updatedAt,那么我们现在举例如何使用以上的查询关键字来作这个表的统计。

计算总和

我们要计算GameScore表所有玩家的得分总和，sum后面只能拼接Number类型的列名，即要计算哪个列的值的总和，只对Number类型有效，多个Number列用,分隔，则查询如下：

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'sum=score' \
    https://api.bmob.cn/1/classes/GameScore

返回内容如下：

[
    {
        "_sumScore": 2398
    }   
]

分组计算总和

比如我们以创建时间按天统计所有玩家的得分，并按时间降序, groupby后面只能拼接列名，如果该列是时间类型，则按天分组，其他类型，则按确定值分组:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'sum=score&groupby=createdAt&order=-createdAt' \
    https://api.bmob.cn/1/classes/GameScore

返回内容如下：

[
    {
        "_sumScore": 2398,
        "createdAt": "2014-02-05"
    },
    {
        "_sumScore": 1208,
        "createdAt": "2014-01-01"
    },
]

多个分组并计算多个列的总和

比如我们以创建时间按天和按玩家名称分组统计所有玩家的得分1，得分2的总和，并按得分1的总和降序, groupby后面只能拼接列名，如果该列是时间类型，则按天分组，其他类型，则按确定值分组:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'sum=score1,score2&groupby=createdAt,playerName&order=-_sumscore1' \
    https://api.bmob.cn/1/classes/GameScore

返回内容如下：

[
    {
        "_sumScore1": 399,
        "_sumScore2": 120,
        "playerName": "John"
        "createdAt": "2014-02-05"
    },
    {
        "_sumScore1": 299,
        "_sumScore2": 250,
        "playerName": "Bily"
        "createdAt": "2014-02-05"
    },
    {
        "_sumScore1": 99,
        "_sumScore2": 450,
        "playerName": "John"
        "createdAt": "2014-02-01"
    },
]

分组计算总和并只返回满足条件的部分值

比如我们以创建时间按天统计所有玩家的得分，并只返回某天的总得分大于2000的记录，并按时间降序，having是用于过滤部分结果，其中的_sumScore是 _sum+首字母大写的列名 的格式表示是计算这个列的总和的值:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'sum=score&having={"_sumScore":{"$gt": 2000}}&groupby=createdAt&order=-createdAt' \
    https://api.bmob.cn/1/classes/GameScore

返回内容如下：

[
    {
        "_sumScore": 2398,
        "createdAt": "2014-02-05"
    },
]

分组计算总和并返回每个分组的记录数

比如我们以创建时间按天统计所有玩家的得分和每一天有多少条玩家的得分记录，并按时间降序:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'sum=score&groupby=createdAt&groupcount=true&order=-createdAt' \
    https://api.bmob.cn/1/classes/GameScore

返回内容如下：

[
    {
        "_sumScore": 2398,
        "_count": 10,
        "createdAt": "2014-02-05"
    },
    {
        "_sumScore": 100,
        "_count": 2,
        "createdAt": "2014-01-01"
    },
]

获取不重复的列值

比如我们获取表中所有的唯一的score:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'groupby=score' \
    https://api.bmob.cn/1/classes/GameScore

返回内容如下：

[
    {
        "score": 78
    },
    {
        "score": 89
    }
]

其他关键字

average(计算平均值)， max(计算最大值)，min(计算最小值)和sum查询语句是类似的，只用把上面的例子中的sum替换为相应的average, max, min就可以了。

BQL查询

我们还提供类 SQL 语法的 BQL 查询语言来查询数据，例如：

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'bql=select * from Player limit 0,100 order by name' \
  https://api.bmob.cn/1/cloudQuery

更多请参考 BQL 详细指南 。

BQL 还支持占位符查询，where 和 limit 子句的条件参数可以使用问号替换，然后通过 values 数组传入：

curl -X GET \
   -H "X-Bmob-Application-Id: Your Application ID" \
   -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'bql=select * from Player where name=? limit ?,? order by name' \
  --data-urlencode 'values=["dennis", 0, 100]'
  https://api.bmob.cn/1/cloudQuery

数组

为了存储数组型数据，Bmob提供了3种操作来原子性地更改一个数组字段:

Add 在一个数组字段的后面添加一些指定的对象(包装在一个数组内)

AddUnique 只会在原本数组字段中没有这些对象的情形下才会添加入数组，插入数组的位置不固定的

Remove 从一个数组字段的值内移除指定的数组中的所有对象

添加数组数据

请求描述

添加数据时添加一个数据字段。

请求

• url ：https://api.bmob.cn/1/classes/TableName

• method ：POST

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  key1:{"__op":"Add","objects":[value1,value2...]},
  ...
}

成功时响应

• status: 200 OK

• body:

{
“createdAt”: “YYYY-mm-dd HHss”,
“objectId”: objectId
}

例子

给GameScore添加一条记录其中一个字体为数组，包含一些技能，可进行如下请求:

curl -X POST \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"skill":{"__op":"Add","objects":["skill1","skill2"]}}' \
    https://api.bmob.cn/1/classes/GameScore

更新数组数据

普通更新

请求描述

数组对象生成后，还可以对其进行更新，往数组里面添加内容。

请求

• url ：https://api.bmob.cn/1/classes/TableName/objectId

• method ：PUT

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
   key1:{"__op":"AddUnique","objects":[value1,value2...]},
  ...
}

成功时响应

• status: 200 OK

• body:

{
  "updatedAt": "YYYY-mm-dd HH:ii:ss"
}

例子

如在GameScore的e1kXT22L再添加两个技能，并且只有在这两个技能不存在时才加入，则可以使用以下请求：

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"skills":{"__op":"AddUnique","objects":["flying","kungfu"]}}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

使用索引和对象key修改数组中的对象

请求描述

当数组中存储的是JSON对象时，可以使用该请求单独修改JSON对象中的某个值。

请求

• url ：https://api.bmob.cn/1/classes/TableName/objectId

• method ：PUT

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  key1.number.keyOfJson : value1,
  key2.number.keyOfJson : value2,
  ...
}

成功时响应

• status: 200 OK

• body:

{
  "updatedAt": "YYYY-mm-dd HH:ii:ss"
}

例子

比如你当前行有一列叫用户的工作经验projectExperiences，是一个Array数组列，里面包含了多个对象值：[{“name”:”项目名称”,”descr”:”项目描述”，”startTime”:”开始时间”，”endTime”:”结束时间”}, …]

那么我们要修改projectExperiences数组中第一个对象的name值：

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"projectExperiences.0.name":"项目名称2"}' \
    https://api.bmob.cn/1/users/e1kXT22L

删除数组数据

请求描述

请求

• url ：https://api.bmob.cn/1/classes/TableName/objectId

• method ：PUT

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
   key1:{"__op":"Remove","objects":[value1,value2...]},
  ...
}

成功时响应

• status: 200 OK

• body:

{
  "updatedAt": "YYYY-mm-dd HH:ii:ss"
}

例子

把GameScore里objectId为e1kXT22L对象的技能移除。

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"skills":{"__op":"Remove","objects":["flying","kungfu"]}}' \
    https://api.bmob.cn/1/classes/GameScore/e1kXT22L

查询数组数据

请求描述

请求

• url ：https://api.bmob.cn/1/classes/TableName

• method ：GET

• params:

//查找数组中含有特定值
where={arraykey1:value1,arraykey2:value2,...}
or
//查找数据组同时含有若干个值
where={"arrayKey":{"$all":[value1,value2,...]}}

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key

成功时响应

• status: 200 OK

• body:

{
  "results": [
    {
      key1:value1,
      key2:value2,
      ...
    },
    {
      key1:value1,
      key2:value2,
      ...
    },
    ...

例子

例如，可以查找Key的数组值中包含有2的对象:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"arrayKey":2}' \
    https://api.bmob.cn/1/classes/RandomObject

还同样可以使用”$all”操作符来找到类型为数组的Key的值中包含有2,3和4的对象:

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'where={"arrayKey":{"$all":[2,3,4]}}' \
    https://api.bmob.cn/1/classes/RandomObject

数据关联

关联对象

在程序设计中，不同类型的数据之间可能存在某种关系。分别是以下三种：

1. 一对一，比如车队给司机分车，1个司机对应1台车；
2. 一对多，比如1个作者会对应多篇贴子；
3. 多对多，比如1篇帖子会有多个喜欢的读者，而每个读者也会有多篇喜欢的帖子。
   前面的两种关系我们提供Pointer类型来表示，而最后一种关系我们使用Relation类型来表示

在下面的讲解中我们可能会使用到以下的两张表，其表结构如下：

_User

Post

Pointer的使用

Pointer可用于表示一对一及一对多的关系。

Pointer本质类似于指针，使用 className 和 objectId 来定位具体的对象。具体的操作如下。

添加Pointer

添加Pointer其实与普通的添加对象是一样的，使用的请求也是添加对象的接口，只是其中的 key-value对中的value的格式为

{
    "__type":"Pointer",
    "className":tableName,
    "objectId":objectId
}

例如，如果我们需要添加一篇帖子，并关联至其作者，可以采用以下请求：

curl -X POST \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -H "Content-Type: application/json" \
  -d '{ \
              "title": "how to user pointer", \              "user" : { \
              "__type":"Pointer", \
              "className":"_User", \
              "objectId":"DdUOIIIW" \
              } \
           }' \
  https://api.bmob.cn/1/classes/GameScore

删除Pointer

与删除普通列值一样，例如要删除帖子(Post)的作者，如下

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"author":{"__op":"Delete"}}' \
    https://api.bmob.cn/1/classes/Post/e1kXT22L

修改Pointer

与修改普通列值一样，只是新的值需要满足Pointer的格式，如下

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{ \
                  "title": "how to user pointer", \                  "user" : { \
                  "__type":"Pointer", \
                  "className":"_User", \
                  "objectId":"objectId" \ (新关联作者的objectId)
                  } \
           }' 
    https://api.bmob.cn/1/classes/Post/e1kXT22L

查询Pointer

在某些情况之下，你可能需要在一个查询之中返回关联对象的所有值，你可以通过传入字段名称到include参数中，多个字段名称用,间隔。比如，在查询Post时还想将其相关联的user对象取出来，如下

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'include=author' \
  https://api.bmob.cn/1/classes/Post

返回的user字段的值如下：

{
  "__type": "Object",
  "className": "_User",
  "objectId": "51e3a359e4b015ead4d95ddc",
  "createdAt": "2011-12-06T20:59:34.428Z",
  "updatedAt": "2011-12-06T20:59:34.428Z",
  "otherFields": "willAlsoBeIncluded"
}

而没有使用include时，返回的user字段值则是如下形式：

{
  "__type": "Pointer",
  "className": "_User",
  "objectId": "51e3a359e4b015ead4d95ddc"
}

你可以同样做多层的include, 这时要使用 “.” 号. 如果你要include一条评论(Comment)对应的帖子(Post)的作者(author)：

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'order=-createdAt' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'include=post.author' \
  https://api.bmob.cn/1/classes/Comment

如果你要构建一个查询, 这个查询要include多个 Pointer 类型的Key, 此时用逗号分隔Key名称列表即可。

另外，include 还可以只返回指定的keys，即 Pointer 类型的字段指向的表只返回指定的字段，举例如下：

建议大家使用以下方式，只返回需要的值，性能更好，流量更少

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'include=post[likes].author[username|email],user[username]' \
  https://api.bmob.cn/1/classes/Comment

post 指向的帖子表只返回likes字段，而author指向的用户表只返回username和email字段，user指向的用户表只返回username字段。

约束Pointer值查询

在查询当中，我们可以对字符串、数组、数字等进行约束，比如查询Post表时，我们可以指定只返回title以“a”开头的Post对象。那么Pointer能不能也进行约束呢？如下：

1.如果约束的是某个特定对象，即知道该对象的objectId，您可以用一个 where 参数查询, 自己使用 __type 构造一个 Pointer, 就像你构造其他数据类型一样。举例说, 如果每一条评论(Comment对象)有一个Key叫post，类型是Pointer，并且指向了一个具体的帖子(Post对象，用objectId表示一个帖子)，那么您可以使用下面的请求获取一个帖子的所有评论

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'where={"post":{"__type":"Pointer","className":"Post","objectId":"1dafb9ed9b"}}' \
  https://api.bmob.cn/1/classes/Comment

2.如果想要约束关联对象除objectId外的其它值，比如我想要返回所有指向的author指向的对象，其username都为Lily的Post对象，该如何做呢？我们可以使用 “$inQuery” 来完成，具体如下：

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'where= { \
                                  "author": { \
                                    "$inQuery": { \
                                      "where": { \
                                           "username": "Lily" \
                                      }, \
                                      "className": "_User" \
                                   } \
                                   } \
                            }' \
  https://api.bmob.cn/1/classes/Post

如果需求是不匹配查询条件的，比较要找username不是Lily的Post对象，只需要将 $inQuery 替换成 $notInQuery 即可。

Relation的使用

Relation可用于表示多对多的关系。其本质是一个Pointer的数组。具体的操作介绍如下。

添加Relation

添加 Relation 返回使用的也是添加对象的接口，对应的 key-value 对中的 value 需要满足以下格式

{
  key: {
    "__op": "AddRelation",
    "objects": [
      {
        "__type": "Pointer",
        "className": className,
        "objectId": objectId
      },
      {
        "__type": "Pointer",
        "className": className,
        "objectId": objectId
      }
    ]
  }
}

如需要给一个 Post 对象添加两个喜欢该 Post 的读者，可以使用以下方法。

curl -X PUT \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -H "Content-Type: application/json" \
  -d '{ "likes": { \
          "__op": "AddRelation", \
          "objects": [ \
            { \
             "__type": "Pointer", \
             "className": "_User", \
             "objectId": "z0lOxp1X" \
            }, \
            { \
             "__type": "Pointer", \
             "className": "_User", \
             "objectId": "MTzXDDDG" \
            } \
           ] \
        } \
      }' \
  https://api.bmob.cn/1/classes/Post/z0lOxp12

删除Relation

与普通的更新对象接口一样，只是需要使用特定的格式，具体如下：

{
  key: {
    "__op": "RemoveRelation",
    "objects": [
      {
        "__type": "Pointer",
        "className": className,
        "objectId": objectId
      },
      {
        "__type": "Pointer",
        "className": className,
        "objectId": objectId
      }
    ]
  }
}

如有读者取消了对某篇帖子的收藏，可以进行如下操作:

curl -X PUT \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -H "Content-Type: application/json" \
  -d '{ "likes": { \
          "__op": "RemoveRelation", \
          "objects": [ \
            { \
             "__type": "Pointer", \
             "className": "_User", \
             "objectId": "z0lOxp1X" \
            }
      }' \
  https://api.bmob.cn/1/classes/Post/z0lOxp2a

查询Relation

如果我们需要查询喜欢某篇帖子的所有作者，那么可以使用 $relatedTo，可以使用以下请求，与Pointer不同的是，此处我们直接查询的是_User表，$relatedTo 跟的是帖子的具体记录。

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'where={"$relatedTo":{"object":{"__type":"Pointer","className":"Post","objectId":"1dafb9ed9b"},"key":"likes"}}' \
  https://api.bmob.cn/1/users

约束Relation进行查询

跟Pointer一样，我们同样可以使用 $inQuery 和 $notInQuery 对Relation的指向的对象的某些属性进行约束。例如，如果需要找到 Lily 喜欢的所有帖子，可以使用以下请求：

curl -X GET \
  -H "X-Bmob-Application-Id: Your Application ID" \
  -H "X-Bmob-REST-API-Key: Your REST API Key" \
  -G \
  --data-urlencode 'where= { \
                                  "likes": { \
                                    "$inQuery": { \
                                      "where": { \
                                           "username": "Lily" \
                                      }, \
                                      "className": "_User" \
                                   } \
                                   } \
                            }' \
  https://api.bmob.cn/1/classes/Post

用户管理

很多跨平台和跨系统的应用都有一个统一的登录流程，Bmob通过REST API访问用户的账户让你实现该功能。

通常来说，用户这个类的功能与其他的对象是相同的，比如都没有限制模式(Schema Less)，User对象和其他对象不同的是一个用户必须有用户名(username)和密码(password)，密码会被自动地加密和存储。Bmob强制你username和email这两个Key的值必须是不重复的。

属性

Bmob默认会有几个特定的属性：
username: 用户的用户名（必需）。
password: 用户的密码（必需）。
email: 用户的电子邮件地址（可选）。

注册用户

请求描述

注册一个新用户与创建一个新的普通对象之间的不同点在于其username和password字段都是必要的，password字段会以与其他的字段不一样的方式处理，它在保存时会被加密而且永远不会被返回给任何来自客户端的请求。

在你的应用设置页面中，你可以向Bmob来请求认证邮件地址，这项设置启用了的话，所有用户在注册时填写email这个Key的值，并且邮箱有效的情况下，就会向这个邮箱地址发出一封邮件，邮件中会包含一个来自Bmob的邮箱验证的链接，当你的用户查收邮件并点击这个链接后，这个用户emailVerified的Key的值会置为True，你可以在emailVerified字段上查看用户的email是否已经通过验证了。

为了注册一个新的用户，需要向user路径发送一个POST请求，你可以加入一个甚至多个新的字段。

请求

• url ：https://api.bmob.cn/1/users

• method ：POST

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  "username" : username,
  "password" : password,
  key1:value1,
  key2:value2,
  ...
}

成功时响应

• status: 201 Created

• body:

返回的主体是一个JSON对象，包含objectId，表示唯一的用户, createdAt时间戳表示用户注册时间, sessionToken可以被用来认证更新或删除这名用户信息的请求。

{
    "createdAt": YYYY-mm-dd HH:ii:ss,
    "objectId": objectId,
    "sessionToken": sessionToken
}

例子

例如，创建一个有家庭电话字段的新用户:

curl -X POST \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"username":"cooldude6","password":"b_m7!-o8","phone":"415-392-0202"}' \
    https://api.bmob.cn/1/users

其返回值如下：

{
    "createdAt": "2011-11-07 20:58:34",
    "objectId": "Kc3M222J",
    "sessionToken": "pnktnjyb996sj4p156gjtp4im"
}

这里需要注意一点的是，有些时候你可能需要在用户注册时发送一封验证邮件，以确认用户邮箱的真实性。这时，你只需要登录自己的应用管理后台，在设置->邮件设置（下图）中把“邮箱验证”功能打开，Bmob云后端就会在注册时自动发动一封验证邮件给用户。

使用手机号码一键注册或登陆

请求描述

Bmob 支持让用户直接输入手机号码进行注册，如果手机号码存在则自动登陆。

请求

• url ： https://api.bmob.cn/1/users

• method ：POST

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

• body:

{
  mobilePhoneNumber:phoneNumber,
  smsCode:smsCode
  key1 : value1,
  key2 : value2,
  ...
}

其中 mobilePhoneNumber 就是手机号码，而 smsCode 是使用 请求短信验证码API发送到用户手机上的 6位验证码字符串。如果是新用户且不传入 username，默认用户名将是手机号码。

成功时响应

• status: 200 OK

• body:

{
  "username": username,
  "mobilePhoneNumber": mobilePhoneNumber,
  "mobilePhoneVerified": boolValue,
  "createdAt": YYYY-mm-dd HH:ii:ss,
  "updatedAt": YYYY-mm-dd HH:ii:ss,
  "objectId": objectId,
  "sessionToken": sessionToekn,
  key1:value1,
  key2:value2,
  ...
}

如果是第一次注册，将默认设置_User表的 mobilePhoneVerified 属性为 true。

例子

创建一个用户如下：

curl -X POST \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "Content-Type: application/json" \
    -d '{"mobilePhoneNumber":"185xxxxxxxx","smsCode":"6位短信验证码"}' \
    https://api.bmob.cn/1/users

返回值

{
  "username": "185xxxxxxxx",
  "mobilePhoneNumber": "185xxxxxxxx",
  "mobilePhoneVerified": true,
  "createdAt": "2011-11-07 20:58:34",
  "updatedAt": "2011-11-07 20:58:34",
  "objectId": "Kc3M222J",
  "sessionToken": "pnktnjyb996sj4p156gjtp4im"
}

登录用户

请求描述

你的用户注册之后，你需要让他们用自己的用户名和密码登录，为了做到这一点，发送一个HTTP GET请求到 /1/login ，加上username和password作为URL编码后的参数。

另外，username 支持传入_User表的username或email或mobilePhoneNumber字段的值，作为登录的扩展功能，以实现邮箱和密码、手机号和密码登录功能。

除了有用户名或邮箱或手机号码和密码登录的功能，Bmob 还支持使用手机号码和验证码一键快速登录的功能，而 smsCode 是使用 请求短信验证码API发送到用户手机上的 6位验证码字符串：

请求

• url ：https://api.bmob.cn/1/login

• params:

用户名密码登陆
"username"=username(也可以使用email或者mobilePhoneNumber)
"password"=password
手机号验证码
"mobilePhoneNumber"=phoneNumber
"smsCode":smsCode

• method ：GET

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

成功时响应

• status: 200 OK

• body:

{
  "username": username,
  "mobilePhoneNumber": mobilePhoneNumber,
  "mobilePhoneVerified": boolValue,
  "createdAt": YYYY-mm-dd HH:ii:ss,
  "updatedAt": YYYY-mm-dd HH:ii:ss,
  "objectId": objectId,
  "sessionToken": sessionToekn,
  key1:value1,
  key2:value2,
  ...
}

例子

使用用户名加密码登陆

curl -X GET
    \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'username=cooldude6' \
    --data-urlencode 'password=b_m7!-o8' \
    https://api.bmob.cn/1/login

使用手机号加验证码登陆

curl -X GET
    \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -G \
    --data-urlencode 'mobilePhoneNumber=185xxxxxxxx' \
    --data-urlencode 'smsCode=6位短信验证码' \
    https://api.bmob.cn/1/login

获取当前用户

请求描述

当注册一个用户后，你可以通过发送一个HTTP GET请求到用户注册成功时返回的HTTP请求头中的Location的URL获取用户的信息。比如，为了获取上面注册成功的用户

请求

• url ： https://api.bmob.cn/1/users/objectID

• method ：GET

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json

成功时响应

• status: 200 OK

• body:

{
    "username": username,
    "createdAt": YYYY-mm-dd HH:ii:ss,
    "updatedAt": YYYY-mm-dd HH:ii:ss,
    "objectId": objectId
}

例子

获取objectId为Kc3M222J的用户可以使用以下请求。

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    https://api.bmob.cn/1/users/Kc3M222J

更新用户

请求描述

在通常的情况下，我们都不希望用户去修改自己的数据，但可以通过认证让用户去做这件事，用户必须加入一个 X-Bmob-Session-Token 头部来请求这个更新操作，这个sessionToken在注册和登录时都会返回。该值的有效期为1年。

为了改动一个用户已经有的数据，需要对这个用户的URL发送一个HTTP PUT请求，任何你没有指定的key会保持不变，所以你可以只改动用户信息中的一部分，username和password可以更改，但是新的username不能重复。

请求

• url ：https://api.bmob.cn/1/users/objectId

• method ：PUT

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json
X-Bmob-Session-Token: sessionToken

• body:

{
  key1 : value1,
  key2 : value2,
  ...
}

成功时响应

• status: 200 OK

• body:

{
    "updatedAt": YYYY-mm-dd HH:ii:ss
}

例子

比如，如果我们想对 cooldude6 的电话做出一些改动，可以采用如下请求，

curl -X PUT \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "X-Bmob-Session-Token: pnktnjyb996sj4p156gjtp4im" \
    -H "Content-Type: application/json" \
    -d '{"phone":"415-369-6201"}' \
    https://api.bmob.cn/1/users/Kc3M222J

在更新用户信息时，如果用户邮箱有变更并且在管理后台打开了邮箱验证选项的话，Bmob云后端同样会自动发动一封验证邮件给用户。

删除用户

请求描述
为了在Bmob上删除一个用户，可以向用户的URL上发送一个DELETE请求，前提是你必须提供一个X-Bmob-Session-Token在Http请求头以便认证授权。

当然了，你也可以直接把MasterKey传入到X-Bmob-Master-Key中, 这个就可以实现在不需要提供SessionToken的情形下更新和删除用户了，但希望只在开发环境下使用，不要把MasterKey发布出去。

请求

• url ： https://api.bmob.cn/1/users/objectId

• method ：DELETE

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json
X-Bmob-Session-Token: sessionToken

成功时响应

• status: 200 OK

• body:

{
  "msg": "ok"
}

例子

删除objectId为g7y9tkhB7O的用户。

curl -X DELETE \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    -H "X-Bmob-Session-Token: pnktnjyb996sj4p156gjtp4im" \
    https://api.bmob.cn/1/users/g7y9tkhB7O

查询用户

请求描述

你可以一次获取多个用户，只要向用户的根URL发送一个GET请求，没有任何URL参数的话，可以简单地列出所有用户。

所有的对普通对象的查询选项都适用于对用户对象的查询，所以可以查看 查询 部分来获取详细信息。

User表是一个特殊的表，专门用于存储用户对象。在浏览器端，你会看到一个User表旁边有一个小人的图标。

请求

• url ： https://api.bmob.cn/1/users

• method ：GET

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key

成功时响应

• status: 200 OK

• body:

{
  {
    "results": [
        {
            "username": username,
            "createdAt": YYYY-mm-dd HH:ii:ss,
            "updatedAt": YYYY-mm-dd HH:ii:ss,
            "objectId": objectId,
            key1:value1,
            ...
        },
        {
            "username": username,
            "createdAt": YYYY-mm-dd HH:ii:ss,
            "updatedAt": YYYY-mm-dd HH:ii:ss,
            "objectId": objectId,
            key1:value1,
            ...
        },
        ...
    ]
}
}

例子

获取当前用户表的所有用户信息。

curl -X GET \
    -H "X-Bmob-Application-Id: Your Application ID" \
    -H "X-Bmob-REST-API-Key: Your REST API Key" \
    https://api.bmob.cn/1/users

密码重置

共提供了3种方法，分别是email重置、短信验证码重置、旧密码重置。

Eamil重置

请求描述

你可以使用这项功能，前提是用户将email与他们的账户关联起来，如果要重设密码，发送一个POST请求到 /1/requestPasswordReset, 同时在request的body部分带上email字段。

密码重置流程如下：

1. 用户输入他们的电子邮件，请求重置自己的密码。
2. Bmob向他们的邮箱发送一封包含特殊的密码重置连接的电子邮件，此邮件的模板可在Bmob后台中修改。
3. 用户根据向导点击重置密码连接，打开一个特殊的Bmob页面，输入一个新的密码。
4. 用户的密码已被重置为新输入的密码。

请求

• url ：https://api.bmob.cn/1/requestPasswordReset

• method ：POST

• header:

X-Bmob-Application-Id: Your Application ID
X-Bmob-REST-API-Key: Your REST API Key
Content-Type: application/json