REST API 简介

API 版本

最新稳定版本是 2.0

API 域名

REST 请求访问域名为:

https://api.maxleap.cn

域名后需要增加版本号,当前最新版本为 2.0,完整的请求路径示例:

https://api.maxleap.cn/2.0/classes/books

API 请求

请求格式

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

用户验证通过 HTTP header 来进行,X-ML-AppId 标明正在运行的是哪个应用,X-ML-APIKey 用来授权鉴定

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"content": "这是一条测试"}' \
      https://api.maxleap.cn/2.0/classes/test

响应格式

对于所有的请求,响应格式都是一个 JSON 对象。

一个请求是否成功是由 HTTP 状态码标明的。一个 2XX 的状态码表示成功,而一个 4XX 表示请求失败。当一个请求失败时响应的主体仍然是一个 JSON 对象,但是总是会包含 code 和 error 这两个字段,你可以用它们来进行调试。举个例子,如果尝试用非法的属性名来保存一个对象会得到如下信息:

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

通用错误码

错误码含义备注
1服务器内部问题
2第三方接口错误
100连接失败
101未找到请求资源
102查询语法错误
103缺少或者无效的类名
104缺少或者无效的ObjectId
105无效的键名
106无效的类型
107无效的json
108命令不可用
109未初始化
110更新语法错误
111类型不匹配
112无效的频道名
113未找到绑定的类
115推送配置错误
116数据太大
118无效的ObjectId
119操作受限
120未找到缓存
121无效的嵌套键
122无效的文件名
123无效的ACL
124超时
125无效的邮件地址
136禁止修改角色名称
137值重复
139无效的角色名称
140超过指标
141云代码错误
142角色未找到
143云代码未发布
160无效的会话标记
200缺少用户名
201缺少用户密码
202此用户名已被占用
203此邮箱已被占用
204缺少邮箱
205未找到邮箱
206缺少会话信息
207必须通过注册创建用户
208此账户已被关联
210用户密码不匹配
211未找到此用户
212此名称已被占用
213此id已被占用
214缺少一些字段
215邮箱未验证
216无效的发票
217数量已满
220设备类型错误
221任务状态错误
222任务格式化错误
225推送系统错误
226推送结束
239缺少短信验证码
240手机号码已经被注册
241验证码有误
242数量已满
243短信参数无效
250缺少关联的id
251无效的关联会话信息
252此服务不支持
253无效的authData
254手机号码未验证
301验证码错误
401未授权
503访问频率受限
601无效的请求
602远程的账单服务错误
603绑定卡错误
604账单权限错误
109999系统错误云代码
109998云代码异常云代码
109997访问云代码失败云代码
100000至少选择一个实例来部署云代码
100001你的云代码正在操作中,请稍后重试云代码
100002资源名称重复云代码
100003当前宿主机有实例正在运行云代码
100004无效的资源ID云代码
100005无效的宿主机IP云代码
100006无效的容器ID云代码
100007当前版本有实例正在运行,删除版本前请先停用它们云代码
100008至少选择一个实例来缩容云代码
100009当前版本还没有部署任何实例,扩容版本前请先部署云代码
100010当前版本已经部署云代码
100011无效的宿主机ID云代码
100012没有足够的内存资源云代码
100013无效的MAC地址云代码
100014没有足够的端口资源云代码
100015应用ID和MASTER_KEY不匹配云代码
100016缺少配置,你必须为你的应用指定applicationId(应用ID)云代码
100017检查云代码失败,当前上传的代码不匹配当前应用,请检查你的云代码配置applicationId(应用ID)云代码
100018缺少配置,你必须为你的应用指定applicationKey(Master Key)云代码
100019缺少配置,你必须为你的应用指定applicationName(应用名称)云代码
100020缺少配置,你必须为你的应用指定version(版本)云代码
100021缺少配置,你必须为你的应用指定lang(语言)云代码
100022无效的配置项lang(语言),不支持该语言云代码
100023缺少配置,你必须为你的应用指定javaMain(程序入口)云代码
100024当前版本还没有部署任何实例云代码
100025你必须指定版本请求比例云代码
100026版本请求比例无效,最多指定2个版本请求比例云代码
100027版本请求比例无效,比例总和必须为10云代码
100028版本号无效,该版本还没有运行云代码
100029解析配置失败,配置必须是符合JSON格式云代码
100030访问CloudCode实例服务失败,服务不可用云代码
100031获取CloudCode应用镜像失败云代码
100032构建CloudCode应用镜像失败云代码
100033上传CloudCode应用镜像失败云代码
100034创建CloudCode应用实例容器失败云代码
100035启动CloudCode应用实例容器失败云代码
100036检测到CloudCode应用实例容器处于非运行状态云代码
100037未检测到CloudCode应用实例容器状态云代码
100038上传云代码文件不能为空云代码
100039当前账号级别无法使用该功能,请提升账号等级云代码
100040容器ID不能为空云代码
100401无效的任务ID云代码
90000没有权限
90100无效的会话标识
90101过期的会话标识
90102应用id和key不匹配
90103应用id和会话标识不匹配

数据存储

API 列表

对象

URLHTTP功能
/classes/<className>POST创建对象
/classes/<className>/<objectId>GET获取对象
/classes/<className>/<objectId>PUT更新对象
/classes/<className>GET查询对象
/classes/<className>/<objectId>DELETE删除对象

文件

URLHTTP功能
/files/<filename>PUT上传文件
/filesDELETE删除单个文件

安装

URLHTTP功能
/installationsPOST上传安装数据
/installations/<objectId>GET获取安装数据
/installations/<objectId>PUT更新安装数据

API 详解

对象

对象格式

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

举个例子,假如我们要实现一个类似于电商 App,主要有三类数据:商品、账号、评论,一个商品可能包含下面几个属性:

    {
      "name": "真皮沙发",
      "price": 1000,
      "producer": "法国巴黎"
    }

Key(属性名)必须是字母和数字组成的字符串,Value(属性值)可以是任何可以 JSON 编码的数据。

每个对象都有一个类名,你可以通过类名来区分不同的数据。例如,我们可以把商品对象称之为 Product。

当你从 MaxLeap 中获取对象时,一些字段会被自动加上,如 createdAt、updatedAt 和 objectId。这些字段的名字是保留的,值也不允许修改。我们上面设置的对象在获取时应该是下面的样子:

    {
      "createdAt": "2016-04-21T08:37:30.774Z",
      "price": 1000,
      "name": "真皮沙发",
      "producer": "法国巴黎",
      "objectId": "5718914a169e7d0001a24dec",
      "updatedAt": "2016-04-21T08:37:30.774Z"
    }

createdAt 和 updatedAt 都是 UTC 时间https://api.maxleap.cn戳,以 ISO 8601 标准和毫秒级精度储存:YYYY-MM-DDTHH:MM:SS.MMMZ。objectId 是一个字符串,在类中可以唯一标识一个实例。 在 REST API 中,class 级的操作都是通过一个带类名的资源路径(URL)来标识的。例如,如果类名是 Post,那么 class 的 URL 就是:

https://api.maxleap.cn/2.0/classes/product

针对于一个特定的对象的操作可以通过组织一个 URL 来做。例如,对 Post 中的一个 objectId 为 5718914a169e7d0001a24dec 的对象的操作应使用如下 URL:

https://api.maxleap.cn/2.0/classes/product/5718914a169e7d0001a24dec

创建对象

为了在 MaxLeap 上创建一个新的对象,应该向 class 的 URL 发送一个 POST 请求,其中应该包含对象本身。例如,要创建如上所说的对象:

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{ "name": "真皮沙发","price": 1000,"producer": "法国巴黎"}' \
      https://api.maxleap.cn/2.0/classes/product

当创建成功时,HTTP 的返回是 200。 响应的主体是一个 JSON 对象,包含新的对象的 objectId 和 createdAt 时间戳。

    {"objectId":"5718999b169e7d0001a2520a","createdAt":"2016-04-21T09:12:59.585Z"}

获取对象

当你创建了一个对象时,你可以通过发送一个 GET 请求到返回的 header 的 Location 以获取它的内容。例如,为了得到我们上面创建的对象:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a

返回的主体是一个 JSON 对象包含所有用户提供的 field 加上 createdAt、updatedAt 和 objectId 字段:

    {
       "createdAt":"2016-04-21T09:12:59.585Z",
       "price":1000,"name":"真皮沙发",
       "ACL":{"creator":{"id":null,"type":"APIKey"}},
       "producer":"法国巴黎",
       "objectId":"5718999b169e7d0001a2520a",
       "updatedAt":"2016-04-21T09:12:59.585Z"
   }

更新对象

为了更改一个对象已经有的数据,你可以发送一个 PUT 请求到对象相应的 URL 上,任何你未指定的 key 都不会更改,所以你可以只更新对象数据的一个子集。例如,我们来更改我们对象的一个 content 字段:

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"producer": "中国东莞"}' \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a

返回的 JSON 对象会包含一个 updatedAt 字段和 number 字段,表明更新发生的时间和更新数量,这里number是1表示成功更新了这条记录:

    {"number":1,"updatedAt":"2016-04-21T09:19:25.585Z"}
计数器

为了存储一个计数器类型的数据, MaxLeap 提供对任何数字字段进行原子增加(或者减少)的功能,比如一个支付账户在同一时间可能进行支付、收款,如果我们每个客户端都先读取值计算后在写回去,毫无疑问,极其容易发生写覆盖,最终结果不准,这个时候,MaxLeap的原子操作就可以派上用场了

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
       -d '{"balance":{"__op":"Increment","amount":20}}' \
      https://api.maxleap.cn/2.0/classes/account/5718999b169e7d0001a2520a

这样就将对象里的 balance(表示账户余额)加 1,其中 amount 指定递增的数字大小,如果为负数,就变成递减。

数组

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

Add:在一个数组字段的后面添加一些指定的对象(包装在一个数组内) AddUnique:只会在数组内原本没有这个对象的情形下才会添加入数组,插入的位置不定。 Remove:从一个数组内移除所有的指定的对象 每一种方法都会有一个 key 是 objects 即被添加或删除的对象列表。举个例子,我们可以为每个商品增加一个 tags (标签)属性,然后往里面加入一些标签值:

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"tags":{"__op":"AddUnique","objects":["高端","大气"]}}' \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a
关系

为了更新 Relation 的类型,MaxLeap 提供特殊的操作来原子地添加和删除一个关系,所以我们可以像这样添加一个关系(某个用户关注了这个商品):

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"follows":{"__op":"AddRelation","objects":[{"__type":"Pointer","className":"_User","objectId":"5718a7c5169e7d0001a25911"}]}}' \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a

或者可以在一个对象中删除一个关系(某个用户取消关注这个商品)

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"follows":{"__op":"RemoveRelation","objects":[{"__type":"Pointer","className":"_User","objectId":"5718a7c5169e7d0001a25911"}]}}' \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a
按条件更新对象

假设我们要从某个账户对象 Account 的余额扣除一定金额,但是要求余额要大于等于被扣除的金额,那么就需要在更新的时候加上条件 balance >= amount,并通过 where 查询参数来实现:

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"balance":{"__op":"Decrement","amount": 100}}' \
      "https://api.leancloud.cn/1.1/classes/Account/558e20cbe4b060308e3eb36c?where=%7B%22balance%22%3A%7B%22%24gte%22%3A%2030%7D%7D"

可以看到 URL 里多了一个 where 查询参数,值是 %7B%22balance%22%3A%7B%22%24gte%22%3A%20100%7D%7D,其实是 {“balance”:{“$gte”: 100}} 做了 url encode 的结果。更多 where 查询的例子参见下文的 查询 一节。

删除对象

为了在 MaxLeap 上删除一个对象,可以发送一个 DELETE 请求到指定的对象的 URL,比如:

    curl -X DELETE \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520b

你也可以在一个对象中删除一个字段,通过 Delete 操作(注意:这时候 HTTP Method 还是 PUT):

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"follows":{"__op":"Delete"}}' \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a
按条件删除对象

为请求增加 where 参数即可以按指定的条件来删除对象:

    curl -X DELETE \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      "https://api.leancloud.cn/1.1/classes/product/5718999b169e7d0001a2520b?where=%7B%22price%22%3A%2010%7D"

可以看到 URL 里多了个参数 where,值是 %7B%price%22%3A%2010%7D,其实是 {“price”: 10} 做了 url encode 的结果,这里的意思是我们只有当这个商品的价格 price 为 10 才删除。更多 where 查询的例子参见 查询 一节。

批量操作

为了减少网络交互的次数太多带来的时间浪费,你可以在一个请求中对多个对象进行 create、update、delete 操作。

在一个批次中每一个操作都有相应的方法、路径和主体,这些参数可以代替你通常会使用的 HTTP 方法。这些操作会以发送过去的顺序来执行,比如我们要一次发布一系列的产品:

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{
         "requests": [
            {
              "method": "POST",
              "path": "/2.0/classes/product",
              "body":{ "name": "木质沙发","price": 1000,"producer": "荷兰"}
            },
            {
              "method": "POST",
              "path": "/2.0/classes/product",
              "body":{ "name": "藤椅","price": 100,"producer": "中国广东"}
            }
         ]
      }' \
      https://api.maxleap.cn/2.0/batch

我们对每一批次中所包含的操作数量(requests 数组中的元素个数)暂不设限,但考虑到云端对每次请求的 body 内容大小有限制,因此建议将每一批次的操作数量控制在 100 以内。

批量操作的响应会是一个列表,列表的元素数量和顺序与给定的操作请求是一致的。每一个在列表中的元素都有一个字段是 success 或者 error。

