编辑文档 更新于

云函数开发指南 · Node.js

云函数是云引擎（LeanEngine）的一个子模块，请确保在阅读本文档之前已经阅读了 云引擎服务概览。

当你开发移动端应用时，可能会有下列需求：

  • 应用在多平台客户端（Android、iOS、Windows Phone、浏览器等）中很多逻辑都是一样的，希望将这部分逻辑抽取出来只维护一份。
  • 有些逻辑希望能够较灵活的调整（比如某些个性化列表的排序规则），但又不希望频繁的更新和发布移动客户端。
  • 有些逻辑需要的数据量很大，或者运算成本高（比如某些统计汇总需求），不希望在移动客户端进行运算，因为这样会消耗大量的网络流量和手机运算能力。
  • 当应用执行特定操作时，由云端系统自动触发一段逻辑（称为 Hook 函数），例如用户注册后对该用户增加一些信息记录用于统计；或某业务数据发生变化后希望做一些别的业务操作。
  • 客户端提供能够越过 ACL 或表权限的限制，对数据进行操作。
  • 需要定时任务，比如每天凌晨清理垃圾注册账号等。

这时，你可以使用云引擎的云函数，云函数是一段部署在服务端的代码，编写 JavaScript、Python、PHP 或 Java 代码，并部署到我们的平台上，可以很好的完成上述需求。

如果还不知道如何创建云引擎项目、本地调试并部署到云端，请阅读 云引擎快速入门。

多语言支持

云引擎支持多种语言的运行环境，你可以选择自己熟悉的语言开发应用：

切换云引擎环境

云引擎应用有「生产环境」和「预备环境」之分。 在云引擎通过 SDK 调用云函数时，包括显式调用以及隐式调用（由于触发 hook 条件导致 hook 函数被调用）， SDK 会根据云引擎所属环境（预备、生产）调用相应环境的云函数。 例如，假定定义了 beforeDelete 云函数，在预备环境通过 SDK 删除一个对象，会触发预备环境的 beforeDelete hook 函数。

在云引擎以外的环境通过 SDK 显式或隐式调用云函数时，X-LC-Prod 的默认值一般为 1，也就是调用生产环境。 但由于历史原因，各 SDK 的具体行为有一些差异：

  • 在 Node.js、PHP、Java 这三个 SDK 下，默认总是调用生产环境的云函数。
  • 在 Python SDK 下，配合 lean-cli 本地调试时，且应用存在预备环境时，默认调用预备环境的云函数，其他情况默认调用生产环境的云函数。
  • 云引擎 Java 环境的模板项目 java-war-getting-started 和 spring-boot-getting-started 做了处理，配合 lean-cli 本地调试时，且应用存在预备环境时，默认调用预备环境的云函数，其他情况默认调用生产环境的云函数（与 Python SDK 的行为一致）。

你还可以在 SDK 中指定客户端将请求所发往的环境：

[AVCloud setProductionMode:NO]; // 调用预备环境

AVCloud.setProductionMode(false); // 调用预备环境

LeanClient::useProduction(false); // 调用预备环境

AV.setProduction(false); // 调用预备环境

leancloud.use_production(False) # 调用预备环境
# 注意：需要在 SDK 初始化语句（`leancloud.init`）之前调用。

免费版云引擎 应用只有「生产环境」，因此请不要切换到预备环境。

云函数

示例项目 中 cloud.js 文件定义了一个很简单的 hello 云函数。现在让我们看一个较复杂的例子来展示云引擎的用途。在云端进行计算的一个重要理由是，你不需要将大量的数据发送到设备上做计算，而是将这些计算放到服务端，并返回结果这一点点信息就好。

例如，你写了一个应用，让用户对电影评分，一个评分对象大概是这样：

{
  "movie": "夏洛特烦恼",
  "stars": 5,
  "comment": "夏洛一梦，笑成麻花"
}

stars 表示评分，1-5。如果你想查找《夏洛特烦恼》这部电影的平均分，你可以找出这部电影的所有评分，并在设备上根据这个查询结果计算平均分。但是这样一来，尽管你只是需要平均分这样一个数字，却不得不耗费大量的带宽来传输所有的评分。通过云引擎，我们可以简单地传入电影名称，然后返回电影的平均分。

Cloud 函数接收 JSON 格式的请求对象，我们可以用它来传入电影名称。整个 JavaScript SDK 都在云引擎运行环境上有效，可以直接使用，所以我们可以使用它来查询所有的评分。结合在一起，实现 averageStars 函数的代码如下：

AV.Cloud.define('averageStars', function(request) {
  var query = new AV.Query('Review');
  query.equalTo('movie', request.params.movie);
  return query.find().then(function(results) {
    var sum = 0;
    for (var i = 0; i < results.length; i++ ) {
      sum += results[i].get('stars');
    }
    return sum / results.length;
  });
});

