详解nodejs 开发企业微信第三方应用入门教程

前言

本教程旨在介绍如何使用Node.js开发企业微信第三方应用，相关内容适用于搭建企业内部应用或者SaaS平台。通过本教程，您将学习到如下知识：

• 掌握企业微信第三方应用的基本概念和开发流程
• 熟悉OAuth2.0协议并实现第三方应用的授权流程
• 学会使用企业微信API接口，开发出功能丰富的企业微信应用

准备工作

在开始开发之前，我们需要完成如下准备工作：

1. 注册企业微信第三方应用

在准备工作中，首先需要注册企业微信第三方应用，并申请相关的API接口权限。在申请API接口权限完成之后，您可以拥有以下接口权限：

• 客户联系/客户群管理/消息发送/素材管理/企业信息管理
• 应用管理/除可信域名配置外的相应应用接口（多个应用间共享）

2. 确认授权流程

企业微信第三方应用的授权流程分为三个阶段：授权发起、授权回调和企业使用。在授权发起阶段，您需要完成如下几个步骤：

1. 引导企业管理员进入企业微信授权页面
2. 获取到企业管理员的授权信息
3. 将授权码传递给第三方应用

至此，授权发起阶段已经完成。在授权回调阶段，您需要完成如下几个步骤：

1. 获取企业管理员的永久授权码
2. 获取企业的access_token
3. 根据access_token，访问其他企业应用API接口

在企业使用阶段，则需要您完成以下几个步骤：

1. 创建企业应用菜单
2. 获取企业内部用户基本信息
3. 发送企业消息/客户消息

3. 安装依赖组件

在开始编写Node.js代码前，您还需要安装如下依赖组件：

• express
• request
• querystring
• xml2js

您可以使用如下命令安装这些依赖组件：

npm install express request querystring xml2js --save

安装完成后，您就可以开始编写Node.js代码了。

实现授权发起流程

1. 获取跳转链接

在这个示例中，我们使用Node.js + Express完成企业微信第三方应用的授权发起流程。在实现授权发起流程之前，您需要配置好企业微信授权页面的跳转链接。您可以通过调用以下API接口，获取到跳转链接：

var crypto = require('crypto');

//构造auth2Url
var auth2Url = 'https://open.weixin.qq.com/connect/oauth2/authorize?appid=' + YOUR_CORP_ID +
 '&redirect_uri=' + encodeURIComponent(YOUR_APP_AUTHORIZE_URL) +
 '&response_type=code&scope=snsapi_privateinfo#wechat_redirect';

//对auth2Url进行加密，使用SHA1算法加密AccessToken
var now = Date.now();
var nonce = Math.random().toString(36).substr(2);
var url = auth2Url.replace(/&|\?/g, '');
var signature = crypto.createHash('sha1').update(url + '&' + now + '&' + nonce + '&'+ YOUR_APP_TOKEN).digest("hex");

//将加密后的AccessToken、时间戳、nonce、跳转链接拼装在一起，返回给前端
var auth2UrlParams = "?signature=" + signature + "&timestamp=" + now + "&nonce=" + nonce + "&auth2Url=" + encodeURIComponent(auth2Url);
var finalAuth2Url = 'https://open.weixin.qq.com/connect/oauth2/authorize' + auth2UrlParams;

2. 发送带有跳转链接的授权请求

授权发起完成之后，您需要将带有跳转链接的授权请求发送给企业管理员。企业管理员在点击此链接后，将会被引导至企业微信授权页面。

app.get('/auth', function (req, res) {
  var redirectUrl = req.query.redirect_uri;
  var userId = req.query.userid;

  //将redirectUri和userId存储在缓存中
  cache.set(userId, redirectUrl);

  //根据企业id获取跳转链接
  getAuth2Url(req.query.corpid,function (authUrl) {
    //发送带有跳转链接的授权请求
    res.redirect(authUrl);
  })
})

在以上代码中，我们使用了一个cache组件，用于将redirectUri和userId存储在缓存中。在企业管理员授权完成后，我们还需要使用userId和缓存中存储的redirectUri信息，生成授权页面的回调链接。

