基本配置-接口对接

介绍

钉钉H5微应用接口对接，主要涉及以下几个方面：

模块Config
工作通知
网页登录
网页前端JSSDK
钉钉网页布局
钉钉API调用

1. 模块Config

CabloyJS提供了两种方式来配置Config参数：

后台管理页面：页面路径为系统应用/基础管理/认证管理
项目配置：直接在项目配置文件中覆盖模块Config中的参数，从而配置与钉钉有关的信息

关于如何覆盖模块Config，请参见：Config

a-dingtalk/backend/src/config/config.js

1  // account.dingtalk
2  config.account.dingtalk = {
3    client: 'dingtalk',
4    // scenes
5    scenes: {
6      selfBuilt: {
7        title: 'AuthSelfBuiltApp',
8        agentId: '',
9        appKey: '',
10        appSecret: '',
11        message: {
12          token: appInfo.name,
13          encodingAESKey: '',
14        },
15        jssdk: {
16          type: 0,
17          jsApiList,
18        },
19      },
20    },
21  };

名称	说明
scenes	配置所有钉钉应用的参数，包括：钉钉内置应用、第三方应用，以及自建应用。如需访问其他应用提供的API接口，直接在`scenes`添加新的配置即可
scenes.selfBuilt	自建应用（H5微应用）

2. 工作通知

模块a-dingtalk已经对工作通知的推送机制进行了封装。比如，要向某个用户发送工作通知的消息，可以这样操作：

src/suite-vendor/test-party/modules/test-dingtalk/backend/src/service/test.js

1async sendAppMessage({ message, user }) {
2  const msg = {
3    msgtype: 'text',
4    text: {
5      content: message.text,
6    },
7  };
8  const content = {
9    userIds: [ user.id ],
10    data: { msg },
11  };
12  await this.ctx.bean.io.pushDirect({
13    content,
14    channel: { module: 'a-dingtalk', name: 'app' },
15  });
16}

名称	说明
content.userIds	推送的目标用户
content.msg	推送的消息内容，参考发送工作通知
channel	内置的推送通道

3. 网页登录

模块a-dingtalk自动判断，如果当前网页处于钉钉app中，会自动进行免登处理，然后自动进行用户认证

4. 网页前端JSSDK

模块a-dingtalk提供了便捷的组件，可以自动注入钉钉JSSDK，并且自动进行config配置

测试模块test-dingtalk演示了如何调用钉钉的二维码扫描操作：

src/suite-vendor/test-party/modules/test-dingtalk/front/src/pages/test/index.vue

1  created() {
2    const action = {
3      actionModule: 'a-dingtalk',
4      actionComponent: 'jssdk',
5      name: 'config',
6    };
7    this.$meta.util.performAction({ ctx: this, action }).then(res => {
8      this.dd = res && res.dd;
9    }).catch(e => {
10      this.$view.toast.show({ text: e.message });
11    });
12  },
13  methods: {
14    onPerformScanQRCode() {
15      this.dd.biz.util.scan({
16        type: 'all',
17        onSuccess: res => {
18          this.$view.toast.show({ text: res.text });
19        },
20        onFail: err => {
21          this.$view.toast.show({ text: err.message });
22        },
23      });
24    },
25  }

先通过this.$meta.util.performAction调用模块a-dingtalk提供的组件，返回dd对象
调用dd对象执行扫描二维码的钉钉接口

5. 钉钉网页布局

CabloyJS可以创建App应用，一个App应用是菜单页面+主页+用户页面组合。我么可以专门针对钉钉场景定义一个专属的App应用

测试模块test-dingtalk演示了如何定制钉钉场景下的App应用：

App应用配置：src/suite-vendor/test-party/modules/test-dingtalk/backend/src/config/static/app/appTest.js
App菜单页面配置：src/suite-vendor/test-party/modules/test-dingtalk/backend/src/config/static/layout/layoutAppMenuTest.js

6. 钉钉API调用

模块a-dingtalk提供了全局Bean组件dingtalk，用于调用所有钉钉API，格式如下：

ctx.bean.dingtalk.app.{providerScene}

名称	说明
providerScene	场景名称，比如`selfBuilt`(自建应用)

钉钉API基于ali-sdk/node-dingtalk。为了便于更灵活的添加新API，CabloyJS对主仓库发起了一个新分支，详细的API清单请参见：node-dingtalk

下面以JSSDK Config为例：

src/module-system/a-dingtalk/backend/src/service/jssdk.js

1async jsconfig({ url }) {
2  ...
3  // jsconfig
4  const res = await this.ctx.bean.dingtalk.app.selfBuilt.client.getJSApiConfig(url);
5}

7. 如何判断是否在`钉钉`中

由于CabloyJS后端架构的普适性，我们有时候需要判断当前是否在钉钉中，从而做出相应的处理

7.1 通过中间件判断

可以通过中间件inDingtalk来判断该api接口是否被钉钉调用，如果不是则自动阻止后续逻辑的执行

src/suite-vendor/test-party/modules/test-dingtalk/backend/src/routes.js

1  { method: 'post', path: 'test/getMemberId', controller: test, middlewares: 'inDingtalk',
2      meta: {
3        inDingtalk: {
4          providerName: 'dingtalk',
5          providerScene: null,
6        },
7      },
8    },

名称	说明
meta.inDingtalk	中间件`inDingtalk`的参数
providerName	认证提供者名称，如果指定`dingtalk`，表示该api只能被`自建H5微应用`调用
providerScene	如果认证提供者支持多个场景，这里可以指定场景名

7.2 通过代码判断

可以直接通过代码进行判断

1ctx.bean.dingtalk.util.in({ providerName, providerScene })

介绍