参数和返回值

Request 会作为参数传入到云函数中，Request 上的属性包括：

  • params: object：客户端发送的参数对象，当使用 rpc 调用时，也可能是 AV.Object。
  • currentUser?: AV.User：客户端所关联的用户（根据客户端发送的 X-LC-Session 头）。
  • sessionToken?: string：客户端发来的 sessionToken（X-LC-Session 头）。
  • meta: object：有关客户端的更多信息，目前只有一个 remoteAddress 属性表示客户端的 IP。

另外，AV.Cloud.define 还接受一个可选参数 options (位置在函数名称和调用函数之间)。 这个 options 对象上的属性包括：

  • fetchUser: boolean：是否自动抓取客户端的用户信息，默认为真。设置为假时，Request 将不会有 currentUser 属性。
  • internal: boolean：是否只允许在云引擎内（使用 AV.Cloud.run 且未开启 remote 选项）或使用 master key （使用 AV.Cloud.run 时传入 useMasterKey）调用，不允许客户端直接调用。默认为假。

例如，假设我们不希望客户端直接调用上述函数，也不关心客户端用户信息，那么上述函数的定义可以改写为：

AV.Cloud.define('averageStars', {fetchUser: false, internal: true}, function(request) {
  // 定义同上
});

如果云函数返回了一个 Promise，那么云函数会使用 Promise 成功结束后的结果作为成功响应；如果 Promise 中发生了错误，云函数会使用这个错误作为错误响应，对于使用 AV.Cloud.Error 构造的异常对象，我们认为是客户端错误，不会在标准输出打印消息，对于其他异常则会在标准输出打印调用栈，以便排查错误。

我们推荐大家使用链式的 Promise 写法来完成业务逻辑，这样会极大地方便异步任务的处理和异常处理，请注意一定要将 Promise 串联起来并在云函数中 return 以保证上述逻辑正确工作，推荐阅读 JavaScript Promise 迷你书 来深入地了解 Promise。

在 2.0 之前的早期版本中，云函数接受 request 和 response 两个参数，我们会继续兼容这种用法到下一个大版本，希望开发者尽快迁移到 Promise 风格的云函数上。之前版本的文档见《Node SDK v1 API 文档》。

SDK 调用云函数

LeanCloud 各个语言版本的 SDK 都提供了调用云函数的接口。

// 在 iOS SDK 中，AVCloud 提供了一系列静态方法来实现客户端调用云函数
// 构建传递给服务端的参数字典
NSDictionary *dicParameters = [NSDictionary dictionaryWithObject:@"夏洛特烦恼"
                                                          forKey:@"movie"];

// 调用指定名称的云函数 averageStars，并且传递参数
[AVCloud callFunctionInBackground:@"averageStars"
                   withParameters:dicParameters
                   block:^(id object, NSError *error) {
                   if(error == nil){
                     // 处理结果
                   } else {
                     // 处理报错
                   }
}];

// 在 Android SDK 中，AVCloud 提供了一系列的静态方法来实现客户端调用云函数
// 构建参数
Map<String, String> dicParameters = new HashMap<String, String>();
dicParameters.put("movie", "夏洛特烦恼");

// 调用云函数 averageStars
AVCloud.callFunctionInBackground("averageStars", dicParameters, new FunctionCallback() {
    public void done(Object object, AVException e) {
        if (e == null) {
            // 处理返回结果
        } else {
            // 处理报错
        }
    }
});

// 在 JavaScript 中 AV.Cloud 提供了一系列方法来调用云函数
var paramsJson = {
  movie: "夏洛特烦恼"
};
AV.Cloud.run('averageStars', paramsJson).then(function(data) {
  // 调用成功，得到成功的应答 data
}, function(err) {
  // 处理调用失败
});

use \LeanCloud\Engine\Cloud;
$params = array(
    "movie" => "夏洛特烦恼"
);
Cloud::run("averageStars", $params);

from leancloud import cloudfunc

cloudfunc.run('averageStars', movie='夏洛特烦恼')

通过 REST API 调用云函数

请查看我们的 云引擎 REST API 使用指南。

云引擎调用云函数

在云引擎中可以使用 AV.Cloud.run 调用 AV.Cloud.define 定义的云函数：

AV.Cloud.run('averageStars', {
  movie: '夏洛特烦恼',
}).then(function(data) {
  // 调用成功，得到成功的应答 data
}, function(error) {
  // 处理调用失败
});

云引擎中默认会直接进行一次本地的函数调用，而不会像客户端一样发起一个 HTTP 请求。如果你希望发起 HTTP 请求来调用云函数，可以传入一个 remote: true 的选项。当你在云引擎之外运行 Node SDK 时（包括在拓展分组的云引擎上调用主分组上的云函数时）这个选项非常有用：

