# 云调用说明

> 版本要求：`wx-server-sdk` >= `0.4.0`、开发者工具 >= `1.02.1904090`（[RC 版下载](/miniprogram/dev/server/API/mp-access-token/api_getstableaccesstoken.md)）

云调用是云开发提供的基于云函数使用小程序开放接口的能力。

云调用需要在云函数中通过 `wx-server-sdk` 使用。在云函数中使用云调用调用服务端接口无需换取 `access_token`，只要是在从小程序端触发的云函数中发起的云调用都经过微信自动鉴权，可以在登记权限后直接调用如发送模板消息等开放接口。使用方式如下：

## 1、判断是否支持云调用

在接口文档中会标明是否支持云调用，支持的情况下则会在「云调用」内容中标明调用函数名。

> 部分接口没有更新显示是否支持云调用，有疑问可在微信开放社区咨询。

## 2、声明调用接口

需要**配置云调用权限**，每个云函数需要声明其会使用到的接口，否则无法调用。声明的方法是在云函数目录下的 `config.json`（如无，需新建）配置文件的 `permissions.openapi` 字段中增加要调用的接口名，`permissions.openapi` 是个字符串数组字段，值必须为所需调用的服务端接口名称。在每次使用微信开发者工具上传云函数时均会根据配置更新权限，该配置有 10 分钟的缓存，如果更新后提示没有权限（`-604101`），稍等 10 分钟后再试。以下是一个示例的声明了使用发送模板消息接口的配置文件：

```json
{
  "permissions": {
    "openapi": [
      "subscribeMessage.send"
    ]
  }
}
```

## 3、使用云调用

首先云函数中需要使用版本号至少 `0.4.0` 的 `wx-server-sdk`，建议 `wx-server-sdk` 始终保持最新，保证云函数目录下的 `package.json` 的 `wx-server-sdk` 字段为 `latest`，如本地安装依赖，请执行 `npm install --save wx-server-sdk@latest`。

接下来，可在云函数中使用云调用 API 了。云调用 API 均挂载在 `wx-server-sdk` 模块的 `openapi` 对象下，各个开放接口类别在 `openapi` 对象下设二级命名空间对象（如模板消息接口的方法均在 `openapi.subscribeMessage` 下），该对象下挂载该类别下的所有开放方法（比如模板消息的发送接口是 `openapi.subscribeMessage.send`）。各接口从属的类别名称和方法名称可以通过接口名称查看，接口名称均以 `<类别>.<方法>` 命名，如发送模板消息的接口名称是 `subscribeMessage.send`。下面是一个给自己发送模板消息的示例：

> 如需可直接运行的示例，请在 IDE 中创建一个云开发快速启动模板的项目，其中有包含发送模板消息的云调用的示例。

```js
const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
  try {
    const result = await cloud.openapi.subscribeMessage.send({
        "touser": 'OPENID',
        "page": 'index',
        "lang": 'zh_CN',
        "data": {
          "number01": {
            "value": '339208499'
          },
          "date01": {
            "value": '2015年01月05日'
          },
          "site01": {
            "value": 'TIT创意园'
          },
          "site02": {
            "value": '广州市新港中路397号'
          }
        },
        "templateId": 'TEMPLATE_ID',
        "miniprogramState": 'developer'
      })
    return result
  } catch (err) {
    return err
  }
}
```

## 4、注意事项

服务端调用有 10 万/分钟的频率限制。

## 5、环境共享下的云调用

环境共享时，可以指定云调用的目标小程序。指定后，将以该小程序的身份发起云调用。

```js
// 指定为来源方的 AppID 调用
cloud.openapi({ appid: wxContent.FROM_APPID }).subscribeMessage.send({
  // ...
})
```
