Skip to content

Latest commit

 

History

History
254 lines (171 loc) · 9.46 KB

API.md

File metadata and controls

254 lines (171 loc) · 9.46 KB
Raw

LeanEngine Node SDK

在 express 应用中使用：

var app = require('express')();
var AV = require('leanengine');

AV.init({
  appId: process.env.LEANCLOUD_APP_ID,
  appKey: process.env.LEANCLOUD_APP_KEY,
  masterKey: process.env.LEANCLOUD_APP_MASTER_KEY
});

app.use(AV.express());

app.listen(process.env.LEANCLOUD_APP_PORT);

AV.express

AV.express(options?: object)

初始化一个 LeanEngine 中间件，可被挂载到 express 应用上。

AV.koa

AV.koa(options?: object)

初始化一个 LeanEngine 中间件，可被挂载到 koa 应用上。

AV.Object

  • AV.Object#disableBeforeHook()
  • AV.Object#disableAfterHook()

LeanEngine SDK 为 AVObject 提供了这两个方法来防止死循环，当在一个 AVObject 实例上调用了这个方法，就不会触发对应的 Hook（需要 masterKey 权限）。详见文档：云函数开发指南：防止死循环调用。

AV.Cloud

AV.Cloud.define

AV.Cloud.define(name: string, func: function)
AV.Cloud.define(name: string, options: object, func: function)

定义云函数有两种签名，其中 options 是一个可选的参数，func 的签名：function(request: Request, response: Response)。

options 的属性包括：

  • fetchUser: boolean：是否自动抓取客户端的用户信息，默认为 true，若设置为 false 则 request 上将不会有 user 属性。

Request 上的属性包括：

  • params: object：客户端发送的参数，当使用 rpc 调用时，也可能是 AV.Object.
  • currentUser?: AV.User：客户端所关联的用户（根据客户端发送的 LC-Session 头）。
  • user?: AV.User：同 currentUser.
  • meta: {remoteAddress}：meta.remoteAddress 是客户端的 IP.
  • sessionToken?: string：客户端发来的 sessionToken（X-LC-Session 头）。

Response 上的属性包括：

  • success: function(result?)：向客户端发送结果，可以是包括 AV.Object 在内的各种数据类型或数组，客户端解析方式见各 SDK 文档。
  • error: function(err?: string)：向客户端返回一个错误。

AV.Cloud.run

运行已定义的云函数，与 JavaScript SDK 中会发起 HTTP 请求不同，在云引擎中默认变成直接调用指定的函数。

AV.Cloud.run(name: string, data: object, options?: object): Promise

options 的属性包括：

  • user?: AV.User：以特定的用户运行云函数（建议在 remote: false 时使用）。
  • sessionToken?: string：以特定的 sessionToken 调用云函数（建议在 remote: true 时使用）。
  • remote?: boolean：通过网络请求来调用云函数，默认 false.
  • req?: Express 的 Request 对象，以便被调用的云函数得到 remoteAddress 等属性。

更多有关云函数的内容请参考文档 云函数开发指南：云函数。

AV.Cloud.rpc

兼容 JavaScript SDK 的同名函数，是 AV.Cloud.run 的一个别名。

定义 Class Hook

  • AV.Cloud.beforeSave
  • AV.Cloud.afterSave
  • AV.Cloud.beforeUpdate
  • AV.Cloud.afterUpdate
  • AV.Cloud.beforeDelete
  • AV.Cloud.afterDelete

这些函数的签名：function(className: string, func: function)。

before 类 Hook 的 func 签名：function(request: Request, response: Response)，before 类 Hook 需要在执行完成后调用 response.success 或 response.error 接受或拒绝这次操作。

after 类 Hook 的 func 签名：function(request: Request)。

Request 上的属性包括：

  • object: AV.Object：被操作的对象。
  • currentUser?: AV.User：发起操作的用户。
  • user?: AV.User：同 currentUser.

Response 上的属性包括：

  • success: function()：允许这个操作，请在 15 秒内调用 success, 否则会认为操作被拒绝。
  • error: function(err: string)：向客户端返回一个错误并拒绝这个操作。

LeanEngine 中间件会为这些 Hook 函数检查「Hook 签名」，确保调用者的确是 LeanCloud 或本地调试时的命令行工具。

更多有关 Hook 函数的内容请参考文档 云函数开发指南：Hook 函数。

登录和认证 Hook

  • AV.Cloud.onVerified
  • AV.Cloud.onLogin

这两个函数的签名：function(func: function)，func 签名：function(request: Request, response: Response)，Hook 需要在执行完成后调用 response.success 或 response.error 接受或拒绝这次操作。