AV.Cloud.run('averageStars', {movie: '夏洛特烦恼'}, {remote: true}).then(function(data) {
  // 成功
}, function(error) {
  // 失败
});

上面的 remote 选项实际上是作为 AV.Cloud.run 的可选参数 options 对象的属性传入的。 这个 options 对象包括以下参数：

  • remote?: boolean：上面的例子用到的 remote 选项，默认为假。
  • user?: AV.User：以特定的用户运行云函数（建议在 remote 为假时使用）。
  • sessionToken?: string：以特定的 sessionToken 调用云函数（建议在 remote 为真时使用）。
  • req?: http.ClientRequest | express.Request：为被调用的云函数提供 remoteAddress 等属性。

RPC 调用云函数

RPC 调用云函数是指：云引擎会在这种调用方式下自动为 Http Response Body 做序列化，而 SDK 调用之后拿回的返回结果就是一个完整的 AVObject。

NSDictionary *dicParameters = [NSDictionary dictionaryWithObject:@"夏洛特烦恼"
                                                          forKey:@"movie"];

[AVCloud rpcFunctionInBackground:@"averageStars"
                  withParameters:parameters
                  block:^(id object, NSError *error) {
                  if(error == nil){
                     // 处理结果
                  }
                  else {
                     // 处理报错
                  }
}];

// 构建参数
Map<String, String> dicParameters = new HashMap<String, String>();
dicParameters.put("movie", "夏洛特烦恼");

AVCloud.rpcFunctionInBackground("averageStars", dicParameters,
    new FunctionCallback<AVObject>() {
      @Override
      public void done(AVObject object, AVException e) {
        Assert.assertNull(e);
      }
    });

// PHP 暂不支持

var paramsJson = {
  movie: "夏洛特烦恼"
};

AV.Cloud.rpc('averageStars', paramsJson).then(function(object) {
  // 成功，如果云函数返回的是一个 AV.Object，回调参数中的 object 也会是一个 AV.Object
}, function(error) {
  // 失败
});

from leancloud import cloudfunc

cloudfunc.rpc('averageStars', movie='夏洛特烦恼')

云函数错误响应码

AV.Cloud.Error 的第二个参数中可以用 status 指定 HTTP 响应代码（默认为 400），还可以用 code 指定响应正文中的错误代码（默认为 1）：

AV.Cloud.define('errorCode', function(request) {
  return AV.User.logIn('NoThisUser', 'lalala');
});

客户端收到的响应：{"code":211,"error":"Could not find user"}

AV.Cloud.define('customErrorCode', function(request) {
  throw new AV.Cloud.Error('自定义错误信息', {code: 123});
});

客户端收到的响应： {"code":123,"error":"自定义错误信息"}

云函数超时

云函数超时时间为 15 秒，如果超过阈值，LeanEngine Node.js SDK 将强制响应：

  • 客户端收到 HTTP status code 为 503 响应，body 为 The request timed out on the server.。
  • 服务端会出现类似这样的日志：LeanEngine: /1.1/functions/<cloudFunc>: function timeout (15000ms)。

另外还需要注意：虽然 LeanEngine Node.js SDK 已经响应，但此时云函数可能仍在执行，但执行完毕后的响应是无意义的（不会发给客户端，会在日志中打印一个 Can't set headers after they are sent 的异常）。

超时的处理方案

我们建议将代码中的任务转化为异步队列处理，以优化运行时间，避免云函数或 定时任务 发生超时。比如：

  • 在存储服务中创建一个队列表，包含 status 列；
  • 接到任务后，向队列表保存一条记录，status 值设置为「处理中」，然后将请求结束掉，将队列对象的 id 发给客户端（旧版本的 SDK 使用 response.success(id)）：
  return new Promise( (resolve, reject) => {
    resolve(id);
  });
  • 当业务处理完毕，根据处理结果更新刚才的队列对象状态，将 status 字段设置为「完成」或者「失败」；
  • 在任何时候，在控制台通过队列 id 可以获取某个任务的执行结果，判断任务状态。

Hook 函数

Hook 函数本质上是云函数，但它有固定的名称，定义之后会由系统在特定事件或操作（如数据保存前、保存后，数据更新前、更新后等等）发生时自动触发，而不是由开发者来控制其触发时机。

需要注意：

对于 before 类的 Hook（也包括 onLogin），如果返回了一个错误的话，这个操作就会被中断，你可以在这些 Hook 中主动抛出一个错误来拒绝掉某些操作；对于 after 类的 Hook（也包括 onVerified），返回错误并不会影响操作的执行（因为其实操作已经执行完了）。

