编辑文档更新于 2020-07-24

云引擎 REST API 使用指南

LeanCloud 云端提供的统一的访问云函数的 REST API 接口，所有的客户端 SDK 也都是封装了这个接口从而实现对云函数的调用。

我们推荐使用 Postman 来调试 REST API，我们的社区中有一篇使用 Postman 调试 REST API 教程。

Base URL

文档中云函数的 Base URL 为绑定的 API 自定义域名，可以在「控制台 > 设置 > 应用 Keys > 服务器地址」查看。

如果暂时没有绑定域名，华北、华东节点可以使用临时的测试域名，具体域名见「控制台 > 设置 > 应用 Keys > 服务器地址」。该域名仅供测试和原型开发阶段使用，不保证可用性，请在正式发布前为应用绑定 API 自定义域名。

LeanCloud 国际版不要求绑定自定义域名。除了使用自定义域名外，也可以使用如下共享域名：

appid前八位.engine.lncldglobal.com

预备环境和生产环境

在客户端通过 REST API 调用云函数时，可以设置 HTTP 头 X-LC-Prod 来区分调用的环境。

X-LC-Prod: 0 表示调用预备环境
X-LC-Prod: 1 表示调用生产环境

通过 SDK 调用云函数时，SDK 会根据当前环境设置 X-LC-Prod HTTP 头，详见云函数开发指南中关于预备环境和生产环境的说明。

云函数

通过 POST /functions/:name 可以调用云函数，参数和结果都是 JSON 格式。例如，我们传入电影的名字来获取电影的目前的评分：

curl -X POST -H "Content-Type: application/json; charset=utf-8" \
       -H "X-LC-Id: {{appid}}" \
       -H "X-LC-Key: {{appkey}}" \
       -d '{"movie":"夏洛特烦恼"}' \
https://API_BASE_URL/1.1/functions/averageStars

响应：

{
  "result": {
    "movie": "夏洛特烦恼",
    "stars": "2.5"
  }
}

如果调用的云函数需要关联用户，那么可以通过 X-LC-Session 传入相应的 sessionToken：

curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "X-LC-Session: qmdj8pdidnmyzp0c7yqil91oc" \
  -H "Content-Type: application/json" \
  -d '{}' \
  https://API_BASE_URL/1.1/functions/hello

有些时候我们希望使用 AVObject 作为云函数的参数，或者希望以 AVObject 为云函数的返回值，这时我们可以使用 POST /1.1/call/:name 这个 RPC 调用的 API，云函数 SDK 会将参数解释为一个 AVObject，同时在返回 AVObject 时提供必要的元信息：

curl -X POST \
  -H "X-LC-Id: {{appid}}" \
  -H "X-LC-Key: {{appkey}}" \
  -H "Content-Type: application/json" \
  -d '{"__type": "Object", "className": "Post", "pubUser": "LeanCloud官方客服"}' \
  https://API_BASE_URL/1.1/call/addPost

响应：

{
  "result": {
    "__type": "Object",
    "className": "Post",
    "pubUser": "LeanCloud官方客服"
  }
}

RPC 调用时，不仅可以返回单个 AVObject，还可以返回包含 AVObject 的数据结构。例如，假设有一个云函数返回一个数组，其中包含一个数字和一个 Todo 对象，那么 RPC 调用的结果为：

{
  "result": [
    1,
    {
      "title": "工程师周会",
      "createdAt": {
        "__type": "Date",
        "iso": "2019-04-28T08:34:12.932Z"
      },
      "updatedAt": {
        "__type": "Date",
        "iso": "2019-04-28T08:34:12.932Z"
      },
      "objectId": "5cc5658443e78cb53fe7b731",
      "__type": "Object",
      "className": "Todo"
    }
  ]
}

在通过 SDK 进行 RPC 调用时，SDK 会据此自动反序列化。

如果云函数超时，客户端会收到 HTTP status code 为 503、524、141 等的响应。

你还可以阅读以下云函数开发指南来获取更多的信息。