Request 上的属性包括：

  • currentUser: AV.User：被操作的用户。
  • user: AV.User：同 currentUser.

Response 上的属性包括：

  • success: function()：允许这个操作，请在 15 秒内调用 success, 否则会认为操作被拒绝。
  • error: function(err: string)：向客户端返回一个错误并拒绝这个操作。

更多有关 Hook 函数的内容请参考文档 云函数开发指南：Hook 函数。

实时通信 Hook 函数

包括：

  • _messageReceived
  • _receiversOffline
  • _messageSent
  • _conversationStart
  • _conversationAdd
  • _conversationRemove
  • _conversationUpdate

LeanEngine 中间件会为这些 Hook 函数检查「Hook 签名」，确保调用者的确是 LeanCloud 或本地调试时的命令行工具。

这些 Hook 需要用 AV.Cloud.define 来定义，详见文档 实时通信概览：云引擎 Hook

AV.Cloud.httpRequest

注意：该 API 已不再维护且可能在之后的版本中去除，请使用 request 发起 HTTP 请求。

AV.Cloud.httpRequest(options: object);

options 的属性包括：

  • url：被请求的 Url, 例如 https://api.leancloud.cn/1.1/ping。
  • success: function(response: Response)：成功回调，接受一个 HTTP 响应作为参数。
  • error: function(response: Response)：失败回调，接受一个 HTTP 响应作为参数。
  • method: string：HTTP 方法，默认为 GET。
  • params：Query String，可以是对象 {q : 'Sean Plott'} 也可以是字符串 q=Sean Plott。
  • headers: object：HTTP 头，例如 {'Content-Type': 'application/json'}。
  • body: object：HTTP 请求正文，默认使用 urlencode 编码，如果指定了 Content-Type 为 application/json 则发送 JSON 格式的正文；不适用于 GET 或 HEAD 请求。
  • timeout: number：超时时间，单位秒，默认 10000。

Response 的属性包括：

  • status: number：HTTP 响应状态码。
  • headers: object：HTTP 响应头。
  • text: string：HTTP 响应正文。
  • buffer: Buffer：HTTP 响应正文。
  • data 解析后的 HTTP 响应正文，例如对于 Content-Type 为 application/json 时，会将响应正文解析为一个对象。

示例：

AV.Cloud.httpRequest({
  method: 'POST',
  url: 'http://www.example.com/create_post',
  body: {
    title: 'Vote for Pedro',
    body: 'If you vote for Pedro, your wildest dreams will come true'
  },
  success: function(httpResponse) {
    console.log(httpResponse.text);
  },
  error: function(httpResponse) {
    console.error('Request failed with response code ' + httpResponse.status);
  }
});

Middlewares

cookie-session

该中间件提供了在 Express 或 Koa 中维护用户状态的能力，在 Express 中：

app.use(AV.Cloud.CookieSession({secret: 'my secret', maxAge: 3600000, fetchUser: true}));

在 Koa 中（添加 framework: 'koa' 参数）：

app.use(AV.Cloud.CookieSession({framework: 'koa', secret: 'my secret', maxAge: 3600000, fetchUser: true}));

参数包括：

  • koa?: boolean：返回一个 koa（而不是 express）中间件。
  • secret: string：对 Cookie 进行签名的密钥，请选用一个随机字符串。
  • name?: string：Cookie 名称，默认为 avos.sess。
  • maxAge?: number：Cookie 过期时间。
  • fetchUser?: boolean：是否自动查询用户信息，默认为 false，即不自动查询，这种情况下只能访问用户的 id 和 sessionToken.
  • httpOnly?: boolean: 不允许客户端读写该 Cookie，默认 false.

express 的 Request（或 koa 的 ctx.request）上会有这些属性可用：

  • currentUser?: AV.User：和当前客户端关联的用户信息（根据 Cookie），如未开启 cookie-session 的 fetchUser 选项则只可以访问 id 和 sessionToken.
  • sessionToken?: string：和当前客户端关联的 sessionToken（根据 Cookie）。

express 的 Response（或 koa 的 ctx.response）上会有这些属性可用：

  • saveCurrentUser(user: AV.User)：将当前客户端与特定用户关联（会写入 Cookie）。
  • clearCurrentUser()：清除当前客户端关联的用户（删除 Cookie）。

更多有关在 express 维护用户状态的技巧见文档：网站托管开发指南：处理用户登录和登出。

https-redirect

该中间件会自动将 HTTP 请求重定向到 HTTPS 上，在 Express 中：

app.enable('trust proxy');
app.use(AV.Cloud.HttpsRedirect());

Koa 中（添加 framework: 'koa' 参数）：

app.proxy = true;
app.use(AV.Cloud.HttpsRedirect({framework: 'koa'}));