graph LR
A((save)) -->D{object}
D-->E(new)
E-->|beforeSave|H{error?}
H-->N(No)
N-->B[create new object on the cloud]
B -->|afterSave|C((done))
H-->Y(Yes)
Y-->Z((interrupted))
D-->F(existing)
F-->|beforeUpdate|I{error?}
I-->Y
I-->V(No)
V-->G[update existing object on the cloud]
G-->|afterUpdate|C

graph LR
A((delete))-->|beforeDelete|H{error?}
H-->Y(Yes)
Y-->Z((interrupted))
H-->N(No)
N-->B[delete object on the cloud]
B -->|afterDelete|C((done))

为了认证 Hook 调用者的身份，我们的 SDK 内部会确认请求确实是从云引擎内网的云存储组件发出的，如果认证失败，可能会出现 Hook key check failed 的提示，如果在本地调试时出现这样的错误，请确保是通过命令行工具启动调试的。

beforeSave

在创建新对象之前，可以对数据做一些清理或验证。例如，一条电影评论不能过长，否则界面上显示不开，需要将其截断至 140 个字符：

AV.Cloud.beforeSave('Review', function(request) {
  var comment = request.object.get('comment');
  if (comment) {
    if (comment.length > 140) {
      // 截断并添加...
      request.object.set('comment', comment.substring(0, 137) + '...');
    }
  } else {
    // 不保存数据，并返回错误
    throw new AV.Cloud.Error('No comment!');
  }
});

上面的代码示例中，request.object 是被操作的 AV.Object。 除了 object 之外，request 上还有一个属性：

  • currentUser?: AV.User，表示发起操作的用户。

类似地，其他 hook 的 request 参数上也包括 object 和 currentUser 这两个属性。

在 2.0 之前的早期版本中，before 类 Hook 接受 request 和 response 两个参数，我们会继续兼容这种用法到下一个大版本，希望开发者尽快迁移到 Promise 风格的云函数上。之前版本的文档见《Node SDK v1 API 文档》。

afterSave

在创建新对象后触发指定操作，比如当一条留言创建后再更新一下所属帖子的评论总数：

AV.Cloud.afterSave('Comment', function(request) {
  var query = new AV.Query('Post');
  return query.get(request.object.get('post').id).then(function(post) {
    post.increment('comments');
    return post.save();
  });
});

再如，在用户注册成功之后，给用户增加一个新的属性 from 并保存：

AV.Cloud.afterSave('_User', function(request) {
  console.log(request.object);
  request.object.set('from','LeanCloud');
  return request.object.save().then(function(user)  {
    console.log('ok!');
  });
});

虽然对于 after 类的 Hook 我们并不关心返回值，但我们仍建议你返回一个 Promise，这样如果发生了非预期的错误，会自动在标准输出中打印异常信息和调用栈。

beforeUpdate

在更新已存在的对象前执行操作，这时你可以知道哪些字段已被修改，还可以在特定情况下拒绝本次修改：

AV.Cloud.beforeUpdate('Review', function(request) {
  // 如果 comment 字段被修改了，检查该字段的长度
  if (request.object.updatedKeys.indexOf('comment') != -1) {
    if (request.object.get('comment').length > 140) {
      // 拒绝过长的修改
      throw new AV.Cloud.Error('comment 长度不得超过 140 字符');
    }
  }
});

注意： 不要修改 request.object，因为对它的改动并不会保存到数据库，但可以抛出一个异常，拒绝这次修改。

注意：传入的对象是一个尚未保存到数据库的临时对象，并不保证与最终储存到数据库的对象完全相同，这是因为修改中可能包含自增、数组增改、关系增改等原子操作。

afterUpdate

本 Hook 使用不当可能会造成死循环，导致数据存储 API 的调用次数暴涨，甚至产生更多的费用。因此请仔细阅读 防止死循环调用 部分，做出必要的调整和预防措施。

在更新已存在的对象后执行特定的动作。和 beforeUpdate 一样，你可以知道哪些字段已被修改。

AV.Cloud.afterUpdate('Review', function(request) {
  if (request.object.updatedKeys.indexOf('comment') != -1) {
    if (request.object.get('comment').length < 5) {
      console.log("疑似灌水评论： " + comment + " 于点评 " + review.ObjectId)
    }
  }
});

防止死循环调用

在实际使用中有这样一种场景：在 Post 类的 afterUpdate Hook 函数中，对传入的 Post 对象做了修改并且保存，而这个保存动作又会再次触发 afterUpdate，由此形成死循环。针对这种情况，我们为所有 Hook 函数传入的 request.object 对象做了处理，以阻止死循环调用的产生。

不过请注意，以下情况还需要开发者自行处理：

  • 对传入的 request.object 对象进行 fetch 操作。
  • 重新构造传入的 request.object 对象，如使用 AV.Object.createWithoutData() 方法。

