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;
});
});
LCEngine.run("averageStars", parameters: ["movie": "夏洛特烦恼"]) { (result) in
switch result {
case .success(value: let resultValue):
print(resultValue)
case .failure(error: let error):
print(error)
}
}
var paramsJson = {
movie: "夏洛特烦恼"
};
AV.Cloud.run('averageStars', paramsJson).then(function (data) {
// 处理结果
}, function (err) {
// 处理报错
});
from leancloud import cloudfunc
cloudfunc.run('averageStars', movie='夏洛特烦恼')
LCEngine.call("averageStars", parameters: ["movie": "夏洛特烦恼"]) { (result) in
switch result {
case .success(object: let object):
if let object = object {
print(object)
}
case .failure(error: let error):
print(error)
}
}
var paramsJson = {
movie: "夏洛特烦恼"
};
AV.Cloud.rpc('averageStars', paramsJson).then(function (object) {
// 处理结果
}, function (error) {
// 处理报错
});
from leancloud import cloudfunc
cloudfunc.rpc('averageStars', movie='夏洛特烦恼')
AV.Cloud.define('errorCode', function (request) {
return AV.User.logIn('NotThisUser', 'P@ssword');
});
客户端收到的响应：{ "code": 211, "error": "Could not find the user." }。
AV.Cloud.define('customErrorCode', function (request) {
throw new AV.Cloud.Error('自定义错误信息。', { code: 123 });
});
客户端收到的响应：{ "code": 123, "error": "自定义错误信息。" }。
云函数超时
云函数超时时间为 15 秒，如果超过阈值，客户端将收到 HTTP status code 为 503 的响应，body 为 The request timed out on the server。服务端会出现类似这样的日志：LeanEngine: /1.1/functions/<cloudFunc>: function timeout (15000ms)。注意即使已经响应，此时云函数可能仍在执行，但执行完毕后的响应是无意义的（不会发给客户端，会在日志中打印一个 Can't set headers after they are sent 的异常）。
除了 503 错误外，有些情况下客户端也可能收到其他报错，如 524 或 141。
超时的处理方案
我们建议将代码中的任务转化为异步队列处理，以优化运行时间，避免云函数或定时任务发生超时。
例如：
在存储服务中创建一个队列表，包含 status 列；
接到任务后，向队列表保存一条记录，status 值设置为 处理中，然后将请求结束掉，将队列对象的 id 发给客户端（旧版本的 SDK 使用 response.success(id)）：
return new Promise((resolve, reject) => {
resolve(id);
});
当业务处理完毕，根据处理结果更新刚才的队列对象状态，将 status 字段设置为 完成 或者 失败；
在任何时候，在控制台通过队列 id 可以获取某个任务的执行结果，判断任务状态。
注意，对于 before 类 hook 函数，改为异步处理通常没有意义。
虽然改为异步后能保证 before 类函数能够运行完成，不会因超时而报错。
但是，只要 before 类 hook 函数不能及时抛出异常，就无法起到中断操作执行的作用。
对于超时的 before 类 hook 函数，如果无法优化代码，压缩执行时间的话，那只能改为 after 类函数。
例如，假设某个 beforeSave 函数需要调用耗时较久的第三方的自然语言处理接口判断用户提交的评论是否来自真实用户，导致超时，
那么可以改为 afterSave 函数，在保存评论后再调用第三方接口，如果判断是水军评论，那么再行删除。
对于 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))
在删除一个对象之前做一些检查工作，比如在删除一个相册 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) {
// delete 操作会被丢弃
throw new AV.Cloud.Error('Cannot delete an album if it still has photos in it.');
}
}, function (error) {
throw new AV.Cloud.Error('Error ' + error.code + ' occurred when finding photos: ' + error.message);
});
});
var post = new Post();
post.save(
{ author: user },
{
// 或者使用 request.sessionToken（网站托管中需启用 `Cloud.CookieSession`）
sessionToken: user.getSessionToken()
}
);
云函数开发指南 · Node.js
云函数是云引擎（LeanEngine）的一个子模块，请确保在阅读本文档之前已经阅读了 云引擎服务概览。
当你开发移动端应用时，可能会有下列需求：
这时，你可以使用云引擎的云函数，云函数是一段部署在服务端的代码，编写 JavaScript、Python、PHP 或 Java 代码，并部署到我们的平台上，可以很好地完成上述需求。
如果还不知道如何创建云引擎项目、本地调试并部署到云端，请阅读 云引擎快速入门。
多语言支持
云引擎支持多种语言的运行环境，你可以选择自己熟悉的语言开发应用：
切换云引擎环境
云引擎应用有「生产环境」和「预备环境」之分。在云引擎通过 SDK 调用云函数时，包括显式调用以及隐式调用（由于触发 hook 条件导致 hook 函数被调用），SDK 会根据云引擎所属环境（预备、生产）调用相应环境的云函数。例如，假定定义了
beforeDelete云函数，在预备环境通过 SDK 删除一个对象，会触发预备环境的beforeDeletehook 函数。在云引擎以外的环境通过 SDK 显式或隐式调用云函数时，
X-LC-Prod的默认值一般为1，也就是调用生产环境。但由于历史原因，各 SDK 的具体行为有一些差异：你还可以在 SDK 中指定客户端将请求所发往的环境：
免费版云引擎 应用只有「生产环境」，因此请不要切换到预备环境。
云函数
示例项目 中
cloud.js文件定义了一个很简单的hello云函数。在云端进行计算的一个重要理由是，你不需要将大量的数据发送到设备上做计算，而是将这些计算放到服务端，并返回结果这一点点信息就好。现在让我们看一个较复杂的例子来展示云引擎的用途。
例如，你写了一个应用，让用户对电影评分，一个评分对象大概是这样：
stars表示评分，1-5。如果你想查找《夏洛特烦恼》这部电影的平均分，你可以找出这部电影的所有评分，并在设备上根据这个查询结果计算平均分。但是这样一来，尽管你只是需要平均分这样一个数字，却不得不耗费大量的带宽来传输所有的评分。通过云引擎，我们可以简单地传入电影名称，然后返回电影的平均分。云函数接收 JSON 格式的请求对象，我们可以用它来传入电影名称。整个 LeanStorage JavaScript SDK 都在云引擎运行环境上有效，可以直接使用，所以我们可以使用它来查询所有的评分。结合在一起，实现
averageStars函数的代码如下：参数和返回值
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）调用，不允许客户端直接调用。默认为假。例如，假设我们不希望客户端直接调用上述函数，也不关心客户端用户信息，那么上述函数的定义可以改写为：
如果云函数返回了一个 Promise，那么云函数会使用 Promise 成功结束后的结果作为成功响应；如果 Promise 中发生了错误，云函数会使用这个错误作为错误响应，对于使用
AV.Cloud.Error构造的异常对象，我们认为是客户端错误，不会在标准输出打印消息，对于其他异常则会在标准输出打印调用栈，以便排查错误。我们推荐大家使用链式的 Promise 写法来完成业务逻辑，这样会极大地方便异步任务的处理和异常处理，请注意一定要将 Promise 串联起来并在云函数中 return 以保证上述逻辑正确工作，推荐阅读 JavaScript Promise 迷你书 来深入地了解 Promise。
在 2.0 之前的早期版本中，云函数接受
request和response两个参数，我们会继续兼容这种用法到下一个大版本，希望开发者尽快迁移到 Promise 风格的云函数上。之前版本的文档见《Node SDK v1 API 文档》。SDK 调用云函数
LeanCloud 各个语言版本的 SDK 都提供了调用云函数的接口：
通过 REST API 调用云函数
请查看我们的 云引擎 REST API 使用指南。
云引擎调用云函数
在云引擎中可以使用
AV.Cloud.run调用AV.Cloud.define定义的云函数：云引擎中默认会直接进行一次本地的函数调用，而不会像客户端一样发起一个 HTTP 请求。如果你希望发起 HTTP 请求来调用云函数，可以传入一个
remote: true的选项。当你在云引擎之外运行 Node.js SDK 时（包括在拓展分组的云引擎上调用主分组上的云函数时）这个选项非常有用：上面的
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 调用之后拿回的返回结果就是一个完整的
AV.Object或包含这样的对象的数据结构：云函数错误响应码
可以根据 HTTP status codes 自定义错误响应码。
客户端收到的响应：
{ "code": 211, "error": "Could not find the user." }。客户端收到的响应：
{ "code": 123, "error": "自定义错误信息。" }。云函数超时
云函数超时时间为 15 秒，如果超过阈值，客户端将收到 HTTP status code 为
503的响应，body 为The request timed out on the server。服务端会出现类似这样的日志：LeanEngine: /1.1/functions/<cloudFunc>: function timeout (15000ms)。注意即使已经响应，此时云函数可能仍在执行，但执行完毕后的响应是无意义的（不会发给客户端，会在日志中打印一个Can't set headers after they are sent的异常）。 除了503错误外，有些情况下客户端也可能收到其他报错，如524或141。超时的处理方案
我们建议将代码中的任务转化为异步队列处理，以优化运行时间，避免云函数或定时任务发生超时。
例如：
status列；status值设置为处理中，然后将请求结束掉，将队列对象的id发给客户端（旧版本的 SDK 使用response.success(id)）：status字段设置为完成或者失败；id可以获取某个任务的执行结果，判断任务状态。注意，对于 before 类 hook 函数，改为异步处理通常没有意义。 虽然改为异步后能保证 before 类函数能够运行完成，不会因超时而报错。 但是，只要 before 类 hook 函数不能及时抛出异常，就无法起到中断操作执行的作用。 对于超时的 before 类 hook 函数，如果无法优化代码，压缩执行时间的话，那只能改为 after 类函数。 例如，假设某个 beforeSave 函数需要调用耗时较久的第三方的自然语言处理接口判断用户提交的评论是否来自真实用户，导致超时， 那么可以改为 afterSave 函数，在保存评论后再调用第三方接口，如果判断是水军评论，那么再行删除。
Hook 函数
Hook 函数本质上是云函数，但它有固定的名称，定义之后会 由系统 在特定事件或操作（如数据保存前、保存后，数据更新前、更新后等等）发生时 自动触发，而不是由开发者来控制其触发时机。需要注意：
_Installation表暂不支持 Hook 函数。对于
before类的 Hook（也包括onLogin），如果返回了一个错误的话，这个操作就会被中断，你可以在这些 Hook 中主动抛出一个错误来拒绝掉某些操作。对于after类的 Hook（也包括onVerified），返回错误并不会影响操作的执行（因为其实操作已经执行完了）。为了认证 Hook 调用者的身份，我们的 SDK 内部会确认请求确实是从云引擎内网的云存储组件发出的，如果认证失败，可能会出现
Hook key check failed的提示，如果在本地调试时出现这样的错误，请确保是通过命令行工具启动调试的。beforeSave在创建新对象之前，可以对数据做一些清理或验证。例如，一条电影评论不能过长，否则界面上显示不开，需要将其截断至 140 个字符：
上面的代码示例中，
request.object是被操作的AV.Object。除了object之外，request上还有一个属性：currentUser?: AV.User：发起操作的用户。类似地，其他 hook 的
request参数上也包括object和currentUser这两个属性。afterSave在创建新对象后触发指定操作，比如当一条留言创建后再更新一下所属帖子的评论总数：
再如，在用户注册成功之后，给用户增加一个新的属性
from并保存：虽然对于
after类的 Hook 我们并不关心返回值，但我们仍建议你返回一个 Promise，这样如果发生了非预期的错误，会自动在标准输出中打印异常信息和调用栈。beforeUpdate在更新已存在的对象前执行操作，这时你可以知道哪些字段已被修改，还可以在特定情况下拒绝本次修改：
对
request.object直接进行的修改不会被保存。如需拒绝修改，可以让函数返回一个错误。传入的对象是一个尚未保存到数据库的临时对象，并不保证与最终储存到数据库的对象完全相同，这是因为修改中可能包含自增、数组增改、关系增改等原子操作。
afterUpdate本 Hook 使用不当可能会造成死循环，导致数据存储 API 的调用次数暴涨，甚至产生更多的费用。因此请仔细阅读 防止死循环调用 部分，做出必要的调整和预防措施。
在更新已存在的对象后执行特定的动作。和
beforeUpdate一样，你可以知道哪些字段已被修改。防止死循环调用
你也许会好奇为什么可以在
afterUpdate中保存post而不会再次触发该 hook。这是因为云引擎对所有传入request.object的对象做了处理，以阻止死循环调用的产生。不过请注意，以下情况还需要开发者自行处理：
request.object对象进行fetch操作。request.object对象，如使用AV.Object.createWithoutData()方法。对于使用上述方式产生的对象，请根据需要自行调用
object.disableBeforeHook()或object.disableAfterHook()：beforeDelete在删除一个对象之前做一些检查工作，比如在删除一个相册
Album前，先检查一下该相册中还有没有照片Photo：afterDelete在一个对象后被删执行操作，例如递减计数、删除关联对象等等。同样以相册为例，这次我们不在删除相册前检查是否还有照片，而是在删除后，同时删除相册中的照片：
onVerified当用户通过邮箱或者短信验证时，对该用户执行特定操作。比如：
上面的代码示例中的
object换成currentUser也可以。因为这里被操作的对象正好是发起操作的用户。 下面的onLogin函数同理。函数的第一个参数是验证类型。短信验证为
sms，邮箱验证为email。数据库中相关的验证字段，如
emailVerified不需要修改，系统会自动更新。onLogin在用户登录之时执行指定操作，比如禁止在黑名单上的用户登录：
再比如校验第三方登录的 access token：
假设某 Example 平台的
authData如下：平台名称为
example_platform。 那么我们可以定义如下onLogin函数：注意，上面的示例片段仅为示意，为了简短省略了许多逻辑，包括 token 时效性检查、其他登录方式的处理、网络请求异常的处理等。
即时通讯 Hook 函数
请阅读 即时通讯概览 · 云引擎 Hook 来了解以下函数的相关参数和用法。
onIMMessageReceived在消息达到服务器、群组成员已解析完成、发送给收件人之前触发。例如，提前过滤掉聊天内容中的一些广告类的关键词：
onIMReceiversOffline在消息发送完成时触发、对话中某些用户却已经下线，此时可以根据发送的消息来生成离线消息推送的标题等等。例如截取所发送消息的前 6 个字符作为推送的标题：
onIMMessageSent消息发送完成之后触发，例如消息发送完后，在云引擎中打印一下日志：
onIMConversationStart创建对话，在签名校验（如果开启）之后、实际创建之前触发。例如对话创建时，在云引擎中打印一下日志：
onIMConversationStarted创建对话完成触发。例如对话创建之后，在云引擎打印一下日志：
onIMConversationAdd向对话添加成员，在签名校验（如果开启）之后、实际加入之前，包括主动加入和被其他用户加入两种情况都会触发。注意如果在创建对话时传入了其他用户的
clientId作为成员，则不会触发该 hook。例如在云引擎中打印成员加入时的日志：onIMConversationRemove从对话中踢出成员，在签名校验（如果开启）之后、实际踢出之前触发，用户自己退出对话不会触发。例如在踢出某一个成员时，在云引擎日志中打印出该成员的
clientId：onIMConversationUpdate修改对话名称、自定义属性，设置或取消对话消息提醒，在实际修改之前触发。例如在更新发生时，在云引擎日志中打印出对话的名称：
Hook 函数错误响应码
为
beforeSave这类的 hook 函数定义错误码，需要这样：客户端收到的响应为
Cloud Code validation failed. Error detail: { "code": 123, "message": "An error occurred." }。可通过 截取字符串 的方式取出错误信息，再转换成需要的对象。Hook 函数超时
Before 类 Hook 函数的超时时间为 10 秒，其他类 Hook 函数的超时时间为 3 秒。如果 Hook 函数被其他的云函数调用（比如因为保存对象而触发
beforeSave和afterSave），那么它们的超时时间会进一步被其他云函数调用的剩余时间限制。例如，如果一个
beforeSave函数是被一个已经运行了 13 秒的云函数触发，那么beforeSave函数就只剩下 2 秒的时间来运行。同时请参考 云函数超时及处理方案。在线编写云函数
很多人使用云引擎是为了在服务端提供一些个性化的方法供各终端调用，而不希望关心诸如代码托管、npm 依赖管理等问题。为此我们提供了在线维护云函数的功能。使用此功能需要注意：
在 控制台 > 云引擎 > 部署 > 在线编辑 标签页，可以：
cloud.js覆盖项目模板的同名文件，即可快速的转换为使用项目部署。云函数编辑之后需要点击 部署 才能生效。
在线编写的 SDK 版本
目前在线编辑仅支持 Node.js，提供了 4 种 SDK 版本：
从 v0 升级到 v1：
request.currentUser获取用户，而不是AV.User.current。AV.Cloud.run时需要手动传递 user 对象。从 v1 升级到 v2：
AV.Cloud.httpRequest。AV.Cloud.Error来表示错误。从 v2 升级到 v3：
AV.Object.toJSON的行为变化等）。定时任务
定时任务可以按照设定，以一定间隔自动完成指定动作，比如半夜清理过期数据，每周一向所有用户发送推送消息等等。定时任务的最小时间单位是 秒，正常情况下时间误差都可以控制在秒级别。
定时任务是普通的云函数，也会遇到 超时问题，具体请参考 超时处理方案。
一个定时任务如果在 24 小时内收到了超过 30 次的
400（Bad Request）或502（Bad Gateway）的应答，它将会被云引擎禁用，同时系统会向开发者发出相关的禁用通知邮件。在控制台的日志中，对应的错误信息为timerAction short-circuited and no fallback available。部署云引擎之后，进入 控制台 > 云引擎 > 定时任务，点击 创建定时任务，然后设定执行的函数名称、执行环境等等。例如定义一个打印循环打印日志的任务
logTimer：定时任务分为两类：
以 Cron 表达式为例，比如每周一早上 8 点打印日志（运行之前定义的
logTimer函数），创建定时任务的时候，选择 Cron 表达式 并填入0 0 8 ? * MON。Cron 表达式的语法可以参考 云队列使用指南的 Cron 表达式一节。
点击「非必填」会展开更多选项：
定时任务创建后，会显示「最近一次执行时间」和「下次执行时间」。 「最近一次执行时间」除了显示时间外，还会显示执行结果，点击「查看详情」还可以查看细节：
status任务的状态，包括success（成功）、failed（失败）uniqueId任务的唯一 IDfinishedAt执行完成的精确时间（仅限成功任务）statusCode云函数响应的 HTTP 状态码（仅限成功任务）result来自云函数的响应（仅限成功任务）error错误提示（仅限失败任务）retryAt下次重试时间（仅限失败任务）具体的执行日志可以在控制台 > 云引擎 > 日志 查看。 例如：
如果希望暂停定时任务（比如遇到报错需要排查），可以点击状态栏的「暂停」按钮。 相应地，点击「启用」按钮可以重新启用暂停的任务。 点击操作栏的「编辑」、「删除」按钮则可以修改、删除定时任务。
Master Key 和超级权限
因为云引擎运行在可信的服务器端环境中，所以你可以全局开启超级权限（Master Key），这样云端会跳过包括 ACL 和 Class 权限在内的检查，让你自由地操作所有云存储中的数据，当然这种方式也允许调用一些仅供 Master Key 使用的 API。开启 Master Key 的方法如下：
如果没有添加这些代码，默认是没有超级权限的，这意味着在云引擎中你也不能修改被 ACL 保护的数据，你需要在进行操作时手动指定
sessionToken，让操作以这个用户的权限来执行：或者你也可单独对某一个操作使用 Master Key，跳过权限检查：
当然你也可以在启用了超级权限的情况下使用
useMasterKey: false来对单个操作关掉超级权限。那么究竟是否应该使用超级权限呢，我们的建议如下：
sessionToken传入数据修改的相关操作（如save）。关于云引擎上的权限问题，还可以参考 ACL 权限管理开发指南 和 在云引擎中使用 ACL。