云引擎 REST API 使用指南

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

我们推荐使用 Postman 来调试 REST API。

Base URL

REST API 请求的 Base URL 可以在云服务控制台 > 设置 > 应用凭证 > 服务器地址查看。

概览

URL	HTTP	功能
/1.1/functions/<functionName>	POST	调用云函数
/1.1/call/<functionName>	POST	调用云函数，支持 LCObject 作为参数和结果

预备环境和生产环境

在客户端通过 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

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

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": "官方客服"
  }
}

RPC 调用时，不仅可以返回单个 LCObject，还可以返回包含 LCObject 的数据结构。 例如，假设有一个云函数返回一个数组，其中包含一个数字和一个 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 等的响应。

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