success 的值是通常是进行其他 REST 操作会返回的值:

    [
      {"createdAt":"2016-04-22T01:34:43.683Z","objectId":"57197fb3169e7d0001a2c44e"},
      {"createdAt":"2016-04-22T01:34:43.683Z","objectId":"57197fb3169e7d0001a2c44d"}
    ]

数据类型

到现在为止我们只使用了可以被标准 JSON 编码的值,在 REST API 中,这些值都被编码了,同时有一个 __type 字段(注意:前缀是两个下划线)来标示出它们的类型,所以如果你采用正确的编码的话就可以读或者写这些字段。

Date 类型包含了一个 iso 字段,其值是一个 UTC 时间戳,以 ISO 8601 格式和毫秒级的精度来存储的时间值,格式为:YYYY-MM-DDTHH:MM:SS.MMMZ:

    {
      "__type": "Date",
      "iso": "2015-06-21T18:02:52.249Z"
    }

MaxLeap CloudData 内置的 createdAt 字段和 updatedAt 字段就是Date类型,举例:找出大于等于某个时间段发布的产品:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"createdAt":{"$gte":{"__type":"Date","iso":"2016-06-21T18:02:52.249Z"}}}' \
      https://api.maxleap.cn/2.0/classes/product

Byte 类型包含了一个 base64 字段,这个字段是一些二进制数据编码过的 base64 字符串。base64 是 MIME 使用的标准,不包含空白符:

    {
      "__type": "Bytes",
      "base64": "5b6I5aSa55So5oi36KGo56S65b6I5Zac5qyi5oiR5Lus55qE5paH5qGj6aOO5qC877yM5oiR5Lus5bey5bCGIExlYW5DbG91ZCDmiYDmnInmlofmoaPnmoQgTWFya2Rvd24g5qC85byP55qE5rqQ56CB5byA5pS+5Ye65p2l44CC"
    }

Pointer 类型是用来设定 CloudData Object 作为另一个对象的值时使用的,它包含了 className 和 objectId 两个属性值,用来提取目标对象:

    {
      "__type": "Pointer",
      "className": "_User",
      "objectId": "5718998d169e7d0001a25203"
    }

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

Relation 类型被用在多对多的类型上,它有一个 className 字段表示目标对象的类名.

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

在进行查询时,Relation 对象的行为很像是 Pointer 的数组,任何针对于 pointer 数组的操作(include 除外)都可以对 Relation 起作用。

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

查询

基础查询

通过发送一个 GET 请求到类的 URL 上,不需要任何 URL 参数,你就可以一次获取多个对象。下面就是简单地获取所有产品:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      https://api.maxleap.cn/2.0/classes/product

返回的主体是一个 JSON 对象列表:

    {
      "results": [
        {
          "createdAt": "2016-04-21T08:37:30.774Z",
          "image": {
            "__type": "File",
            "name": "zcf-00c51b9d-3006-4877-ac95-012a9db82fa4.png",
            "url": "https://cscdn.maxleap.cn/2.0/download/NTY5ZDg0YTAxNjllN2QwMDAxMmM3YWZl/zcf-00c51b9d-3006-4877-ac95-012a9db82fa4.png"
          },
          "price": 1000,
          "name": "真皮沙发",
          "ACL": {
            "creator": {
              "id": null,
              "type": "APIKey"
            }
          },
          "produce": "法国巴黎",
          "objectId": "5718914a169e7d0001a24dec",
          "updatedAt": "2016-07-21T05:29:34.779Z"
        },
        {
          "createdAt": "2016-04-21T09:12:45.043Z",
          "image": {
            "__type": "File",
            "name": "zcf-739fa899-0aca-423a-82b1-dbca564a439b.png",
            "url": "https://cscdn.maxleap.cn/2.0/download/NTY5ZDg0YTAxNjllN2QwMDAxMmM3YWZl/zcf-739fa899-0aca-423a-82b1-dbca564a439b.png"
          },
          "price": 1000,
          "name": "真皮沙发",
          "ACL": {
            "creator": {
              "id": null,
              "type": "APIKey"
            }
          },
          "produce": "法国巴黎",
          "objectId": "5718998d169e7d0001a25203",
          "updatedAt": "2016-07-21T05:30:26.370Z"
        }
      ]
    }
查询约束

通过 where 参数的形式可以对查询对象做出约束。

where 参数的值应该是 JSON 编码过的。就是说,如果你查看真正被发出的 URL 请求,它应该是先被 JSON 编码过,然后又被 URL 编码过。最简单的使用 where 参数的方式就是包含应有的 key 和 value。

查询所有价格为100的商品。

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"price":100}' \
      https://api.maxleap.cn/2.0/classes/product

返回的结果集是一个 JSON 对象列表:

    {
      "results": [
        {
          "createdAt": "2016-04-22T01:34:43.683Z",
          "price": 100,
          "name": "藤椅",
          "producer": "中国广东",
          "objectId": "57197fb3169e7d0001a2c44d",
          "updatedAt": "2016-04-22T01:34:43.683Z"
        }
      ]
    }

除了完全匹配一个给定的值以外,where 也支持比较的方式。where 参数支持下面一些选项:

Key操作
$lt小于
$lte小于等于
$gt大于
$gte大于等于
$ne不等于
$in包含
$nin不包含
$exists这个Key有值
$select匹配另一个查询的返回值
$dontSelect排除另一个查询的返回值
$all包括所有的给定的值

例如,为了获取在 2016-04-22 前创建的商品,我们应该这样请求:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"createdAt":{"$lt":{"__type":"Date","iso":"2016-04-22T00:00:00.000Z"}}}' \
      https://api.maxleap.cn/2.0/classes/product

求价格低于1000,并且产地是荷兰的产品:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"price":{"$lt":1000}, "produce":"荷兰"}' \
      https://api.maxleap.cn/2.0/classes/product

产地不是荷兰的产品:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"produce": {"$ne": "荷兰"}}' \
      https://api.maxleap.cn/2.0/classes/product

我们假如__User对象有一个hometown字段,现在我们要找出产地是该用户家乡的产品,我们可以这样:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"produce": {"$select":{"query":{"className":"_User","where":{"objectId":"55a39634e4b0ed48f0c1845c"}, "key":"hometown"}}}}' \
      https://api.maxleap.cn/2.0/classes/product

你可以用 order 参数来指定一个字段来排序,前面加一个负号的前缀表示逆序。这样返回的微博会按发布时间呈升序排列:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'order=createdAt' \
      https://api.maxleap.cn/2.0/classes/product

排序字段加一个减号程降序排列:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'order=-createdAt' \
      https://api.maxleap.cn/2.0/classes/product

当然了,你还可以用多个字段排序

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'order=-createdAt, produce' \
      https://api.maxleap.cn/2.0/classes/product

你可以用 limit 和 skip 来做分页。limit 的默认值是 100,最大是2000, 在 1 到 2000 范围之外的都强制转成默认的 100。比如为了获取排序在 100 到 500 之间的产品:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'skip=100' \
      --data-urlencode 'limit=400' \
      https://api.maxleap.cn/2.0/classes/product

你可以限定返回的字段通过传入 keys 参数和一个逗号分隔列表。为了返回对象只包含 produce、name 和 price 字段(还有特殊的内置字段比如 objectId、createdAt 和 updatedAt都是默认返回的)

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'skip=100' \
      --data-urlencode 'limit=400' \
      --data-urlencode 'keys=produce,name,price' \
      https://api.maxleap.cn/2.0/classes/product

keys 还支持反向选择,也就是不返回某些字段,字段名前面加个减号即可,比如我不想查询返回 detail字段:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'skip=100' \
      --data-urlencode 'limit=400' \
      --data-urlencode 'keys=-detail' \
      https://api.maxleap.cn/2.0/classes/product
对数组的查询

arrayKey 字段是一个数组类型,你可以使用 $all 操作符来找到 arrayKey 的值中有 1、4 和 7 的对象:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"arrayKey":{"$all":[1,4,7]}}' \
      https://api.maxleap.cn/2.0/classes/TestObject
关系查询

有几种方式来查询对象之间的关系数据。如果你想获取对象,而这个对象的一个字段对应了另一个对象,你可以用一个 where 查询,自己构造一个 Pointer,和其他数据类型一样。例如,每个用户可能有很多订单,我们可以为每一个 Order 保存一个User对象,获取用户下所有订单:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"user":{"__type":"Pointer","className":"__User","objectId":"558e20cbe4b060308e3eb36c"}}' \
      https://api.maxleap.cn/2.0/classes/Order

user 字段是一个Pointer类型,指向__User类

如果你想获取对象,这个对象的一个字段指向的对象需要另一个查询来指定,你可以使用 $inQuery 操作符。注意 limit 的默认值是 100 且最大值是 2000,这个限制同样适用于内部的查询,所以对于较大的数据集你可能需要细心地构建查询来获得期望的结果。

例如,我们想要有头像的用户订单列表

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'where={"user":{"$inQuery":{"where":{"avatar":{"$exists":true}},"className":"__User"}}}' \
      https://api.maxleap.cn/2.0/classes/Order

有时候,你可能需要在一个查询之中返回多种类型,你可以通过传入字段到 include 参数中。比如,我们要获取最新的10个订单,而你想同时得到它们关联的用户信息:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'order=-createdAt' \
      --data-urlencode 'limit=10' \
      --data-urlencode 'include=user' \
      https://api.maxleap.cn/2.0/classes/Order

你可以同样做多层的 include,这时要使用点号(.)。如果你要 include 一个 Order 对应的 User 对应的 Address对象:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
      --data-urlencode 'order=-createdAt' \
      --data-urlencode 'limit=10' \
      --data-urlencode 'include=user.address' \
      https://api.maxleap.cn/2.0/classes/Order
对象计数

如果你在使用 limit,或者如果返回的结果很多,你可能想要知道到底有多少对象应该返回,而不用把它们全部获得以后再计数,此时你可以使用 count 参数。举个例子,如果你仅仅是关心一个某个用户有多少个订单:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -G \
        --data-urlencode 'count=1' \
        --data-urlencode 'limit=0' \
      https://api.maxleap.cn/2.0/classes/Order

因为这个 request 请求了 count 而且把 limit 设为了 0,返回的值里面只有计数,没有 results:

    {
      "results": [

      ],
      "count": 7
    }

如果有一个非 0 的 limit 的话,则既会返回 results 也会返回 count。

文件

上传文件

上传文件到 MaxLeap 通过 PUT 请求,注意必须指定文件的 content-type,例如上传一个文本文件 hello.txt 包含一行字符串:

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -d '[object ArrayBuffer]' "https://api.maxleap.cn/2.0/files/0.jpeg"

文件上传成功后,返回 201 Created 的应答和创建的文件对象:

    { 
      "name":"zcf-416e3066-70b3-439a-afca-55fe3ed50195.jpeg",
      "hash":null,"createTime":1461296757167,"region":"cn-north-1",
      "uid":null,"url":"cscdn.maxleap.cn/2.0/download/NTY5ZDg0YTAxNjllN2QwMDAxMmM3YWZl/zcf-416e3066-70b3-439a-afca-55fe3ed50195.jpeg",
      "size":20,
      "contentType":null
    }

其中 url 就是文件下载链接,objectId 是文件的对象 id,name 就是上传的文件名称。

关联文件到对象

一个文件上传后,你可以关联该文件到某个 MLObject 对象上:

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"image":{"__type":"File","name":"zcf-8a953de2-06bc-4210-a4c2-e5c3a7c16b7e.jpeg","url":"https://cscdn.maxleap.cn/2.0/download/NTY5ZDg0YTAxNjllN2QwMDAxMmM3YWZl/zcf-8a953de2-06bc-4210-a4c2-e5c3a7c16b7e.jpeg"}}' \
      https://api.maxleap.cn/2.0/classes/product/5718999b169e7d0001a2520a

删除文件

删除文件通过 DELETE 请求,注意头信息需要指定文件的 X-ML-Fid , X-ML-Fid就是创建文件时返回的 name 字段,需要用MasterKey,例如删除上面新建的文件 zcf-8a953de2-06bc-4210-a4c2-e5c3a7c16b7e.jpeg :

    curl -X DELETE \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-MasterKey: TzZhQ1NJSS1WUmdFNUp1UTdISHVXXX" \
      -H "X-ML-Fid: zcf-8a953de2-06bc-4210-a4c2-e5c3a7c16b7e.jpeg" \
      "https://api.maxleap.cn/2.0/files"

文件上传成功后,返回 204 Deleted 。

安装

上传安装数据

一个安装对象表示了一个你的在手机上被安装的 app。

字段描述
channels数组,可选,表示这个安装对象的频道列表。
deviceToken由 Apple 生成的字符串标志,在 deviceType 为 iOS 上的设备是必须的,而且自对象生成开始就不能改动,对于一个 app 来说也是不可重复的。
deviceType必须被设置为"ios"、"android"、"wp"、"web"中的一种,而且自这个对象生成以后就不能变化。
installationId由 MaxLeap 生成的字符串标志,而且如果 deviceType 是 android 的话是一个必选字段,如果是 iOS 的话则可选。它只要对象被生成了就不能发生改变,而且对一个 app 来说是不可重复的。
timeZone字符串,表示安装的这个设备的系统时区。

创建一个安装对象时,deviceToken或者installationId必选其中一个,MaxLeap通过installationId和deviceToken来区分不同的安装

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{
              "deviceType": "ios",
              "installationId": "a2188f955d1a4a968ee40e6952b05407",
              "deviceId": "o09f93f6996123c1c2d3d8b9639201be783207360",
              "channels": [
                ""
              ]
            }' \
      https://api.maxleap.cn/2.0/installations

当创建成功后,返回的 body 是一个 JSON 对象,包括了 objectId 和 createdAt 这个创建对象的时间戳。

    {"objectId":"571d9d76169e7d0001a4317b","createdAt":"2016-04-25T04:30:46.349Z"}

