mLab数据API

简单也说,你不用写后台服务,直接免费使用mLab的RESTful服务做CRUD纯前端应用。是不是想试一试了。且慢,您得先了解一下mLab数据API。mLab数据库可以通过两种方式应用程序访问。

第一种方法(强烈推荐):使用一个可用的驱动程序连MongoDB。如果使用的驱动程序,根本不需要使用mLab数据API。事实上,使用驱动程序能提供更好的性能、更好的安全性和更多的功能。

第二种方法:正如下面具体描述的,通过mLab的RESTful数据API连接。但请记住一个原则:只有在你不能使用MongoDB的驱动程序时才使用该方法。

每个mLab帐户都带有一个数据API(默认禁用),可用于访问属于该帐户的数据库、集合的文档。API暴露了你能使用MongoDB驱动完成的大部分操作,但只能通过HTTPS 来访问提供的RESTful接口。

此外,每个帐户都有自己的用于访问API的密钥。用户可以通过管理入口查看或重置API密钥,管理员用户还可以查看或重置该帐户直所有用户的API密钥。

API 认证

每一个API请求必须使用一个apikey查询参数。默认情况下,数据API的访问是禁用的,并且必须在获取API密钥之前启用。按照以下步骤启用数据API访问并获取API密钥:

  1. 登录mLab管理入口
  2. 在右上角点击你的用户名 (不是帐户名)打开用户中心页面。如果已在用户详情页,点击帐户用户区有你的用户名那行。
  3. 如果API密钥区的状态显示为 “Data API Access: Disabled”,请点击“Enable Data API access”按钮。
  4. 一旦能访问Data API,您当前的API密钥将显示在API密钥区域中。如下图:
  5. (可选项)如果您想更新当前API密钥,点击 ”Regenerate API key“按钮。

API Key
下面是一个完整资源URL的例子:

https://api.mlab.com/api/1/databases?apiKey=myAPIKey

基本URL路径

下面列出的所有API路径都使用下面的基本URL路径:
固定部分资源的网址:
https://api.mlab.com/api/1

API参考

注意mLab数据API使用严格模式下MongoDB扩展JSON来编码查询和文档。

数据库清单

GET /databases
GET /clusters/{cluster}/databases

集合清单

GET /databases/{database}/collections
如:https://api.mlab.com/api/1/databases/sample/collections?apiKey=myAPIKey

文档清单

GET /databases/{database}/collections/{collection}
如:https://api.mlab.com/api/1/databases/sample/collections/users?s={“name”: 1}&sk=0&l=10&apiKey=myAPIKey
可选参数:
[q=][&c=true][&f=][&fo=true][&s=][&sk=][&l=]
如:

可选参数: (MongoDB参考手册):

  • q=<query> – 特定的JSON查询筛选结果
  • c=true – 返回查询结果总数
  • f=<set of fields> – 为每个文档指定要包含或排除字段集 (1 – 包含;0 – 排除)
  • fo=true – 从结果集返回单个文档(类似使用mongo shell的findOne() 方法
  • s=<sort order> – 为特定的字段指定排序顺序(1- 升序; -1 – 降序)
  • sk=<num results to skip> – 在结果集指定要路过多少条记录;用于分页
  • l=<limit> – 指定记录数限制(默认为 1000)

新建集合

要创建一个新的集合,直接使用它就好了!和使用一个标准的驱动程序或shell一样,集合是通过使用它们隐式地创建的。一旦你POST你的第一个文档,你应该看到它出现在集合中。

插入文档

POST /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>

如:(使用jQuery)

$.ajax({
  url: 'https://api.mlab.com/api/1/databases/sample/collections/users?apiKey=myAPIKey'
  data: JSON.stringify({
    "name": "张三",
    "age": 30,
    "sex": 1
  }),
  type: "POST",
  contentType: "application/json"
}, function(res) {
  console.log(res);
});

如果你发布的文件包含一个_id字段,结果会会覆盖任何带有_id的已有文档。当您文档已包含一个_id值后,会被看作“insert”或“UPSERT”(下面讨论)而不是“create”或“insert”。

这种行为的后果之一:一个带有_id字段的特定文档,没有一种简单的API实现纯粹的“插入”。也就是说,拒绝修改已存在的带有_id字段的文档。POST会新增文档; PUT会修改文档。如果该方法不适用您的应用程,可考虑使用其他非_id字段,该字段可以索引并且唯一。

插入多个文档

若要向指定集合中添加多个文档,请在数据载荷中指定文档列表。请看jQuery的实现

POST /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>

$.ajax({url:'https://api.mlab.com/api/1/databases/sample/collections/users?apiKey=myAPIKey',
  data: JSON.stringify([
    {"name" : "曹操", "age": 45, "sex": 1},
    {"name" : "刘备", "age": 48, "sex": 1},
    {"name" : "孙尚湘", "age": 40, "sex": 0}
  ]),
  type: "POST",
  contentType: "application/json"
});

修改多个文档

在指定的集合中更新一个或多个文档,使用一个带有替代文档的PUT请求或在body中使用更新修改符(MongoDB参考):

PUT /databases/{database}/collections/{collection}
Content-Type: application/json
Body:

示例使用jQuery在"sex"= 0的文档中设置"age"值为30:

$.ajax({url: 'https://api.mlab.com/api/1/databases/sample/collections/users?apiKey=myAPIKey&q={"sex":0}',
  data: JSON.stringify({"$set" : {"age" : 30}}),
  type: "PUT",
  contentType: "application/json"
});

可选参数:
[q=<query>][&m=true][&u=true]

可选参数:

  • q=<query>:只更新匹配指定JSON查询的一个或多个文档
  • m=true:如果指定更新所有的文档集合或查询。默认情况下,只有一个文档被修改
  • u=true:“UPSERT”:插入定义在请求主体如果没有匹配指定的查询文档

所以你可以认为PUT即“更新”;加参数u=true就变成“更新或插入”,或者“UPSERT”的简称。

删除替换多个文档

若要替换某个集合的全部或全部内容,请在正文中使用PUT请求替换文档列表。q参数中的可选查询可用于替换集合的子集.。在正文中指定一个空列表相当于删除查询匹配的文档。

PUT /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>  

示例(使用jQuery):
$.ajax({ url: 'https://api.mlab.com/api/1/databases/sample/collections/users/?apiKey=myAPIKey',
  data: JSON.stringify([
    { "age": 30 },
    { "age": 32 },
    { "age": 50}
  ]),
  type: "PUT",
  contentType: "application/json"
});

可选参数:
[q=<query>]

可选参数:
q=:只替换匹配指定JSON查询的文档

查看、更新、删除单个文档

返回与指定_id的文档

GET /databases/{database}/collections/{collection}/{_id}

示例:
https://api.mlab.com/api/1/databases/sample/collections/users/585d7789c2ef160d17116ec5?apiKey=myAPIKey

修改匹配指定的_id的文档。如果没有匹配指定的_id文档存在,将创建一个新的文档。数据载荷应包含替换文件或更新修饰符(MongoDB参考):

PUT /databases/{database}/collections/{collection}/{_id}
Content-Type: application/json
Body: <JSON data> 
 
下面示例使用{ "sex" : 0 }替换匹配的文档(使用jQuery):
$.ajax({ url: 'https://api.mlab.com/api/1/databases/sample/collections/users/585d7789c2ef160d17116ec5?apiKey=myAPIKey',
  data: JSON.stringify({ "sex" : 0 }),
  type: "PUT",
  contentType: "application/json" 
});

下面示例在替换匹配的文档中设置"sex" = 0而不影响其它字段(使用jQuery):
$.ajax({ url: 'https://api.mlab.com/api/1/databases/sample/collections/users/585d7789c2ef160d17116ec5?apiKey=myAPIKey'
  data: JSON.stringify({"$set" : {"sex" : 0}}),
  type: "PUT",
  contentType: "application/json"
});

删除特定_id的文档:

DELETE /databases/{database}/collections/{collection}/{_id}

示例(使用cURL):
curl -X DELETE 'https://api.mlab.com/api/1/databases/sample/collections/users/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey

示例 (使用jQuery):
$.ajax({ url: "https://api.mlab.com/api/1/databases/sample/collections/users/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey",
  type: "DELETE",
  async: true,
  timeout: 300000,
  success: function (data) { },
  error: function (xhr, status, err) { } 
});

完整实例:https://github.com/szriafan/mlab-data-api.git

最终效果:https://szriafan.github.io/mlab-data-api/app

发表评论