对于使用上述方式产生的对象，请根据需要自行调用以下 API：

  • object.disableBeforeHook() 或
  • object.disableAfterHook()

这样，对象的保存或删除动作就不会再次触发相关的 Hook 函数。

// 直接修改并保存对象不会再次触发 afterUpdate Hook 函数
request.object.set('foo', 'bar');
request.object.save().then(function(obj) {
  // 你的业务逻辑
});

// 如果有 fetch 操作，则需要在新获得的对象上调用相关的 disable 方法
// 来确保不会再次触发 Hook 函数
request.object.fetch().then(function(obj) {
  obj.disableAfterHook();
  obj.set('foo', 'bar');
  return obj.save();
}).then(function(obj) {
  // 你的业务逻辑
});

// 如果是其他方式构建对象，则需要在新构建的对象上调用相关的 disable 方法
// 来确保不会再次触发 Hook 函数
var obj = AV.Object.createWithoutData('Post', request.object.id);
obj.disableAfterHook();
obj.set('foo', 'bar');
obj.save().then(function(obj) {
  // 你的业务逻辑
});

beforeDelete

在删除一个对象之前做一些检查工作，比如在删除一个相册 Album 前，先检查一下该相册中还有没有照片 Photo：

AV.Cloud.beforeDelete('Album', function(request) {
  //查询Photo中还有没有属于这个相册的照片
  var query = new AV.Query('Photo');
  var album = AV.Object.createWithoutData('Album', request.object.id);
  query.equalTo('album', album);
  return query.count().then(function(count) {
    if (count > 0) {
      //还有照片，不能删除，调用error方法
      throw new AV.Cloud.Error('Can\'t delete album if it still has photos.');
    }
  }, function(error) {
    throw new AV.Cloud.Error('Error ' + error.code + ' : ' + error.message + ' when getting photo count.');
  });
});

afterDelete

在被删一个对象后执行操作，例如递减计数、删除关联对象等等。同样以相册为例，这次我们不在删除相册前检查是否还有照片，而是在删除后，同时删除相册中的照片：

AV.Cloud.afterDelete('Album', function(request) {
  var query = new AV.Query('Photo');
  var album = AV.Object.createWithoutData('Album', request.object.id);
  query.equalTo('album', album);
  return query.find().then(function(posts) {
    //查询本相册的照片，遍历删除
    return AV.Object.destroyAll(posts);
  }).catch(function(error) {
    console.error('Error finding related comments ' + error.code + ': ' + error.message);
  });
});

onVerified

当用户通过邮箱或者短信验证时，对该用户执行特定操作。比如：

AV.Cloud.onVerified('sms', function(request) {
  console.log('onVerified: sms, user: ' + request.object);
});

上面的代码示例中的 object 换成 currentUser 也可以。因为这里被操作的对象正好是发起操作的用户。 下面的 onLogin 函数同理。

函数的第一个参数是验证类型。短信验证为 sms，邮箱验证为 email。另外，数据库中相关的验证字段，如 emailVerified 不需要修改，系统会自动更新。

onLogin

在用户登录之时执行指定操作，比如禁止在黑名单上的用户登录：

AV.Cloud.onLogin(function(request) {
  // 因为此时用户还没有登录，所以用户信息是保存在 request.object 对象中
  console.log("on login:", request.object);
  if (request.object.get('username') == 'noLogin') {
    // 如果是 error 回调，则用户无法登录（收到 401 响应）
    throw new AV.Cloud.Error('Forbidden');
  }
});

即时通讯 Hook 函数

请阅读 即时通讯概览 · 云引擎 Hook 来了解以下函数的相关参数和用法。

onIMMessageReceived

在消息达到服务器、群组成员已解析完成、发送给收件人之前触发。例如，提前过滤掉聊天内容中的一些广告类的关键词：

AV.Cloud.onIMMessageReceived((request) => {
    // request.params = {
    //     fromPeer: 'Tom',
    //     receipt: false,
    //     groupId: null,
    //     system: null,
    //     content: '{"_lctext":"耗子，起床！","_lctype":-1}',
    //     convId: '5789a33a1b8694ad267d8040',
    //     toPeers: ['Jerry'],
    //     __sign: '1472200796787,a0e99be208c6bce92d516c10ff3f598de8f650b9',
    //     bin: false,
    //     transient: false,
    //     sourceIP: '121.239.62.103',
    //     timestamp: 1472200796764
    // };

    let content = request.params.content;
    console.log('content', content);
    let processedContent = content.replace('XX中介', '**');
    // 必须含有以下语句给服务端一个正确的返回，否则会引起异常
  return {
    content: processedContent
  };
});

onIMReceiversOffline

在消息发送完成时触发、对话中某些用户却已经下线，此时可以根据发送的消息来生成离线消息推送的标题等等。例如截取所发送消息的前 6 个字符作为推送的标题：