获取安装对象

你可以通过 GET 方法请求创建的时候 Location 表示的 URL 来获取 Installation 对象。比如,获取上面的被创建的对象:

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      https://api.maxleap.cn/2.0/installations/571d9d76169e7d0001a4317b

返回的 JSON 对象所有用户提供的字段,加上 createdAt、updatedAt 和 objectId 字段:

    {
      "deviceType":"ios",
      "createdAt":"2016-04-25T04:30:46.349Z",
      "channels":[""],
      "ACL":
         {"creator":{"id":null,"type":"APIKey"}},
     "installationId":"a2188f955d1a4a968ee40e6952b05407",
     "deviceId":"o09f93f6996123c1c2d3d8b9639201be783207360",
     "objectId":"571d9d76169e7d0001a4317b",
     "updatedAt":"2016-04-25T04:30:46.349Z"
    }

更新安装对象

安装对象可以向相应的 URL 发送 PUT 请求来更新。例如,更新安装的语言:

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{
              "language": "en"
            }' \
      https://api.maxleap.cn/2.0/installations/571d9d76169e7d0001a4317b

错误码

参考 通用错误码

FAQ

补充说明

账号服务

API 列表

URLHTTP功能
/usersPOST用户注册
/loginGET用户登录
/logoutGET用户退出登录
/users/<objectId>GET获取用户
/users/<objectId>PUT更新用户
/usersGET查询用户
/users/<objectId>DELETE删除用户
/updatePasswordPOST更新密码,要求输入旧密码
/requestPasswordResetPOST请求密码重设
/requestLoginSmsCodePOST获取手机登录验证码
/loginByMobilePhonePOST使用“手机号码"和"验证码"登录

API 详解

用户注册

注册一个新用户与创建一个新的普通对象之间的不同点在于 username 和 password 字段必填。

为了注册一个新的用户,需要向 user 路径发送一个 POST 请求,你可以加入一个新的字段,例如,创建一个新的用户有一个电话号码:

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"username":"hitest","password":"hitest123","phone":"13587878799"}' \
      https://api.maxleap.cn/2.0/users

当创建成功时,HTTP 的返回是 200。 响应的主体是一个 JSON 对象,包含新的对象的 objectId , createdAt 时间戳,sessionToken 可以被用来认证这名用户随后的请求。

    {
      "username": "hitest",
      "phone": "13587878799",
      "lastLoginTime": 1472175866398,
      "enabled": true,
      "objectId": "57bf9efa1c5de20009e0b27b",
      "createdAt": "2016-08-26T01:44:26.424Z",
      "sessionToken": "NJT-W5xCdxUFtyD98r_fU58o1eBrLhHmmD3KTDeJ2lA"
    }

用户登录

用自己的用户名和密码登录。发送一个 GET 请求到 /2.0/login,加上 username 和 password 作为参数。

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      https://api.maxleap.cn/2.0/login?username=hitest&password=hitest123

返回的主体是一个 JSON 对象包括所有除了 password 以外的自定义字段。它同样包含了 createdAt、updateAt、objectId 和 sessionToken 字段。

    {
      "lastLoginTime": 1472176437185,
      "createdAt": "2016-08-26T01:53:57.190Z",
      "phone": "13587878799",
      "sessionToken": "1ohbwr6l1aZzGnhWstIRJPNcW5BrLxHmpK0CQmhDvSc",
      "enabled": true,
      "objectId": "57bfa135b0d8500007e2ac67",
      "username": "hitest",
      "updatedAt": "2016-08-26T01:53:57.195Z"
    }

用户退出登录

用自己的用户名和密码登录。发送一个 GET 请求到 /2.0/logout,头里包含 X-ML-Session-Token。

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-Session-Token: 1ohbwr6l1aZzGnhWstIRJHxr6hBrMxHmmD3KTDeJ2lA" \
      -H "Content-Type: application/json" \
      https://api.maxleap.cn/2.0/logout

返回的主体是一个 JSON 对象包括所有除了 password 以外的自定义字段。它同样包含了 createdAt、updateAt、objectId 和 sessionToken 字段。

    {
      "success": true
    }

获取用户信息

发送一个 GET 请求到 URL 以获取用户的账户信息,返回的内容就是当创建用户时返回的内容。参数UserId就是创建和登录时返回的 objectId 。

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-Session-Token: 1ohbwr6l1aZzGnhWstIRJL9ydsBrNBHmmD3KTDeJ2lA" \
      -H "Content-Type: application/json" \
      https://api.maxleap.cn/2.0/users/57bfa135b0d8500007e2ac67

返回的主体是一个 JSON 对象包括用户信息相关字段。

    {
      "lastLoginTime": 1472178497581,
      "createdAt": "2016-08-26T01:53:57.190Z",
      "phone": "13587878799",
      "ACL": {
        "creator": {
          "id": "57bfa135b0d8500007e2ac67",
          "type": "AppUser"
        }
      },
      "enabled": true,
      "objectId": "57bfa135b0d8500007e2ac67",
      "username": "hitest",
      "updatedAt": "2016-08-26T02:28:17.581Z"
    }

修改用户密码

发送一个 GET 请求到 URL 以获取用户的账户信息,返回的内容就是当创建用户时返回的内容。参数UserId就是创建和登录时返回的 objectId 。 password是原密码,newPassword是新密码。

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-Session-Token: 1ohbwr6l1aZzGnhWstIRJL9ydsBrNBHmmD3KTDeJ2lA" \
      -H "Content-Type: application/json" \
      -d '{"password":"hitest123","newPassword":"hitest123"}' \
      https://api.maxleap.cn/2.0/updatePassword

返回的主体是一个 JSON 更新成功时返回200。

    {
      "number": 1,
      "updatedAt": "2016-08-26T02:35:05.267Z"
    }

更改用户信息

为了改动一个用户已经有的数据,需要对这个用户的 URL 发送一个 PUT 请求。任何你没有指定的 key 都会保持不动,比如更新手机信息。

    curl -X PUT \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-Session-Token: 1ohbwr6l1aZzGnhWstIRJL9ydsBrNBHmmD3KTDeJ2lA" \
      -H "Content-Type: application/json" \
      -d '{"phone":"133333333333"}' \
      https://api.maxleap.cn/2.0/users/57bfa135b0d8500007e2ac67

返回的主体是一个 JSON 更新成功时返回200。

    {
      "number": 1,
      "updatedAt": "2016-08-26T02:35:05.267Z"
    }

查询用户

_User表的查询权限是关闭的,需要用MasterKey查询,通常用在云代码和云容器中。MasterKey不能直接暴露出去。

    curl -X GET \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-MasterKey: 你的MasterKey" \
      -H "Content-Type: application/json" \
      https://api.maxleap.cn/2.0/users

返回的主体是用户列表, JSON 格式,查询成功时返回200。

    {
      "results": [
        {
          "lastLoginTime": 1472178497581,
          "createdAt": "2016-08-26T01:53:57.190Z",
          "phone": "133333333333",
          "ACL": {
            "creator": {
              "id": "57bfa135b0d8500007e2ac67",
              "type": "AppUser"
            }
          },
          "enabled": true,
          "objectId": "57bfa135b0d8500007e2ac67",
          "username": "hitest",
          "updatedAt": "2016-08-26T02:46:54.838Z"
        }
      ]
    }

删除用户

删除权限是关闭的,需要用MasterKey查询,通常用在云代码和云容器中。MasterKey不能直接暴露出去。

    curl -X DELETE \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-MasterKey: 你的MasterKey" \
      -H "Content-Type: application/json" \
      https://api.maxleap.cn/2.0/users/57bfb8771c5de20009e0cd97

返回的主体是用户列表, JSON 格式,查询成功时返回200。

    {
      "number": 1
    }

申请重置密码

申请重置密码,会发送邮件到指定邮箱。

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "Content-Type: application/json" \
      -d '{"email":"test@maxleap.com"}
      https://api.maxleap.cn/2.0/requestPasswordReset

返回的主体是用户列表, JSON 格式,查询成功时返回200。

    {
      "success": true
    }

获取手机登录/注册验证码

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"mobilePhone":"你的手机号"}
      https://api.maxleap.cn/2.0/requestLoginSmsCode

发送成功时返回200。

    {"success":true}

用手机和验证码登录/注册

    curl -X POST \
      -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
      -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
      -H "Content-Type: application/json" \
      -d '{"mobilePhone":"你的手机号","smsCode":"861293"}
      https://api.maxleap.cn/2.0/loginByMobilePhone

如果用户不存在,则自动创建,并返回信息。如果用户存在,则登录成功。

    {
    "createdAt":"2016-08-26T04:09:40.885Z",
    "mobilePhone":"你的手机号",
    "sessionToken":"F1zRm-MSN7BHL46N2VZmpOlhmYBrQhHmpK0CQmhDvSc",
    "isNew":true,
    "mobilePhoneVerified":true,
    "enabled":true,
    "objectId":"57bfc104b0d8500007e2cd2f",
    "username":"你的手机号"
    }

错误码

参考 通用错误码

FAQ

补充说明

云代码

API 列表

云函数

URLHTTP功能
/functions/<name>POST调用云函数
/jobs/<name>POST执行job

API 详解

调用云函数

云函数是运行在 MaxLeap 上的代码,可以使用它来实现各种复杂逻辑。用户在上传完云代码后,可以通过REST API来调用云端定义的函数,以JAVA版本为例,当你使用CloudCode-SDK(如何使用请参考云代码 SDK使用教程)定义了一个function:

    //定义一个简单的function:返回输入数据
    defineFunction("hello", new MLHandler<Request, Response>() {
        @Override
        public Response handle(Request request) {
            Response<String> response = new MLResponse<>(String.class);
            response.setResult(request.parameter(String.class));
            return response;
        }
    });

部署该云代码后,通过API调用该云函数如下:

    curl -X POST \
          -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
          -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
          -H "Content-Type: application/json" \
          -d '{ "name": "真皮沙发","price": 1000,"producer": "法国巴黎"}' \
          https://api.maxleap.cn/2.0/functions/hello

云函数会返回结果:

{ "name": "真皮沙发","price": 1000,"producer": "法国巴黎"}

使用云函数,你必须在请求头里指定你的appId和相应的key方可有权限调用,但同时云代码支持白名单模式,你可以将函数的某个调用方式添加至白名单(如何添加至白名单请参阅云代码-白名单),添加后,当请求调用该函数时,将不进行http请求头中X-ML-AppId和X-ML-APIKey的校验,这一般用于回调请求,比如你调用银联支付接口设置了回调地址为MaxLeap的云函数地址

https://api.maxleap.cn/2.0/functions/hello?LASAppId=569d84a0169e7d00012c7afe

这是一个URL,银联方在完成支付请求后会通过GET方式来回调该地址,这个GET请求只需添加query参数LASAppId来标示该请求的云函数所属app即可,这样你可以在不提供相关应用key的安全前提下通过白名单云函数来接受第三方回调请求.

执行job

云代码中,您还可以自定义后台任务,它可以很有效的帮助您完成某些重复性的任务,或者定时任务。如深夜进行数据库迁移,每周六给用户发送打折消息等等。您也可以将一些耗时较长的任务通过Job来有条不紊地完成。用户在上传完云代码后,可以通过REST API来调用云端定义的后台任务,以JAVA版本为例,当你使用CloudCode-SDK(如何使用请参考云代码 SDK使用教程)定义了一个background job:

    //定义一个简单的job
    defineJob("helloJob", new MLHandler<Request, Response>() {
        @Override
        public Response handle(Request request) {
            Response response = new MLResponse(String.class);
            response.setResult("hello job");
            return response;
        }
    });

部署该云代码后,通过API调用该任务如下:

    curl -X POST \
          -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
          -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
          -H "Content-Type: application/json" \
          https://api.maxleap.cn/2.0/jobs/helloJob

执行Job会返回结果:

hello job

MaxLeap不建议你通过rest api方式来调用background job,而是通过console界面上创建后台任务来替代,一方面通过rest api调用job这是一个同步接口,如果你的后台任务需要比较长时间执行,你得到的响应可能便是超时,而通过后台界面执行任务是异步方式,你不但可以方便管理你的后台任务,同时也能清楚的追踪你的任务状态,详情请见 云代码-任务

补充说明

在调用云函数/执行 Job 时 POST 请求所传递数据必须符合 application/json 格式

错误码

补充说明

FAQ

补充说明

在线参数

内容更新中,敬请期待。。。

移动支付

API 列表

URLHTTP功能
maxpay/billPOST支付
maxpay/recordsPOST支付查询

API 详解

支付

支付渠道说明

渠道说明
ali_app支付宝移动支付
ali_web支付宝网页支付
ali_wap支付宝手机网页支付
wx_app微信移动支付
wx_native微信扫码支付
unipay_app银联移动支付
unipay_web银联网页支付

头信息说明

属性
Content-Typeapplication/json
X-ML-AppId${应用的ID}
X-ML-Session-Token${应用的SessionToken}

公共参数信息说明

属性类型示例数据说明
channelString‘ali’必填项,支付渠道
billNumString'00x98987’必填项,订单号,需要保证唯一,由客户端提供,需请自行确保在商户系统中唯一
totalFeeInt9900必填项,交易金额,单位为分
subjectString'图书-支付战争’必填项,订单主题
extrasObject{“key1”:“value1”,“key2”:“value2”}选填项,附加数据,JsonObject类型
returnUrlString'http://maxleap.cn/returnUrl’选填项,同步自动跳转url,若为支付宝网页支付则必填
showUrlString'http://maxleap.cn/showUrl’可选,支付宝网页支付(ali_web)的选填参数

返回公共数据说明

属性类型说明
codeInteger返回码,0为正常
msgString返回信息, OK为正常
errString具体错误信息
idString成功发起支付后返回支付表记录唯一标识