实现授权回调流程

1. 获取企业管理员授权信息

企业管理员授权完成后，企业微信会将授权信息通过GET方式传递给您的应用。在授权回调流程中，您需要根据授权的结果，获取到企业管理员的授权信息。在本示例中，我们使用如下方式获取企业管理员的授权信息:

app.get('/auth/callback', function (req, res) {
  var code = req.query.code;
  var state = req.query.state;

  //根据授权码获取access_token
  getAccessToken(code,function (err, accessToken) {
    //根据access_token和企业管理员信息，获取企业管理员的授权信息
    getUserInfo(accessToken, state, function (err, user) {

      //从缓存中获取redirect_url和userId信息，并删除缓存中的数据
      var redirect_url = cache.get(user.UserId);
      cache.remove(user.UserId);

      //跳转到应用回调页面
      res.redirect(redirect_url + '?auth_code=' + user.AuthCode);
    });
  });
})

在以上代码中，我们使用了一个getAccessToken和getUserInfo函数，用于获取access_token和企业管理员的授权信息。

2. 获取企业访问令牌

在获取企业管理员授权信息之后，我们还需要获取企业访问令牌。一个企业访问令牌（access_token），代表了一个企业的身份，您需要使用企业访问令牌才能访问企业微信API接口。在本示例中，我们使用如下方式获取企业访问令牌：

function getAccessToken(code, callback) {
  //通过授权码获取access_token
  request({
    url: 'https://qyapi.weixin.qq.com/cgi-bin/gettoken',
    qs: {
      corpid: YOUR_CORP_ID,
      corpsecret: YOUR_APP_SECRET
    },
    method: 'GET',
    json: true
  }, function (err, res, data) {
    if (!err && data.access_token) {
      callback(null, data.access_token);
    } else {
      console.log("Get access_token error:", err);
      callback(err);
    }
  });
}

在以上代码中，我们使用corpid和corpsecret信息，发送GET请求获取企业访问令牌，如果获取成功，则将令牌信息返回给回调函数。如果获取失败，则把错误信息传递给回调函数。

示例1：获取企业内部用户基本信息

企业微信API提供了获取企业内部用户基本信息的方法。在本示例中，我们通过GET方法，获取特定用户的用户信息。以下是获取用户基本信息的代码示例：

function getUser(accessToken, userId, callback) {
  var url = 'https://qyapi.weixin.qq.com/cgi-bin/user/get?access_token=' + accessToken + '&userid=' + userId;
  request.get(url, function (err, res, body) {
    if (err) {
      callback(err);
    } else {
      var user = JSON.parse(body);
      callback(null, user);
    }
  });
}

在以上代码中，我们使用JSON.parse方法，将从API接口返回的JSON格式的用户信息转换为JavaScript对象。在处理用户信息时，您可以自行决定需要缓存哪些用户信息和缓存时间等信息。

示例2：发送企业消息

企业微信API提供了发送企业消息的方法。在本示例中，我们使用企业微信API接口，向特定用户发送一条企业消息。以下是发送企业消息的代码示例：

function sendText(accessToken, userId, text, callback) {
  var url = 'https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=' + accessToken;
  var formData = {
    touser: userId,
    msgtype: "text",
    agentid: AGENT_ID,
    text: {
      content: text
    },
    safe: 0
  };
  request.post({url: url, form: formData}, function (err, res, body) {
    if (err) {
      callback(err);
    } else {
      var result = JSON.parse(body);
      callback(null, result);
    }
  });
}

在以上代码中，我们使用了POST方法，向企业微信API发送请求。formData参数中，touser表示接收消息的用户id，msgtype表示消息类型，content表示消息内容。

结语

本文介绍了企业微信第三方应用的开发过程，并提供了2个示例，分别介绍了如何使用企业微信API获取企业内部用户基本信息和发送企业消息。在实际开发中，您还可以使用企业微信API，完成客户联系、客户群管理、消息发送、素材管理、应用管理等功能。