AV.Cloud.onIMReceiversOffline((request) => {
    let params = request.params;
    let content = params.content;

  // params.content 为消息的内容
    let shortContent = content;

    if (shortContent.length > 6) {
        shortContent = content.slice(0, 6);
    }

    console.log('shortContent', shortContent);

  return {
    pushMessage: JSON.stringify({
          // 自增未读消息的数目，不想自增就设为数字
          badge: "Increment",
          sound: "default",
          // 使用开发证书
          _profile: "dev",
          alert: shortContent
      })
  }
});

onIMMessageSent

消息发送完成之后触发，例如消息发送完后，在云引擎中打印一下日志：

AV.Cloud.onIMMessageSent((request) => {
    console.log('params', request.params);

    // 在云引擎中打印的日志如下：
    // params { fromPeer: 'Tom',
    //   receipt: false,
    //   onlinePeers: [],
    //   content: '12345678',
    //   convId: '5789a33a1b8694ad267d8040',
    //   msgId: 'fptKnuYYQMGdiSt_Zs7zDA',
    //   __sign: '1472703266575,30e1c9b325410f96c804f737035a0f6a2d86d711',
    //   bin: false,
    //   transient: false,
    //   sourceIP: '114.219.127.186',
    //   offlinePeers: [ 'Jerry' ],
    //   timestamp: 1472703266522 }
});

onIMConversationStart

创建对话，在签名校验（如果开启）之后、实际创建之前触发。例如对话创建时，在云引擎中打印一下日志：

AV.Cloud.onIMConversationStart((request) => {
    let params = request.params;
    console.log('params', params);

    // 在云引擎中打印的日志如下：
    // params {
    //     initBy: 'Tom',
    //     members: ['Tom', 'Jerry'],
    //     attr: {
    //         name: 'Tom & Jerry'
    //     },
    //     __sign: '1472703266397,b57285517a95028f8b7c34c68f419847a049ef26'
    // }
});

onIMConversationStarted

创建对话完成触发。例如对话创建之后，在云引擎打印一下日志：

AV.Cloud.onIMConversationStarted((request) => {
    let params = request.params;
    console.log('params', params);

    // 在云引擎中打印的日志如下：
    // params {
    //     convId: '5789a33a1b8694ad267d8040',
    //     __sign: '1472723167361,f5ceedde159408002fc4edb96b72aafa14bc60bb'
    // }
});

onIMConversationAdd

向对话添加成员，在签名校验（如果开启）之后、实际加入之前，包括主动加入和被其他用户加入两种情况都会触发，注意在创建对话时传入了其他用户的 clientId 作为 Member 参数，不会触发 onIMConversationAdd 。例如在云引擎中打印成员加入时的日志：

AV.Cloud.onIMConversationAdd((request) => {
    let params = request.params;
    console.log('params', params);

    // 在云引擎中打印的日志如下：
    // params {
    //     initBy: 'Tom',
    //     members: ['Mary'],
    //     convId: '5789a33a1b8694ad267d8040',
    //     __sign: '1472786231813,a262494c252e82cb7a342a3c62c6d15fffbed5a0'
    // }
});

onIMConversationRemove

从对话中踢出成员，在签名校验（如果开启）之后、实际踢出之前触发，用户自己退出对话不会触发。例如在踢出某一个成员时，在云引擎日志中打印出该成员的 clientId：

AV.Cloud.onIMConversationRemove((request) => {
    let params = request.params;
    console.log('params', params);
    console.log('removed client Id:', params.members[0]);

    // 在云引擎中打印的日志如下：
    // params {
    //     initBy: 'Tom',
    //     members: ['Jerry'],
    //     convId: '57c8f3ac92509726c3dadaba',
    //     __sign: '1472787372605,abdf92b1c2fc4c9820bc02304f192dab6473cd38'
    // }
    //removed client Id: Jerry
});

onIMConversationUpdate

修改对话属性、设置或取消对话消息提醒，在实际修改之前触发。例如在更新发生时，在云引擎日志中打印出对话的名称：

AV.Cloud.onIMConversationUpdate((request) => {
    let params = request.params;
    console.log('params', params);
    console.log('name', params.attr.name);

    // 在云引擎中打印的日志如下：
    // params {
    //     convId: '57c9208292509726c3dadb4b',
    //     initBy: 'Tom',
    //     attr: {
    //         name: '聪明的喵星人',
    //         type: 'public'
    //     },
    // name 聪明的喵星人
});

Hook 函数错误响应码

为 beforeSave 这类的 hook 函数定义错误码，需要这样：

AV.Cloud.beforeSave('Review', function(request) {
  // 使用 JSON.stringify() 将 object 变为字符串
  throw new AV.Cloud.Error(JSON.stringify({
    code: 123,
    message: '自定义错误信息'
  }));
});