返回alipay的特有数据

属性类型说明
ali_webString跳转到用户支付的连接
ali_appStringapp使用的string
ali_wapString跳转到用户支付的连接

返回wxpay_native的特有数据

属性类型说明
prepayidString微信prepay_id
codeUrlString微信二维码

返回wxpay_app的特有数据

属性类型说明
appidString微信应用id
noncestrString随机字符串
packageString微信package参数
partneridString微信商户id
prepayidString支付id
signString签名
timestampString时间戳

返回unipay_web的特有数据

属性类型说明
htmlString包含一个自动提交表单的html

返回unipay_app的特有数据

属性类型说明
tnString支付流水号,用于手机sdk

返回Code的含义

属性类型说明
0OK成功
1APP_INVALID根据app_id找不到对应的APP或者app_sign不正确
2PAY_FACTOR_NOT_SET支付要素在后台没有设置
3CHANNEL_INVALIDchannel参数不合法
4MISS_PARAM缺少必填参数
5PARAM_INVALID参数不合法
6CERT_FILE_ERROR证书错误
7CHANNEL_ERROR渠道内部错误
14RUN_TIME_ERROR实时未知错误,请与技术联系帮助查看

示例

调用支付请求,前提是你已经为你的应用配置了相关渠道支付参数(如何配置请参考支付服务-配置渠道参数),如果你已经配置完你的渠道参数,你可以这样发起一个支付宝网页支付请求:

    curl -X POST \
          -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
          -H "X-ML-Session-Token: U9_sVnH_MRfmXYDRnug-jtF_FtD65RHlrNxWhHr-l5k" \
          -H "Content-Type: application/json" \
          -d '{ "channel": "ali_web","billNum": "5721d724bee82c77290c29e9","totalFee": 1,"subject":"test","extras":{"t":"2"},"returnUrl":"http://maxleap.cn/returnUrl","showUrl":"http://maxleap.cn/showUrl"}' \
          https://api.maxleap.cn/2.0/maxpay/bill

返回结果:

    {
        "id":"5721d724bee82c77290c29e9",
        "ali_app":"_input_charset=\"utf-8\"&notify_url=\"http://101.95.153.34:8888/maxpay/alinotify\"&out_trade_no=\"5721d724bee82c77290c29e9\"&partner=\"2088121305224121\"&payment_type=\"1\"&seller_id=\"2088121305224121\"&service=\"mobile.securitypay.pay\"&sign=\"n9Nk%2BshO%2BuhFOUxIgCLerbYnrMCcSe26ZNVcHxVgaX7yHfzv4EeeIAYCLzQkoYHL0zPLtmaHR8Gg0IXuyt1ANCTxM%2B8L3Femvq%2FUw22WCmOwR6ZWmv3ESrQ6uOuwekNa4uXK9SihmQQBYWKgsbJWdAhGo62dmMzBu2RNyE5wdTA%3D\"&sign_type=\"RSA\"&subject=\"test\"&total_fee=\"0.01\"",
        "ali_web":"https://mapi.alipay.com/gateway.do?_input_charset=utf-8&notify_url=http://101.95.153.34:8888/maxpay/alinotify&out_trade_no=5721d724bee82c77290c29e9&partner=2088121305224121&payment_type=1&seller_id=2088121305224121&service=create_direct_pay_by_user&sign=7d8515a7d3ba68ebbfafc1236a487c0b&sign_type=MD5&subject=test&total_fee=0.01",
        "ali_wap":"https://mapi.alipay.com/gateway.do?_input_charset=utf-8&notify_url=http://101.95.153.34:8888/maxpay/alinotify&out_trade_no=5721d724bee82c77290c29e9&partner=2088121305224121&payment_type=1&seller_id=2088121305224121&service=alipay.wap.create.direct.pay.by.user&sign=2e02ab9c76c1efcd0e72ddaad88b1d91&sign_type=MD5&subject=test&total_fee=0.01",
        "msg":"OK",
        "code":0
    }

需要注意的是,返回结果里包含了ali_web,ali_app等多个返回参数URL,你应该根据请求里的channel值来选择对应的URL来完成支付

你可以这样发起一个微信移动支付请求:

    curl -X POST \
          -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
          -H "X-ML-Session-Token: U9_sVnH_MRfmXYDRnug-jtF_FtD65RHlrNxWhHr-l5k" \
          -H "Content-Type: application/json" \
          -d '{ "channel": "wx_app","billNum": "5721d724bee82c77290c29e9","totalFee": 1,"subject":"test","extras":{"t":"2"}}' \
          https://api.maxleap.cn/2.0/maxpay/bill

返回结果:

    {
        "appid":"wx85fcd0162fdd8c11",
        "noncestr":"acc7a298fa3e4693a43886932ccb0497",
        "package":"Sign=WXPay",
        "partnerid":"1301506401",
        "prepayid":"wx20160428173420f12d329a3f0305120260",
        "sign":"A560ED5DFA0721913E598E4DC4C5AD36",
        "timestamp":"1461836061",
        "id":"5721d91bbee82c77290c29ea",
        "code":0
    }

这个结果都是微信支付的特有数据,拿到这些数据你可以完成你后续的微信支付了

你可以这样发起一个银联移动支付请求:

    curl -X POST \
        -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
        -H "X-ML-Session-Token: U9_sVnH_MRfmXYDRnug-jtF_FtD65RHlrNxWhHr-l5k" \
        -H "Content-Type: application/json" \
        -d '{ "channel": "unipay_app","billNum": "5721d724bee82c77290c29e9","totalFee": 1,"subject":"test","extras":{"t":"2"}}' \
        https://api.maxleap.cn/2.0/maxpay/bill

返回结果:

    {
        "tn":"201604281737505105498",
        "id":"5721d9eebee82c77290c29eb",
        "code":0
    }

得到返回结果中的tn支付流水号,你便可以通过手机SDK完成后续的银联支付了

支付查询

头信息说明

属性
Content-Typeapplication/json
X-ML-AppId${应用的ID}
X-ML-MasterKey${应用的MasterKey}

参数说明

属性类型示例数据说明
channelString'ali’选填项,支付渠道
billNumString'00x98987’选填项,订单号,需要保证唯一,由客户端提供,需请自行确保在商户系统中唯一
statusString'success’选填,订单状态
startTimeLong1451890938648选填,订单创建时间的起始时间
endTimeLong1451890939648选填,订单创建时间的终止时间
skipInteger0选填,分页参数,跳过条数
limitInteger100选填,分页参数,分页大小
orderString’-createdTime’选填,排序项,"-“开头表示倒序,后紧跟需要排序的关键字。顺序则直接填写排序关键字

返回数据

属性类型说明
codeInteger返回码,0为正常
errString具体错误信息
results:JsonArray查询结果

返回Code的含义

属性类型说明
0OK成功
1APP_INVALID根据app_id找不到对应的APP或者app_sign不正确
2PAY_FACTOR_NOT_SET支付要素在后台没有设置
3CHANNEL_INVALIDchannel参数不合法
4MISS_PARAM缺少必填参数
5PARAM_INVALID参数不合法
6CERT_FILE_ERROR证书错误
7CHANNEL_ERROR渠道内部错误
14RUN_TIME_ERROR实时未知错误,请与技术联系帮助查看

返回Results中一项的的含义

属性类型示例数据说明
idString568a18fad4c6062dcda477b2订单纪录的唯一id
channelString'ali’支付渠道
billNumString'00x98987’商户传入订单号
totalFeeInt9900交易金额,单位为分
createdTimeLong1451890938648订单创建时间
endTimeLong1451890939648订单交易终止时间
statusString'success’订单状态
extrasJsonObject{"1”: “2”}创建订单传入的额外信息

下面举例发起一个查询4月22日-四月28日内所有支付宝网页支付的交易列表请求:

    curl -X POST \
        -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
        -H "X-ML-MasterKey: NkZCeHprbjlKN2ZIOEtVOTBiLU5GQQ" \
        -H "Content-Type: application/json" \
        -d '{ "channel":"ali_web","startTime": 1461254400000,"endTime": 1461859199000,"skip": 0,"limit": 21}' \
        https://api.maxleap.cn/2.0/maxpay/bill

返回结果:

    {
        "results":[
            {
                "billNum":"5721df20bee8bb1b17703533",
                "channel":"ali_web",
                "createdTime":1461837602028,
                "currency":"CNY",
                "extras":{"t":"2"},
                "id":"5721df21bee87096cb665f6a",
                "money":"ï¿¥ 0.01",
                "status":"created",
                "totalFee":1
            }
        ],
        "code":0
    }

错误码

补充说明

FAQ

补充说明

即时通讯

API 列表https://im.maxleap.cn/

用户

URLHTTP功能
/ctxGET搜索用户
/ctx/{user_id}GET获取用户详情
/ctx/{user_id}/attributesPOST设置用户属性
/ctx/{user_id}/attributesPUT覆盖更新用户属性
/ctx/{user_id}/attributesGET获取用户属性
/ctx/{user_id}/attributes/{attribute}GET获取某个用户属性
/ctx/{user_id}/attributesDELETE清空用户属性
/ctx/{user_id}/friends/{friend_id}POST添加用户好友
/ctx/{user_id}/friends/{friend_id}GET获取友谊信息
/ctx/{user_id}/friends/{friend_id}DELETE删除好友
/ctx/{user_id}/friends/{friend_id}/chatsGET获取好友聊天记录
/ctx/{user_id}/friendsGET获取用户好友列表
/ctx/{user_id}/groupsGET获取用户已经加入的群组列表
/ctx/{user_id}/roomsGET获取用户已经加入的聊天室列表
/ctx/{user_id}/strangersGET获取用户相关联的陌生人列表
/ctx/{user_id}/strangers/{stranger_id}GET获取用户相关联的某个陌生人信息
/ctx/{user_id}/strangers/{stranger_id}/chatsGET获取与个陌生人的聊天记录

群组

URLHTTP功能
/groupsPOST创建群组
/groupsGET搜索群组
/groups/{group_id}GET获取群组基础信息
/groups/{group_id}PUT更新群组基础信息
/groups/{group_id}DELETE删除群组
/groups/{group_id}/attributesPOST设置群组属性
/groups/{group_id}/attributesPUT覆盖更新群组属性
/groups/{group_id}/attributesGET获取群组属性
/groups/{group_id}/attributes/{attribute}GET获取某个群组属性
/groups/{group_id}/attributesDELETE清空群组属性
/groups/{group_id}/membersPOST追加群组成员
/groups/{group_id}/membersDELETE移除群组成员
/groups/{group_id}/chatsGET获取群组聊天记录
/groups/{group_id}/chatsDELETE清空群组聊天记录

聊天室

URLHTTP功能
/roomsPOST创建聊天室
/roomsGET搜索聊天室
/rooms/{room_id}GET获取聊天室基础信息
/rooms/{room_id}DELETE删除聊天室
/rooms/{room_id}/attributesPOST设置聊天室属性
/rooms/{room_id}/attributesPUT覆盖更新聊天室属性
/rooms/{room_id}/attributesGET获取聊天室属性
/rooms/{room_id}/attributes/{attribute}GET获取某个聊天室属性
/rooms/{room_id}/attributesDELETE清空聊天室属性
/rooms/{room_id}/membersPOST追加聊天室成员
/rooms/{room_id}/membersDELETE移除聊天室成员

游客

URLHTTP功能
/passengersPOST创建游客
/passengers/{passenger_id}GET获取游客基础信息
/passengers/{passenger_id}/chats/{user_id}GET获取游客聊天记录

系统消息

URLHTTP功能
/systemPOST给所有人发送系统消息
/system/{target}POST给指定对象发送系统消息

附件

URLHTTP功能
/attachmentPOST上传附件

API 详解

用户

搜索用户

自定义搜索用户, 您可以使用自定义用户属性作为搜索过滤条件, 另外还支持基础的分页过滤条件, 分页条件请参考FAQ

以下示例搜索cityshanghai的用户:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx?city=shanghai"

如果搜索到结果, 则返回匹配列表, 如:

[
  {
    "id": "testuser1",
    "online": false,
    "ts": 1461827422054,
    "attributes": {
      "name": "隔壁老王",
      "gender": "male",
      "age": 46,
      "city": "shanghai"
    }
  }
]

其中id表示用户标识, online表示用户当前是否在线, ts表示最后更新时间戳, attributes表示用户属性。

获取用户详情

根据用户标识来获取详细的用户信息。 用户标识用于标识应用内全局唯一的某个用户, 由字母、数字、下划线或中横线组成, 且长度不能超过128位。 以下举例标识为testuser1的用户详情:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1"

获取成功时, 将返回用户详情:

{
  "attributes": {
    "key1": "value1",
    "key2": "value2"
  },
  "installs": [ "installid1", "installid2" ],
  "sessions": 1,
  "friends": [ "friendid1", "friendid2" ],
  "groups": [ "groupid1", "groupid2" ],
  "rooms": [ "roomid1", "roomid2" ]
}

其中attributes表示用户属性, installs表示用户的APP安装ID, sessions表示该用户当前在线数, friends表示该用户的好友列表, groups表示该用户已加入的群组列表, rooms表示该用户已加入的聊天室列表。

设置用户属性

对系统中已存在的用户进行一些属性设置。本操作为追加形式写入, 当写入的属性已存在时则覆盖, 不存在时则新建。如果您需要完全覆盖重置, 请使用覆盖更新用户属性。 用户属性可以被用来读取或进行搜索。 以下举例为标识为testuser1的用户设置一些属性:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"name": "隔壁老王","age": 46,"gender": "male"}' \
    "https://im.maxleap.cn/ctx/testuser1/attributes"

当设置成功时, 系统会返回201状态码。

覆盖更新用户属性

类似设置用户属性, 但本操作会强制重置并覆盖所有属性。 以下举例为标识为testuser1的用户设置一些属性:

$ curl -X PUT \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"name": "隔壁老李"}' \
    "https://im.maxleap.cn/ctx/testuser2/attributes"

当设置成功时, 系统会返回201状态码。

获取用户属性

查询当前的用户属性。 以下示例查询标识为testuser1的用户属性:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/attributes"

获取某个用户属性

查询单个的用户属性。 以下示例查询用户标识为testuser1name属性:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/attributes/name"

查询成功则返回属性值。无此属性则返回HTTP状态码404及错误信息。

清空用户属性

强制清空用户的所有属性。 以下示例清空用户标识testuser1的所有属性:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser3/attributes"

清空成功则返回HTTP状态码204。

添加用户好友

使两个用户彼此成为好友, 该调用为幂等操作, 可以顺序颠倒或多次调用。 以下示例让用户标识为testuser1testuser2的用户彼此成为好友。

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/friends/testuser2"

成功调用则返回友谊(friendship)信息:

{
  "id": "b9d61d4e80ad1f6d",
  "from": "testuser1",
  "to": "testuser2",
  "ns": "569d84a0169e7d00012c7afe",
  "ts": 1461824615892
}

其中, id唯一标识友谊, from表示建立友谊的发起人, to表示接受人, ns表示命名空间(等价于ApplicationID), ts表示最后更新时间戳。

获取友谊信息

查询两个用户彼此的友谊信息。如果彼此不是好友或者用户标识不存在则返回错误信息。 以下示例尝试获取用户标识为testuser1testuser2的友谊信息。

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/friends/testuser2"

成功调用则返回友谊(friendship)详情:

{
  "id": "b9d61d4e80ad1f6d",
  "from": "testuser1",
  "to": "testuser2",
  "online": false,
  "ts": 1461824615892
}

其中, id唯一标识友谊, from表示建立友谊的发起人, to表示接受人, online表示好友是否在线, ts表示最后更新时间戳。

删除好友

擦除友谊信息, 令两人彼此不再是好友。本操作为幂等操作: 用户标识不存在, 顺序置换或者多次调用均可成功执行。 以下实例尝试删除用户标识为testuser3testuser4之间的好友关系(友谊小船说翻就翻):

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser3/friends/testuser4"

成功调用后返回HTTP状态码204。

获取好友聊天记录

查询最近7天的两位好友之间的聊天记录。

您可以额外添加过滤参数: - ts: 查询截止时间戳, 默认为当前时间戳。 - limit: 返回记录数, 默认为20条, 最大可设置为100。

以下示例返回用户标识testuser1testuser2最近的20条聊天记录:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/friends/testuser2/chats"

请求成功会返回聊天记录数组, 以下为范例:

[
  {
    "speaker": "testuser1",
    "content": {
        "media": 0,
        "body": "Hello!"
    },
    "ts": 1454490959094
  }
]

其中speaker表示发言者, content表示消息体(具体请参考FAQ), ts表示发言时间戳。

获取用户好友列表

根据用户标识获取该用户的所有好友信息。默认仅返回每个好友的用户标识, 如需返回更详细的信息, 可追加过滤条件detail。

以下示例返回用户标识testuser1的所有好友详情:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/friends?detail"

成功调用后会返回好友信息列表, 以下范例为追加detail后的返回格式:

[
  {
    "id": "testuser2",
    "online": false,
    "recent": {
      "speaker": "testuser1",
      "content": {
        "media": 0,
        "body": "Hello!",
      },
      "ts": 1454490959094
    }
  }
]

其中id为好友的用户标识, online表示好友当前是否在线, recent为彼此的最近一条聊天记录。

获取用户已经加入的群组列表

根据用户标识获取该用户已经加入的群组信息。默认仅返回每个群组的标识ID, 如需返回更详细的信息, 可追加过滤条件detail。

以下示例返回用户标识testuser1的所有群组信息:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/groups?detail"

成功调用后会返回群组信息列表, 以下范例为追加detail后的返回格式:

[
  {
    "id": "7c9fb6ca88ed41d58f69bb40b779d5bc",
    "owner": "testuser1",
    "attributes": {
        "name": "周杰伦粉丝群",
        "description": "这里是周杰伦粉丝的基地!"
    },
    "members": [ "testuser2", "testuser3" ],
    "ts": 1456306512958,
    "recent": {
      "speaker": "testuser1",
      "content": {
        "media": 0,
        "body": "hello everyone."
      },
      "ts": 1454490959094
    }
  }
]

其中id为群组标识, owner为群管理员的用户标识, attributes为群属性, members为群成员表, recent为该群的最近一条聊天信息, ts表示群创建日期时间戳。

获取用户已经加入的聊天室列表

根据用户标识获取该用户已经加入的聊天室信息。默认仅返回每个聊天室的标识ID, 如需返回更详细的信息, 可追加过滤条件detail。

以下示例返回用户标识testuser1的所有聊天室信息:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/rooms?detail"

成功调用后会返回聊天室信息列表, 以下范例为追加detail后的返回格式:

[
  {
    "id": "7c9fb6ca88ed41d58f69bb40b779d5bc",
    "attributes": {
        "name": "周杰伦粉丝群",
        "description": "这里是周杰伦粉丝的基地!"
    },
    "members": [ "testuser2", "testuser3" ],
    "ts": 1456306512958
  }
]

其中id为聊天室标识, attributes为聊天室属性, members为聊天室成员表, ts表示聊天室创建日期时间戳。

获取用户相关联的陌生人列表

当两个陌生用户聊天之后, 系统会记录两者的陌生人关联。您可以通过该API查询某个用户上下文中与其有过关联的陌生人列表。

该接口支持分页, 您可以追加skiplimit来控制分页(skip表示跳过的记录数,limit表示返回的记录数, 默认返回20)。

如果追加了detail, 系统将会在返回结果中附带详情信息(包括在线情况和最近一条聊天记录)。以下是范例:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/strangers?skip=0&limit=10&detail"

成功调用后返回testuser1的陌生人列表:

[
  {
    "id": "stranger_1",
    "online": false,
    "recent": {
      "speaker": "testuser1",
      "content": {
        "media": 0,
        "body": "hello world"
      },
      "ts": 1472635302198
    }
  }
]

获取用户相关联的某个陌生人信息

获取与某个陌生人的关联信息。

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/strangers/stranger_1"

将返回陌生人详情:

{
  "ts": 1472543936000,
  "online": false,
  "recent": {
    "speaker": "testuser1",
    "content": {
      "media": 0,
      "body": "hello world"
    },
    "ts": 1472635302198
  }
}

获取与个陌生人的聊天记录

获取与某个陌生人的聊天记录。您可以追加查询条件ts来限制最后聊天时间戳(默认为当前时间戳), limit用于控制返回记录数(默认20条)。

以下范例为查询最近聊天记录:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/ctx/testuser1/strangers/stranger_1/chats"

调用成功将返回:

[
  {
    "speaker": "testuser1",
    "content": {
      "media": 0,
      "body": "nice to meet you."
    },
    "ts": 1472635302198
  },{
    "speaker": "stranger_1",
    "content": {
      "media": 0,
      "body": "nice to meet you too."
    },
    "ts": 1472635330023
  }
]

群组

创建群组

新建一个群组, 调用时您必须指定一个群管理员(owner)。另外您也可以指定初始化成员(members)。

以下提交将会创建一个群, 管理员用户标识为testuser1, 额外的初始化成员为testuser2:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"owner": "testuser1","members": ["testuser2"]}' \
    "https://im.maxleap.cn/groups"

调用成功将会返回该群的标识ID, 如:

"7c9fb6ca88ed41d58f69bb40b779d5bc"

搜索群组

自定义搜索群组, 您可以使用自定义群组属性作为搜索过滤条件, 另外还支持基础的分页过滤条件, 分页条件请参考FAQ。

以下操作搜索company属性为maxleap的群组:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups?company=maxleap"

成功调用后返回匹配的群组详情列表, 范例如下:

[
  {
    "id": "4fced5ee96ac438bbf56b4a1fd87d330",
    "owner": "testuser1",
    "members": [ "testuser2", "testuser3" ],
    "attributes": {
      "name": "test group",
      "description": "this is a test group",
      "company": "maxleap"
    },
    "ts": 1458153453000
  }
]

获取群组基础信息

根据群组标识ID获取群组信息。 以下示例获取群组标识为11e930016e2e48d8b5faa6fd0ee90517的群组信息:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517"

查询成功则返回群组信息, 范例如下:

{
  "owner": "testuser1",
  "members": [ "testuser2" ],
  "attributes": {
    "name": "我的测试群",
    "description": "专业测试一百年",
    "company": "maxleap"
  },
  "ts": 1456306512958
}

如果群组不存在则返回HTTP状态码404以及错误信息。

更新群组基础信息

更新群组基础属性, 基础属性包括owner, members。当前版本系统只会处理这两个属性。

以下示例将群组11e930016e2e48d8b5faa6fd0ee90517的管理员设置为testuser2

$ curl -X PUT \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"owner": "testuser2"}' \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517"

更新成功则返回HTTP状态码201。

删除群组

根据群组标识ID彻底删除群组。该操作不可逆, 请谨慎调用!

以下示例将删除标识为b313c8af604a44f690ff9528b309ca1d的群组:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/b313c8af604a44f690ff9528b309ca1d"

删除成功返回HTTP状态码204。

设置群组属性

为某个群组自定义一些属性, 群组属性可以被用来作为搜索条件。具体请参考参考搜索群组

本操作为追加形式写入, 对已存在的属性进行覆写, 不存在的属性则新建并写入。如果您需要完全覆盖重置, 请使用覆盖更新群组属性

以下示例为标识为11e930016e2e48d8b5faa6fd0ee90517的群组设置一些属性:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"company": "maxleap","star": 5}' \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517/attributes"

设置成功则返回HTTP状态码201。如果群组不存在则返回HTTP状态码404以及错误信息。

覆盖更新群组属性

参考上文, 本API为上述的强制覆盖版本。

$ curl -X PUT \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"flag": "Game"}' \
    "https://im.maxleap.cn/groups/46b9c7cc4fc6428185a2e3a1c1f9e26e/attributes"

获取群组属性

根据群组标识获取该群组的所有自定义属性。

以下示例返回群组标识为11e930016e2e48d8b5faa6fd0ee90517的所有属性:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517/attributes"

如果调用成功, 将返回类似如下格式的消息体:

{
  "name": "周杰伦粉丝群",
  "description": "这里是周杰伦粉丝的基地",
  "score": 5
}

获取某个群组属性

获取单个的群组自定义属性。

以下示例返回群组标识为11e930016e2e48d8b5faa6fd0ee90517name属性:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517/attributes/name"

调用成功则返回:

"周杰伦粉丝群"

如果属性不存在则返回HTTP状态码404及错误信息。

清空群组属性

用于擦除群组所有自定义属性。本操作不可逆, 请谨慎调用。

以下示例擦除群组标识为46b9c7cc4fc6428185a2e3a1c1f9e26e的所有自定义属性:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/46b9c7cc4fc6428185a2e3a1c1f9e26e/attributes"

调用成功则返回HTTP状态码204。

追加群组成员

为某个群组添加新的群组成员, 请确保群组标识和您要加入的成员标识在系统中存在! 否则系统会返回错误提示!

以下示例为标识为11e930016e2e48d8b5faa6fd0ee90517的群组添加新成员testuser3:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"members": ["testuser3"]}' \
   "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517/members"

成功添加后返回HTTP状态码201。

移除群组成员

为群组移除某些成员。调用前请确保群组标识存在, 并且将要移除的成员标识不能为管理员! 否则系统会返回错误消息。

以下示例为标识为11e930016e2e48d8b5faa6fd0ee90517的群组移除testuser3成员:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"members": ["testuser3"]}' \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517/members"

成功调用后返回HTTP状态码204。

获取群组聊天记录

根据群组标识查询获取7天内的群组聊天记录。 您可以追加过滤字段: - ts: 标识截止时间戳, 默认为当前时间戳。 - limit: 返回记录数, 默认为20条, 最大支持100。

以下示例返回群组标识为11e930016e2e48d8b5faa6fd0ee90517的聊天记录:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/11e930016e2e48d8b5faa6fd0ee90517/chats"

查询成功则返回聊天记录消息体:

[
  {
    "speaker": "testuser1",
    "content": {
      "media": 0,
      "body": "大家都在吗?"
    },
    "ts": 1454490959094
  }
]

清空群组聊天记录

擦除保存在云端的群组聊天记录。该操作不可逆, 请谨慎调用!

以下示例擦除群组标识为35802e7cc8b546f2b51558f44fecc0ea的所有云端聊天记录:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/groups/35802e7cc8b546f2b51558f44fecc0ea/chats"

擦除成功返回HTTP状态码204。

聊天室

创建聊天室

创建一个全新的聊天室。您可以额外指定初始化成员表(members)。

以下示例新建一个聊天室并初始化两位成员testuser1testuser2:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"members": ["testuser1","testuser2"]}' \
    "https://im.maxleap.cn/rooms"

调用成功系统将返回新建聊天室的标识ID, 如:

"7c9fb6ca88ed41d58f69bb40b779d5bc"

搜索聊天室

自定义搜索聊天室, 您可以使用自定义聊天室属性作为搜索过滤条件, 另外还支持基础的分页过滤条件, 分页条件请参考FAQ。

以下操作搜索company属性为maxleap的聊天室:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/rooms?company=maxleap"

成功调用后返回匹配的聊天室详情列表, 范例如下:

[
  {
    "id": "2a416cb1847d4700b0431f193f6418b7",
    "members": [ "testuser2", "testuser3" ],
    "attributes": {
      "company": "maxleap",
      "name": "test room",
      "description": "this is a test room",
      "city": "shanghai"
    },
    "ts": 1458153453000
  }
]

其中id为聊天室标识, members为聊天室当前成员列表, attributes为聊天室属性, ts为聊天室最后更新日期时间戳。

获取聊天室基础信息

根据聊天室标识ID获取聊天室信息。 以下示例获取群组标识为52f5e4bfa4e3442fb38225887187a0ae的聊天室信息:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/rooms/52f5e4bfa4e3442fb38225887187a0ae"

查询成功则返回聊天室信息, 范例如下:

{
  "members": [ "testuser1", "testuser2" ],
  "attributes": {
    "company": "maxleap",
    "name": "test room",
    "description": "this is a test room",
    "city": "shanghai"
  },
  "ts": 1458153453000
}

如果聊天室不存在则返回HTTP状态码404及错误信息。

删除聊天室

根据聊天室标识ID彻底删除聊天室, 该操作不可逆,请谨慎调用!

以下示例将会彻底删除标识为c0eebb302b1345fd983345336dd4eaa6的聊天室:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/rooms/c0eebb302b1345fd983345336dd4eaa6"

删除成功则返回HTTP状态码204。

设置聊天室属性

为某个聊天室自定义一些属性, 聊天室属性可以被用来作为搜索条件。具体请参考参考搜索聊天室

本操作为追加形式写入, 对已存在的属性进行覆写, 不存在的属性则新建并写入。如果您需要完全覆盖重置, 请使用覆盖更新聊天室属性

以下示例为标识为52f5e4bfa4e3442fb38225887187a0ae的聊天室设置一些属性:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"city": "shanghai","score": 5}' \
    "https://im.maxleap.cn/rooms/52f5e4bfa4e3442fb38225887187a0ae/attributes"

设置成功则返回HTTP状态码201。

覆盖更新聊天室属性

参考上文, 本API为上述的强制覆盖版本。

$ curl -X PUT \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"rate": "100%"}' \
    "https://im.maxleap.cn/rooms/403b479663a24f47a08262ca293c47db/attributes"

获取聊天室属性

根据聊天室标识获取该聊天室的所有自定义属性。

以下示例返回群组标识为52f5e4bfa4e3442fb38225887187a0ae的所有属性:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/rooms/52f5e4bfa4e3442fb38225887187a0ae/attributes"

如果调用成功, 将返回类似如下格式的消息体:

{
  "city": "shanghai",
  "score": 5
}

获取某个聊天室属性

获取单个的聊天室自定义属性。

以下示例返回群组标识为52f5e4bfa4e3442fb38225887187a0aecity属性:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/rooms/52f5e4bfa4e3442fb38225887187a0ae/attributes/city"

调用成功则返回属性值, 如本例:

"shanghai"

如果属性不存在则返回HTTP状态码404及错误信息。

清空聊天室属性

用于擦除聊天室所有自定义属性。本操作不可逆, 请谨慎调用。

以下示例擦除聊天室标识为9699068226a14cfbbc569b6fa2f5cf8d的所有自定义属性:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/rooms/9699068226a14cfbbc569b6fa2f5cf8d/attributes"

调用成功则返回HTTP状态码204。

追加聊天室成员

为某个聊天室添加新的成员, 请确保聊天室标识和您要加入的成员标识在系统中存在! 否则系统会返回错误提示!

以下示例为标识为52f5e4bfa4e3442fb38225887187a0ae的聊天室添加新成员testuser3:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"members": ["testuser3"]}' \
    "https://im.maxleap.cn/rooms/52f5e4bfa4e3442fb38225887187a0ae/members"

移除聊天室成员

为聊天室移除某些成员。调用前请确保聊天室标识存在, 否则系统会返回错误提示。

以下示例为标识为52f5e4bfa4e3442fb38225887187a0ae的聊天室移除成员testuser3:

$ curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"members": ["testuser3"]}' \
    "https://im.maxleap.cn/rooms/52f5e4bfa4e3442fb38225887187a0ae/members"

成功调用后返回HTTP状态码204。

游客

创建游客

创建一个游客, 您可以初始化一些自定义属性, 系统将会在创建时保存这些属性。

另外您可以指定一个游客标志(id), 用于唯一标志该游客, 如果不指定, 系统会随机分配一个标志。

以下示例创建一个包含name,qqage属性的游客:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"name": "王尼玛","qq": 88888888,"age": 28}' \
    "https://im.maxleap.cn/passengers"

调用成功将会返回该游客的标志ID:

"58550388f9434168bf2019317b649265"

获取游客基础信息

根据游客标志获取该游客的信息。

以下示例获取标志为dcb52ac805ab459dabb66032bb43edaf的游客信息:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/passengers/dcb52ac805ab459dabb66032bb43edaf"

成功获取后, 将返回该游客的所有属性:

{
  "name": "王尼玛",
  "qq": 88888888,
  "age": 28
}

如果该游客不存在, 则会返回HTTP状态码404及错误消息。

获取游客聊天记录

根据游客标志和用户标志, 获取两者的云端历史聊天记录 ( 历史聊天记录最长保存1年 )。

以下示例返回游客dcb52ac805ab459dabb66032bb43edaf和用户testtuser1之间的云端聊天记录:

$ curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://im.maxleap.cn/passengers/dcb52ac805ab459dabb66032bb43edaf/chats/testuser1"

成功调用后返回:

[
  {
    "speaker": "dcb52ac805ab459dabb66032bb43edaf",
    "content": {
      "media": 0,
      "body": "这个能包邮吗?"
    },
    "ts": 1460969109145
  },
  {
    "speaker": "testuser1",
    "content": {
      "media": 0,
      "body": "包邮的哦亲!"
    },
    "ts": 1460969109380
  }
]

系统消息

给所有人发送系统消息

给应用内的所有在线用户发送系统消息。

以下示例发送内容为hello all!的文本消息:

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"content": {"media": 0,"body": "hello all!"}}' \
    "https://im.maxleap.cn/system"

发送成功则返回HTTP状态码202。

给指定对象发送系统消息

给应用内的单个对象发送系统消息。仅当对象为用户或者群组时, 系统会尝试推送离线消息。

您可以指定对象类型, 默认为普通用户, 例如: - https://im.maxleap.cn/system/35802e7cc8b546f2b51558f44fecc0ea?group 发送对象为群组, 群组标识为35802e7cc8b546f2b51558f44fecc0ea - https://im.maxleap.cn/system/c0eebb302b1345fd983345336dd4eaa6?room 发送对象为聊天室, 聊天室标识为c0eebb302b1345fd983345336dd4eaa6

以下示例对标识为testuser1的用户发送系统消息。

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    -d '{"content":{"media": 0,"body": "hello!"}}' \
    "https://im.maxleap.cn/system/testuser1"

发送成功则返回HTTP状态码202。

附件

上传附件

上传附件到服务器使用POST表单方式。当上传的文件为图片时, 系统会自动生成最大尺寸为128*128的缩略图。 使用时请注意: - 附件仅会在云端保存7天 - 附件大小限制为20MB

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: multipart/form-data;" \
    -F "attachment=@[YOUR_LOCAL_FILE]" \
    "https://im.maxleap.cn/attachment"

如果上传成功且为图片文件, 则返回原图和缩略图的URL(其他格式则只有原文件URL), 例如:

[
  "http://s3.cn-north-1.amazonaws.com.cn/im.maxleap.cn/b9d61d4e/6bee2996.png",
  "http://s3.cn-north-1.amazonaws.com.cn/im.maxleap.cn/b9d61d4e/6bee2996.sm.png"
]

错误码

错误码含义备注
5001非法的参数错误
5002数据库异常
5003未授权的操作
5004请求的对象不存在
5005请求参数冲突
5006文件存储服务异常
5007无法完成图片处理
5008成员数已经达到上限
5009未支持的操作
5010请求参数超长
5011文件大小超过限制
5012文件上传错误

FAQ

通用的请求头

名称作用示例备注
X-ML-AppId应用IDX-ML-AppId: 569d84a0169e7d00012c7afe头名称大小写不敏感
X-ML-Request-Sign加密后的应用签名X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060加密算法: 首先取变量TS为当前时间戳, 然后计算MD5(TS + ClientKey) + "," + TS, ClientKey可以在页面应用设置-应用密钥中找到
X-Parrot-Version请求的聊天服务版本X-Parrot-Version: 2头名称大小写不敏感, 可选项, 默认使用最新版本的API

通用的分页过滤参数

参数名作用示例备注
_sort排序_sort=score,-age前缀-表示倒序
_skip跳过记录数_skip=10大于0
_limit分页记录数_limit=30最大为100

通用的消息内容格式

消息内容包含在一个消息的content字段中, 拥有两个字段: - media: 媒体类型(int) - 0: 文本 - 1: 图片 - 2: 音频 - 3: 视频 - 其他: 待扩展 - body: 消息体(string), 一般除了文本之外, 其他可以设置为URL链接。

应用内社交

API 列表

关系

URLHTTP功能
/maxsocial/relationPOST创建或者更新用户关系表
/maxsocial/relation/objectId/<objectId>GET获取用户关系
/maxsocial/relation/statusGET获取2个用户之间的关注状态
/maxsocial/relation/getRelationGET得到2个用户的关系
/maxsocial/relation/followsPOST获取关注列表
/maxsocial/relation/followersPOST获取粉丝列表
/maxsocial/relation/objectId/<objectId>DELETE删除关系
/maxsocial/relation/deleteDELETE删除关系

说说

URLHTTP功能
/maxsocial/shuoPOST创建或者更新说说
/maxsocial/shuo/objectId/<objectId>GET获取说说
/maxsocial/shuo/listPOST得到说说列表
/maxsocial/shuo/nearPOST得到指定区域附近的说说
/maxsocial/shuo/latestPOST得到最新的一些说说
/maxsocial/shuo/getAllPOST得到一条说说所有内容
/maxsocial/shuo/friendCirclePOST得到朋友圈说说
/maxsocial/shuo/photosdeleteDELETE删除说说

地理位置

URLHTTP功能
/maxsocial/locationPOST创建或者更新用户和地理位置的对应关系
/maxsocial/location/nearPOST得到指定地点指定距离内的人
/maxsocial/location/<objectId>GET获得用户和地理对应关系
/maxsocial/location/userId/<userId>GET获取用户的地理信息
/maxsocial/relation/<objectId>DELETE删除用户和地理对应关系

评论

URLHTTP功能
/maxsocial/commentPOST创建或者更新评论
/maxsocial/comment/listPOST获取评论列表
/maxsocial/comment/updatePOST更新评论已读状态
/maxsocial/comment/objectId/<objectId>GET获得评论
/maxsocial/comment/unreadGET得到未读评论
/maxsocial/comment/objectId/<objectId>DELETE删除评论

通行证

URLHTTP功能
/maxsocial/socialpass/registerPOST注册
/maxsocial/socialpass/loginPOST登陆(账号密码)
/maxsocial/socialpass/smsCodePOST获取短信验证码
/maxsocial/socialpass/loginByMobilePOST短信验证码登陆

API 详解

关系

创建或者更新用户关系

创建一个用户关系,或者更新对应的用户关系。请求中reverse字段表示2者是否相互关注:

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 4bbfe81d-bf4c-3a83-2aeb-c3130ff8e23b" -d '{
  "userId": "5641b10b3330920001f1f7b1",
  "followerId": "5641b10b3330920001f1f7a1",
  "reverse": true
}' "http://api.maxleap.cn/2.0/maxsocial/relation"
Request:
{
  "userId": "5641b10b3330920001f1f7b1",
  "followerId": "5641b10b3330920001f1f7a1",
  "reverse": true
}

返回创建或者更新结果:

Response:
[{"updateResult":1},{"updateResult":1}]
or
[
    {
        "createdAt": "2016-04-07T03:39:54.460Z",
        "objectId": "5705d68a6b85b3410eaaabcc"
    },
    {
        "createdAt": "2016-04-07T03:39:54.460Z",
        "objectId": "5705d68a6b85b3410eaaabcd"
    }
]

获取用户关系

请求根据objectId获取用户关系:

curl -X GET -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: ba97ada1-d483-520e-507b-4d6d28fa0cb9" "http://api.maxleap.cn/2.0/maxsocial/relation/objectId/5705d68a6b85b3410eaaabcd"
Response:
{
  "createdAt": "2016-03-22T07:42:07.127Z",
  "black": false,
  "followerId": "5641b10b3330920001f1f7v1",
  "reverse": true,
  "userId": "5641b10b3330920001f1f7b1",
  "objectId": "56f0f74f6b85b309eda7ae53",
  "updatedAt": "2016-03-22T07:42:07.127Z"
}

获取2个用户之间的关注状态

query中根据userId和followerId获取相互之间的关注状态:
status: 1:相互关注 0:已关注 -1:未关注

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/status?followerId=5704e0e9667a2300015c1bd0&userId=5704e0c3667a2300015c1bce"
Response:
{"status":1}

得到2个用户的关系

query中根据userId和followerId获取2个用户的关系:

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/relation/getRelation?followerId=5704e0e9667a2300015c1bd0&userId=5704e0c3667a2300015c1bce"

返回一条Relation详细信息:

Response:
{
    "results":
        {
            "createdAt": "2016-04-08T09:33:19.123Z",
            "black": false,
            "followerId": "567",
            "reverse": false,
            "userId": "321",
            "objectId": "57077adf6b85b34b67fe4921",
            "updatedAt": "2016-04-08T09:33:19.123Z"
        }
}

获取关注列表