客户端收到的响应为：Cloud Code validation failed. Error detail : {"code":123, "message": "自定义错误信息"}，然后通过截取字符串的方式取出错误信息，再转换成需要的对象。

Hook 函数超时

Hook 函数的超时时间为 3 秒。如果 Hook 函数被其他的云函数调用（比如因为 save 对象而触发 beforeSave 和 afterSave），那么它们的超时时间会进一步被其他云函数调用的剩余时间限制。

例如，如果一个 beforeSave 函数是被一个已经运行了 13 秒的云函数触发，那么 beforeSave 函数就只剩下 2 秒的时间来运行。同时请参考 云函数超时及处理方案。

在线编写云函数

很多人使用 LeanEngine 是为了在服务端提供一些个性化的方法供各终端调用，而不希望关心诸如代码托管、npm 依赖管理等问题。为此我们提供了在线维护云函数的功能。

使用此功能需要注意：

  • 在定义的函数会覆盖你之前用 Git 或命令行部署的项目。
  • 目前只能在线编写云函数和 Hook，不支持托管静态网页、编写动态路由。
  • 只能使用 SDK 和一些内置的模块（详见下节表格），无法引入其他模块作为依赖。

在 控制台 > 云引擎 > 部署 > 在线编辑 标签页，可以：

  • 创建函数：指定函数类型，函数名称，函数体的具体代码，注释等信息，然后「保存」即可创建一个云函数。
  • 部署：选择要部署的环境，点击「部署」即可看到部署过程和结果。
  • 预览：会将所有函数汇总并生成一个完整的代码段，可以确认代码，或者将其保存为 cloud.js 覆盖项目模板的同名文件，即可快速的转换为使用项目部署。
  • 维护云函数：可以编辑已有云函数，查看保存历史，以及删除云函数。

云函数编辑之后需要点击 部署 才能生效。

在线编写的 SDK 版本

目前在线编辑仅支持 Node.js，提供了 4 种 SDK 版本：

在线编辑版本 Node SDK JS SDK Node.js 备注 可用依赖
v0 0.x 0.x 0.12 已不推荐使用 moment, request, underscore
v1 1.x 1.x 4 async, bluebird, co, ejs, handlebars, joi, lodash, marked, moment, q, request, superagent, underscore
v2 2.x 2.x 6 需要使用 Promise 写法 async, bluebird, crypto, debug, ejs, jade, lodash, moment, nodemailer, qiniu, redis, request, request-promise, superagent, underscore, uuid, wechat-api, xml2js
v3 3.x 3.x 8 需要使用 Promise 写法 async, bluebird, crypto, debug, ejs, jade, lodash, moment, nodemailer, qiniu, redis, request, request-promise, superagent, underscore, uuid, wechat-api, xml2js

从 v0 升级到 v1：

  • JS SDK 升级到了 1.0
  • 需要从 request.currentUser 获取用户，而不是 AV.User.current
  • 在调用 AV.Cloud.run 时需要手动传递 user 对象

从 v1 升级到 v2：

  • JS SDK 升级到 2.0（必须使用 Promise，不再支持 callback 风格）
  • 删除了 AV.Cloud.httpRequest
  • 在云函数中 必须 返回 Promise 作为云函数的值，抛出 AV.Cloud.Error 来表示错误。

从 v2 升级到 v3：

  • JS SDK 升级到了 3.0（AV.Object#toJSON 的行为变化等）

定时任务

定时任务可以按照设定，以一定间隔自动完成指定动作，比如半夜清理过期数据，每周一向所有用户发送推送消息等等。定时任务的最小时间单位是秒，正常情况下时间误差都可以控制在秒级别。

定时任务是普通的云函数，也会遇到 超时问题，具体请参考 超时处理方案。

一个定时器如果在 24 小时内收到了超过 30 次的 400 (Bad Request) 或 502 (Bad Gateway) 的应答，它将会被云引擎禁用，同时系统会向开发者发出相关的禁用通知邮件。在控制台的日志中，对应的错误信息为 timerAction short-circuited and no fallback available。

部署云引擎之后，进入 控制台 > 云引擎 > 定时任务，点击 创建定时器，然后设定执行的函数名称、执行环境等等。例如定义一个打印循环打印日志的任务 log_timer：

AV.Cloud.define('log_timer', function(request){
  console.log('Log in timer.');
});

定时器创建后，其状态为未运行，需要点击 启用 来激活。之后其执行日志可以在 日志 页面中查看。

定时任务分为两类：

  • 使用 Cron 表达式安排调度
  • 以秒为单位的简单循环调度

以 Cron 表达式为例，比如每周一早上 8 点准时发送推送消息给用户：