请求followerId,得到其关注的所有人,支持分页(参数详见FAQ):

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 0a55dfda-ce83-cbdf-cca2-71b2bec8c937" -d '{
    "followerId":"5641b10b3330920001f1f7v1"
}' "http://api.maxleap.cn/2.0/maxsocial/relation/follows"
Request:
{
    "followerId":"5641b10b3330920001f1f7v1"
}
Response:
{
  "results": [
    {
      "createdAt": "2016-03-22T07:42:07.127Z",
      "black": false,
      "followerId": "5641b10b3330920001f1f7v1",
      "reverse": true,
      "userId": "5641b10b3330920001f1f7b1",
      "objectId": "56f0f74f6b85b309eda7ae53",
      "updatedAt": "2016-03-22T07:42:07.127Z"
    }
  ]
}

获取粉丝列表

请求userId,得到其粉丝列表,支持分页(参数详见FAQ):

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 04778a3d-1570-fc28-4f15-fe6503274abf" -d '{
    "userId":"5641b10b3330920001f1f7b1"
}' "http://api.maxleap.cn/2.0/maxsocial/relation/followers"
Request:
{
    "userId":"5641b10b3330920001f1f7b1"
}
Response:
{
  "results": [
    {
      "createdAt": "2016-03-22T07:42:07.127Z",
      "black": false,
      "followerId": "5641b10b3330920001f1f7v1",
      "reverse": true,
      "userId": "5641b10b3330920001f1f7b1",
      "objectId": "56f0f74f6b85b309eda7ae53",
      "updatedAt": "2016-03-22T07:42:07.127Z"
    },
    {
      "createdAt": "2016-03-18T07:45:37.349Z",
      "black": false,
      "followerId": "5641b10b3330920001f1f7a1",
      "reverse": true,
      "userId": "5641b10b3330920001f1f7b1",
      "objectId": "56ebb2216b85b356e380daf2",
      "updatedAt": "2016-03-22T07:39:06.345Z"
    }
  ]
}

删除关系

根据关系表的objectId来删除关系

curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/relation/objectId/{objectId}

根据userId来删除关系:

curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/relation/delete?userId=xxx

说说

创建或者更新说说

字段:userId,content,link,longitude,latitude,friendCircle 地理位置字段可选,文件,文字内容和连接不能3者都有也不能都没有,friendCircle字段默认false 采用form-data方式提交

获取说说

根据objectId获取说说:

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/shuo/objectId/{objectId}

返回一条说说信息:

{
            "createdAt": "2016-04-07T08:01:03.645Z",
            "photopath": ["https://s3.cn-north-1.amazonaws.com.cn/social.maxleap.cn/file-uploads/56c5719d654e350001dc6e66/5641b10b3330920001f1f7a4/570613bf6b85b3436e86aa43/338be31c-78dd-479a-9266-8ee150b312f1"],
            "location": [
                40.1,
                20.1
            ],
            "userId": "5641b10b3330920001f1f7a4",
            "content": "just a testaa*,*,呵呵呵呵",
            "friendCircle": false,
            "objectId": "570613bf6b85b3436e86aa43",
            "updatedAt": "2016-04-07T08:01:03.645Z"
        }

得到说说列表

根据userId得到说说列表,black字段是从relation中query出来得到,支持分页(参数详见FAQ),返回说说的同时会把对应的评论和赞一起返回

curl: json curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 5aaeba19-e5b0-04d2-bd6d-3429d3bb2ab3" -d '{ "userId":"5641b10b3330920001f1f7b1", "black": false }' "http://api.maxleap.cn/2.0/maxsocial/shuo/list"

Request:
{
    "userId":"5641b10b3330920001f1f7b1",
    "black": false
}
Response:
{
    "results": [
        {
            "createdAt": "2016-04-07T08:01:03.645Z",
            "photopath": ["https://s3.cn-north-1.amazonaws.com.cn/social.maxleap.cn/file-uploads/56c5719d654e350001dc6e66/5641b10b3330920001f1f7a4/570613bf6b85b3436e86aa43/338be31c-78dd-479a-9266-8ee150b312f1"],
            "location": [
                40.1,
                20.1
            ],
            "userId": "5641b10b3330920001f1f7a4",
            "content": "just a testaa*,*,呵呵呵呵",
            "friendCircle": false,
            "objectId": "570613bf6b85b3436e86aa43",
            "updatedAt": "2016-04-07T08:01:03.645Z"
        }
    ],
    "comments": {
        "5704b2b26b85b33d02184f08": [
            {
                "createdAt": "2016-04-06T06:57:49.037Z",
                "read": false,
                "zan": false,
                "shuoId": "5704b2b26b85b33d02184f08",
                "userId": "5641b10b3330920001f1f7a4",
                "content": "fuck test!",
                "objectId": "5704b36d6b85b33d2cab54b8",
                "updatedAt": "2016-04-06T06:57:49.037Z"
            }
        ]
    },
    "zans": {
        "570608016b85b342ce46b8a8": [
            {
                "createdAt": "2016-04-07T10:58:39.670Z",
                "read": false,
                "zan": true,
                "shuoId": "570608016b85b342ce46b8a8",
                "userId": "56f9f06c667a2300017c706b",
                "objectId": "57063d5f238c8f0001b942bf",
                "updatedAt": "2016-04-07T10:58:39.670Z"
            }
        ]
    }
}

得到指定区域附近的说说

得到指定区域附近的说说,支持分页(参数详见FAQ),返回说说的同时会把对应的评论和赞一起返回

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: c0128465-b63d-20a2-83bf-df0c43661731" -d '{
    "latitude": 40.2,
    "longitude": 20.1,
    "distance": 100000000
}' "http://api.maxleap.cn/2.0/maxsocial/shuo/near"
Request:
{
    "latitude": 40.2,
    "longitude": 20.1,
    "distance": 100000000
}
Response:
{
    "results": [
        {
            "createdAt": "2016-04-07T08:01:03.645Z",
            "photopath": ["https://s3.cn-north-1.amazonaws.com.cn/social.maxleap.cn/file-uploads/56c5719d654e350001dc6e66/5641b10b3330920001f1f7a4/570613bf6b85b3436e86aa43/338be31c-78dd-479a-9266-8ee150b312f1"],
            "location": [
                40.1,
                20.1
            ],
            "userId": "5641b10b3330920001f1f7a4",
            "content": "just a testaa*,*,呵呵呵呵",
            "friendCircle": false,
            "objectId": "570613bf6b85b3436e86aa43",
            "updatedAt": "2016-04-07T08:01:03.645Z"
        }
    ],
    "comments": {
        "5704b2b26b85b33d02184f08": [
            {
                "createdAt": "2016-04-06T06:57:49.037Z",
                "read": false,
                "zan": false,
                "shuoId": "5704b2b26b85b33d02184f08",
                "userId": "5641b10b3330920001f1f7a4",
                "content": "fuck test!",
                "objectId": "5704b36d6b85b33d2cab54b8",
                "updatedAt": "2016-04-06T06:57:49.037Z"
            }
        ]
    },
    "zans": {
        "570608016b85b342ce46b8a8": [
            {
                "createdAt": "2016-04-07T10:58:39.670Z",
                "read": false,
                "zan": true,
                "shuoId": "570608016b85b342ce46b8a8",
                "userId": "56f9f06c667a2300017c706b",
                "objectId": "57063d5f238c8f0001b942bf",
                "updatedAt": "2016-04-07T10:58:39.670Z"
            }
        ]
    }
}

得到最新的一些说说

得到最新的一些说说,默认50条,支持分页(参数详见FAQ),返回说说的同时会把对应的评论和赞一起返回

curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/shuo/latest

返回结果:

Response:
{
    "results": [
        {
            "createdAt": "2016-04-07T08:01:03.645Z",
            "photopath": ["https://s3.cn-north-1.amazonaws.com.cn/social.maxleap.cn/file-uploads/56c5719d654e350001dc6e66/5641b10b3330920001f1f7a4/570613bf6b85b3436e86aa43/338be31c-78dd-479a-9266-8ee150b312f1"],
            "location": [
                40.1,
                20.1
            ],
            "userId": "5641b10b3330920001f1f7a4",
            "content": "just a testaa*,*,呵呵呵呵",
            "friendCircle": false,
            "objectId": "570613bf6b85b3436e86aa43",
            "updatedAt": "2016-04-07T08:01:03.645Z"
        }
    ],
    "comments": {
        "5704b2b26b85b33d02184f08": [
            {
                "createdAt": "2016-04-06T06:57:49.037Z",
                "read": false,
                "zan": false,
                "shuoId": "5704b2b26b85b33d02184f08",
                "userId": "5641b10b3330920001f1f7a4",
                "content": "fuck test!",
                "objectId": "5704b36d6b85b33d2cab54b8",
                "updatedAt": "2016-04-06T06:57:49.037Z"
            }
        ]
    },
    "zans": {
        "570608016b85b342ce46b8a8": [
            {
                "createdAt": "2016-04-07T10:58:39.670Z",
                "read": false,
                "zan": true,
                "shuoId": "570608016b85b342ce46b8a8",
                "userId": "56f9f06c667a2300017c706b",
                "objectId": "57063d5f238c8f0001b942bf",
                "updatedAt": "2016-04-07T10:58:39.670Z"
            }
        ]
    }
}

得到一条说说所有内容

返回说说的同时会把对应的评论和赞一起返回

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 4ff155d4-ef16-d710-0aa6-327f6f80f6e4" -d '{
    "userId": "5641b10b3330920001f1f7a4",
    "shuoId": "5704b2b26b85b33d02184f08"
}' "http://api.maxleap.cn/2.0/maxsocial/shuo/getAll"
Request:
{
    "userId": "5641b10b3330920001f1f7a4",
    "shuoId": "5704b2b26b85b33d02184f08"
}
response:
{
    "results": {
        "comments": [],
        "zans": [],
        "shuo": {
            "createdAt": "2016-04-08T07:05:58.027Z",
            "photopath": [
                "https://s3.cn-north-1.amazonaws.com.cn/social.maxleap.cn/file-uploads/56c5719d654e350001dc6e66/5641b10b3330920001f1f7a7/570758566b85b349ab08e7bd/828134d3-6bfa-4652-8253-370ba7d94880"
            ],
            "location": [
                40.1,
                20.1
            ],
            "userId": "5641b10b3330920001f1f7a7",
            "content": "just a testaa*,*,呵呵呵呵",
            "friendCircle": false,
            "objectId": "570758566b85b349ab08e7bd",
            "updatedAt": "2016-04-08T07:05:58.027Z"
        }
    }
}

得到朋友圈关注人的说说以及评论和赞

得到朋友圈关注人的说说以及评论和赞,支持分页(参数详见FAQ)

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: c7c62f8b-a6b0-ccb4-5b33-5a3b00712f61" -d '{
    "userId": "123"
}' "http://api.maxleap.cn/2.0/maxsocial/shuo/friendCircle"
Request:
{
    "userId": "123"
}
Response:
{
    "results": [
        {
            "createdAt": "2016-03-30T07:00:27.647Z",
            "userId": "5641b10b3330920001f1f7a4",
            "content": "just a testaa*,*,呵呵呵呵",
            "objectId": "56fb798b6b85b32682580896",
            "updatedAt": "2016-03-30T07:00:27.647Z"
        },
        {
            "createdAt": "2016-03-29T07:51:13.701Z",
            "userId": "5641b10b3330920001f1f7a4",
            "content": "just a testaa",
            "objectId": "56fa33f1238c8f000122a378",
            "updatedAt": "2016-03-29T07:51:13.701Z"
        },
    ],
    "comments": {},
    "zans": {}
}

删除说说

删除说说以及对应的图片

curl:

curl -X DELETE -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: e058afd2-35f4-1737-127a-52cf34075bca" -d '{
    "userId": "5641b10b3330920001f1f7a7",
    "objectId": "570f13e9238c8f0001d622ef"
}' "http://api.maxleap.cn/2.0/maxsocial/photosdelete"
Request:
{
    "userId": "5641b10b3330920001f1f7a7",
    "objectId": "570f13e9238c8f0001d622ef"
}
Response:
{"shuoDeleteRes":1,"photosDelRes":true}

地理位置

创建或者更新用户和地理位置的对应关系

参数说明:coordinates里面第一行代表经度longitude,第二行代表纬度latitude。

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: ed75162f-a386-edae-e1c0-c1e39fa5ec3d" -d '{
  "userId": "5641b10b3330920001f1f7a5",
  "location": {
    "type": "Point",
    "coordinates": [
      40,
      5
    ]
  }
}' "http://api.maxleap.cn/2.0/maxsocial/location"
Request:
{
  "userId": "5641b10b3330920001f1f7a5",
  "location": {
    "type": "Point",
    "coordinates": [
      40,
      5
    ]
  }
}
Response:
{
  "objectId": "56f10f3d6b85b30b2463dc76",
  "createdAt": "2016-03-22T09:24:13.079Z"
}

得到指定地点指定距离内的人

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: f3232411-6832-7b68-935a-0e9feadc168d" -d '{
  "userId": "5641b10b3330920001f1f7a5",
  "latitude":5,
  "longitude":40,
  "distance": 100000
}' "http://api.maxleap.cn/2.0/maxsocial/location/near"
Request:
{
  "userId": "5641b10b3330920001f1f7a5",
  "latitude":5,
  "longitude":40,
  "distance": 100000
}
Response:
[
  {
    "createdAt": "2016-03-22T09:24:13.079Z",
    "location": {
      "type": "Point",
      "coordinates": [
        40,
        5
      ]
    },
    "userId": "5641b10b3330920001f1f7a5",
    "objectId": "56f10f3d6b85b30b2463dc76",
    "updatedAt": "2016-03-22T09:24:13.079Z"
  }
]

获得用户和地理对应关系

根据objectId获得用户和地理对应关系:

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/location/objectId/{objectId}

获取用户的地理信息

根据userId获取用户的地理信息:

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/location/userId/{userId}
Response:
[
  {
    "createdAt": "2016-03-22T09:24:13.079Z",
    "location": {
      "type": "Point",
      "coordinates": [
        40,
        5
      ]
    },
    "userId": "5641b10b3330920001f1f7a5",
    "objectId": "56f10f3d6b85b30b2463dc76",
    "updatedAt": "2016-03-22T09:24:13.079Z"
  }
]

删除用户和地理对应关系

根据objectId删除用户和地理对应关系:

curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/location/objectId/{objectId}

评论

创建或者更新评论

创建或者更新评论,评论id就是objectId:

Request:
{
  "userId": "5641b10b3330920001f1f7a5",
  "content": "waht?",
  "shuoId":"5641b10b3330920001f1f7a2",
  "zan":false
}
Response:
{
  "objectId": "56f116156b85b30b79b20078",
  "createdAt": "2016-03-22T09:53:25.668Z"
}

获取评论列表

获取评论列表,请求可选字段:zan:默认false,支持分页(参数详见FAQ)

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 3e1b4a05-3d3c-cc25-e6be-51cd739164cf" -d '{
  "shuoId":"5641b10b3330920001f1f7a2"
}' "http://api.maxleap.cn/2.0/maxsocial/comment/list"
Request:
{
  "shuoId":"5641b10b3330920001f1f7a2"
}
Response:
{
  "results": [
    {
      "createdAt": "2016-03-22T09:53:25.668Z",
      "read": false,
      "zan": false,
      "shuoId": "5641b10b3330920001f1f7a2",
      "userId": "5641b10b3330920001f1f7a5",
      "content": "waht?",
      "objectId": "56f116156b85b30b79b20078",
      "updatedAt": "2016-03-22T09:53:25.668Z"
    }
  ]
}

更新评论已读状态

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: f8f4cbf3-58e7-955e-fad9-48559789a6c4" -d '{
  "objectId": "570620dd238c8f0001b4e85b",
  "read": true
}' "http://api.maxleap.cn/2.0/maxsocial/comment/update"
Request:
{
  "objectId": "570620dd238c8f0001b4e85b",
  "read": true
}
Response:
{
    "updateResult": true
}

获得评论

根据objectId获得评论:

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/comment/objectId/{objectId}

得到未读评论

curl -X GET \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/comment/unread?shuoId=xxx
Response:
{
  "results": [
    {
      "createdAt": "2016-03-22T09:53:25.668Z",
      "read": false,
      "zan": false,
      "shuoId": "5641b10b3330920001f1f7a2",
      "userId": "5641b10b3330920001f1f7a5",
      "content": "waht?",
      "objectId": "56f116156b85b30b79b20078",
      "updatedAt": "2016-03-22T09:53:25.668Z"
    }
  ]
}

删除评论

curl -X DELETE \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
    -H "X-ML-Request-Sign: da1bb6b56200c84995127c784de90445,1461920236060" \
    -H "Content-Type: application/json" \
    "https://api.maxleap.cn/maxsocial/comment/objectId/{objectId}

通行证

注册

curl

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 9368e9c9-92eb-a34b-d4a5-a9d29ebccb80" -d '{
    "username":"yangtan",
    "password":"123456"
}' "http://api.maxleap.cn/2.0/maxsocial/socialpass/register"
request:
{
    "username":"yangtan",
    "password":"123456"
}
response:
{
    "username": "yangtan",
    "enabled": true,
    "objectId": "57033c9670c676000110e747",
    "createdAt": "2016-04-05T04:18:30.023Z",
    "sessionToken": "cCq4Ly6jxiaRRJDaFviaWXPw5ND65RHls79WhHr-l5k",
    "isNew": true,
    "ACL": {
        "creator": {
            "id": "57033c9670c676000110e747",
            "type": "AppUser"
        }
    }
}

登陆(账号密码

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: c48ce95f-76e4-ae2c-ff9d-f36019922bb1" -d '{
    "username":"yangtan",
    "password":"123456"
}' "http://api.maxleap.cn/2.0/maxsocial/socialpass/login"
request:
{
    "username":"yangtan",
    "password":"123456"
}
response:
{
    "createdAt": "2016-04-05T04:18:30.023Z",
    "sessionToken": "cCq4Ly6jxiaRRJDaFviaWXPw5ND65RHls79WhHr-l5k",
    "ACL": {
        "creator": {
            "id": "57033c9670c676000110e747",
            "type": "AppUser"
        }
    },
    "enabled": true,
    "objectId": "57033c9670c676000110e747",
    "username": "yangtan",
    "updatedAt": "2016-04-05T04:18:30.450Z"
}

获取短信验证码

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 585278b6-ba80-4435-0015-d9cad0d11bb8" -d '{
 "mobilePhone":"1347919XXXX",
}' "http://api.maxleap.cn/2.0/maxsocial/socialpass/smsCode"
Request
{
 "mobilePhone":"1347919XXXX",
}


Response
{
  "success": true
}

短信验证码登陆

curl:

curl -X POST -H "X-ML-appid: 5609fe7da5ff7f00012ce481" -H "X-ML-Session-Token: MuI3kNXYF1Jt8Ueb8RZvH5viI2CcehHlin5WhHr-l5k" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Postman-Token: 132b0216-eeba-707e-0bd1-58c1ec2e282e" -d '{
 "mobilePhone":"1347919XXXX",
 "smsCode":"030684"
}' "http://api.maxleap.cn/2.0/maxsocial/socialpass/loginByMobile"
Request
{
 "mobilePhone":"1347919XXXX",
 "smsCode":"030684"
}


Response
{
  "sessionToken": "NDRZDwGtbwPmrLM9_3Dz-KZjMnCU0hHljlE8FcK-tXg",
  "enabled": true,
  "isNew": true,
  "objectId": "5657fc5ed9ff8fa4e340c93d",
  "mobilePhoneVerified": true,
  "mobilePhone": "1347919XXXX",
  "createdAt": "2015-11-27T06:46:54.910Z",
  "username": "18602162324"
}

错误码

参考 通用错误码

FAQ

通用的分页过滤参数

参数名作用示例备注
sort排序sort=11:按创建时间排序,0:按userId排序。默认是1
pageId页面idpageId=1大于=0, 默认是0
asc正序还是倒序asc=true默认false, asc=true时表示倒序

数据分析

内容更新中,敬请期待。。。

推送营销

API 列表

URLHTTP功能
`/marketing/push/msg/(all{installId})`POST
/goppush/server/get?k={key}&p={}GET获取可用Android 推送服务器
/gopush/msg/get?k={key}&m={}GET获取Android离线消息
/gopush/time/get?cb={}GET获取初始消息ID

API 详解

向用户发送消息

当 App 安装到用户设备后,如果要使用消息推送功能,MaxLeap SDK 会自动生成一个 Installation 对象。Installation 对象包含了推送所需要的所有信息。你可以使用 REST API,通过 Installation 对象进行消息推送。

通过 POST marketing/push/msg 来推送消息给设备,下面是数据的描述

对于IOS 设备 推送内容为:

{
  "aps": {
    "alert": "hello",//消息内容
    "badge": 5,//数字类型,未读消息数目,应用图标边上的小红点数字,可以是数字,也可以是字符串 "Increment"(大小写敏感),
    "sound": "default",//声音文件名,前提在应用里存在
    "content-available": 1 //如果使用 Newsstand,设置为 1 来开始一次后台下载
  }, 
  "customFiled1": "key1",//自定义属性
  "customField2": [
    "bang",
    "whiz"
  ]
}

并且 IOS 设备支持 alert 本地化消息推送:

{ 
    "alert": {
      "title":           "推送标题",
      "title-loc-key":   "",
      "body":            "推送内容",
      "action-loc-key":  "string",
      "loc-key":         "string",
      "loc-args":        ["array of string"],
      "launch-image":    "string"
     }

}

详情参考 Apple 文档

如果是 Android 设备,默认是用的是MaxLeap的推送服务,默认的消息栏通知  支持下列属性:

{   
    "alert":      "消息内容",
    "title":      "显示在通知栏的标题",
    "custom-key": "由用户添加的自定义属性"
}

MaxLeap 支持一次向多个平台设备进行推送

{
  "aps": { //ISO 设备
    "alert": "hello",//消息内容
    "badge": 5,//数字类型,未读消息数目,应用图标边上的小红点数字,可以是数字,也可以是字符串 "Increment"(大小写敏感),
    "sound": "default",//声音文件名,前提在应用里存在
    "content-available": 1 //如果使用 Newsstand,设置为 1 来开始一次后台下载
  },  
  "alert":"android 设备内容"  // Android 设备
  "title":"android 设备标题" //Android 设备
  "customField": "自定义属性"
}

IOS 支持测试和生产证书

在发送之前需要上传对应的p12证书,否则消息不能正确的发出去。

{
  "certType":"number" //0:使用生产证书 1:测试证书 默认使用生产证书
  "aps": {
    "alert": "hello",//消息内容
    "badge": 5,//数字类型,未读消息数目,应用图标边上的小红点数字,可以是数字,也可以是字符串 "Increment"(大小写敏感),
    "sound": "default",//声音文件名,前提在应用里存在
    "content-available": 1 //如果使用 Newsstand,设置为 1 来开始一次后台下载
  }, 
  "customFiled1": "key1",//自定义属性
  "customField2": [
    "bang",
    "whiz"
  ]
}

下面是向某个特定的 Installation 推送一条消息

$ curl -X POST \
    -H "X-ML-AppId: 569d84a0169e7d00012c7afe"\
    -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ"\
    -H "Content-Type: application/json"\
    -d ' {     
          "alert":"hello maxleap"
         }'\
    "https://api.maxleap.cn/2.0/marketing/push/msg/a2188f955d1a4a968ee40e6952b05407" 

也可以向一批设备发送消息

$ curl -X POST \
-H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
-H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
-H "Content-Type: application/json" \
-d '{
   "installs":["a2188f955d1a4a968ee40e6952b05407","1111111"] ,   
   "alert":"hello maxleap,I'm android",
   "aps": {
          "alert": {
            "title": "Tips",
            "body": "hello maxleap,I'm apple device",
            "action-loc-key": "PLAY",
            "title-loc-key": "abc",
            "title-loc-args": [
              "1",
              "2"
            ],
            "loc-key": "abc",
            "loc-args": [
              "3"
            ],
            "launch-image": "string"
          },
          "badge": 1,
          "sound": "default",
          "content-available": 1
        },
   "customKey":"name"
}' "https://api.maxleap.cn/2.0/marketing/push/msg/all"

根据Installation 条件进行推送,下面是发送给中国地区用户的示例:

$ curl -X POST \
-H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
-H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
-H "Content-Type: application/json" \
-d '{
   "criteria":"{\"local\":\"cn\"}" ,
   "alert":"hello maxleap",
   "aps": {
          "alert": {
            "title": "Tips",
            "body": "hello maxleap,I'm from china",
            "action-loc-key": "PLAY",
            "title-loc-key": "abc",
            "title-loc-args": [
              "1",
              "2"
            ],
            "loc-key": "abc",
            "loc-args": [
              "3"
            ],
            "launch-image": "string"
          },
          "badge": 1,
          "sound": "default",
          "content-available": 1
        },
   "customKey":"name"
}' "https://api.maxleap.cn/2.0/marketing/push/msg/all"

criteria 为指定推送条件,格式为string 类型。

获取可用Android 推送服务器

IOS 设备默认使用苹果的APNS服务器,Android 推送使用的是MaxLeap 的推送服务器,用户首先需要根据设备的InstallationId 和AppId 获取可用的服务器,然后进行连接。

$ curl -X GET \
 -H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
 -H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ"\
 -H "Content-Type: application/json" \
 "https://api.maxleap.cn/2.0/gopush/server/get?k=a43f00f741b55a231cd25da08413ca3c&p=2"

其中k=Md5(appId+installId).toHexString(),p为指定使用的协议类型,支持WebSocket(1)TCP(2),成功返回数据如下:

{
  "data": {
    "server": [
      "push1.maxleap.cn:6031",
      "push1.maxleap.cn:6041"
    ]
  },
  "ret": 0
}

ret 返回值为错误码,server 为可以用服务列表。

公共返回码

错误码描述
0成功
65534参数错误
65535内部错误

获取Android离线消息

  • 请求参数
参数类型描述
kstringk=Md5(appId+installId).toHexString()
mnumber最新接受的私有消息的ID
cbstring返回jsonp结构函数名(可选)
$ curl -X GET \
-H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
-H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
-H "Content-Type: application/json" \
 "https://api.maxleap.cn/2.0/gopush/msg/get?k=a43f00f741b55a231cd25da08413ca3c&m=0"
  • 返回结果说明
参数类型描述
msgs数组私有离线消息
{
  "data": {
    "msgs": [
      {
        "msg": {
          "alert": "hello"
        },
        "mid": 14624164300040908,
        "gid": 0
      }
    ]
  },
  "ret": 0
}

获取初始消息ID

  • 请求参数
参数类型描述
cbstring返回jsonp结构函数名(可选)
$ curl -X GET \
-H "X-ML-AppId: 569d84a0169e7d00012c7afe" \
-H "X-ML-APIKey: MjVvSjJUMTZveUR2d1hoNlVoQ0R1QQ" \
-H "Content-Type: application/json" \
 "https://api.maxleap.cn/2.0/gopush/time/get"
  • 返回结果说明

| 参数 | 类型 | 描述 | | —— | —— | —— | | timeid | string | 初始消息ID |

{
  "data": {
    "timeid": 14624168551915608
  },
  "ret": 0
}

FAQ

iOS 证书生成

请参考文档

用户支持

内容更新中,敬请期待。。。