AV.Cloud.define('push_timer', function(request){
  return AV.Push.send({
    channels: ['Public'],
    data: {
      alert: 'Public message'
    }
  });
});

创建定时器的时候，选择 Cron 表达式 并填入 0 0 8 ? * MON。

Cron 表达式

Cron 表达式的基本语法为：

<秒> <分钟> <小时> <日期 day-of-month> <月份> <星期 day-of-week>
位置 字段 约束 取值 可使用的特殊字符
1 秒 必须 0-59 , - * /
2 分钟 必须 0-59 , - * /
3 小时 必须 0-23（0 为午夜） , - * /
4 日期 必须 1-31 , - * ? /
5 月份 必须 1-12、JAN-DEC , - * /
6 星期 必须 1-7、SUN-SAT , - ? /

特殊字符的用法：

字符 含义 用法
* 所有值 代表一个字段的所有可能取值。如将 <分钟> 设为 *，表示每一分钟。
? 不指定值 用于可以使用该字符的两个字段中的一个，在一个表达式中只能出现一次。如任务执行时间为每月 10 号，星期几无所谓，那么表达式中 <日期> 设为 10，<星期> 设为 ?。
- 范围 如 <小时> 为 10-12，即10 点、11 点、12 点。
, 分隔多个值 如 <星期> 为 MON,WED,FRI，即周一、周三、周五。
/ 增量 如 <秒> 设为 0/15，即从 0 秒开始，以 15 秒为增量，包括 0、15、30、45 秒；5/15 即 5、20、35、50 秒。*/ 与 0/ 等效，如 <日期> 设为 1/3，即从每个月的第一天开始，每 3 天（即每隔 2 天）执行一次任务。

各字段以空格或空白隔开。JAN-DEC、SUN-SAT 这些值不区分大小写，比如 MON 和 mon 效果一样。

举例如下：

表达式 说明
0 */5 * * * ? 每隔 5 分钟执行一次
10 */5 * * * ? 每隔 5 分钟执行一次，每次执行都在分钟开始的 10 秒，例如 10:00:10、10:05:10 等等。
0 30 10-13 ? * WED,FRI 每周三和每周五的 10:30、11:30、12:30、13:30 执行。
0 */30 8-9 5,20 * ? 每个月的 5 号和 20 号的 8 点和 10 点之间每隔 30 分钟执行一次，也就是 8:00、8:30、9:00 和 9:30。

定时器数量

生产环境和预备环境的定时器数量都限制在 6 个以内，也就是说你总共最多可以创建 12 个定时器。

错误信息

定时器执行后的日志会记录在 控制台 > 云引擎 > 日志 中，以下为常见的错误信息及原因。

  • timerAction timed-out and no fallback available
    某个定时器触发的云函数，因 15 秒内没有响应而超时（可参考 对云函数调用超时的处理）。
  • timerAction short-circuited and no fallback available
    某个定时器触发的云函数，因为太多次超时而停止触发。

Master Key 和超级权限

因为云引擎运行在可信的服务器端环境中，所以你可以全局开启超级权限（Master Key），这样云端会跳过包括 ACL 和 Class 权限在内的检查，让你自由地操作所有云存储中的数据，当然这种方式也允许调用一些仅供 masterKey 使用的 API。开启 Master Key 的方法如下：

// 通常位于 server.js
AV.Cloud.useMasterKey();

如果没有添加这些代码，默认是没有超级权限的，这意味着在云引擎中你也不能修改被 ACL 保护的数据，你需要在进行操作时手动指定 sessionToken，让操作以这个用户的权限来执行：

var post = new Post();
post.save({
  author: user
}, {
  // 或者使用 request.sessionToken（网站托管中需启用 `Cloud.CookieSession`）
  sessionToken: user.getSessionToken()
});

或者你也可单独对某一个操作使用 Master Key，跳过权限检查：

post.destroy({useMasterKey: true});

当然你也可以在启用了超级权限的情况下使用 useMasterKey: false 来对单个操作关掉超级权限。

那么究竟是否应该使用超级权限呢，我们的建议如下：

  • 如果你的云引擎代码中特权操作比较多、操作不属于用户的全局数据比较多，那么建议全局开启 Master Key，并自行做好对于用户请求的权限检查。
  • 如果你的云引擎代码中的请求通常和单个用户自己的数据相关、需要遵守 ACL，那么建议不开启 Master Key，将用户请求的 sessionToken 传入数据修改的相关操作（如 save）。

关于云引擎上的权限问题，还可以参考 ACL 与数据安全 和 在云引擎中使用 ACL。

{{allComment[version]}} ×
  • 暂无评论
  • {{comment.author}}
    {{ comment.createdAt | date: 'yyyy-MM-dd HH:mm:ss '}}
    {{comment.content}}
您需要 后才能评论