dingtalk_enterprise
v1.9.11
Published
nodejs钉钉企业号API
Downloads
7
Readme
dingtalk enterprise
钉钉企业号API,自带cache,并自带ISV套件操纵接口。 ##安装
npm install dingtalk_enterprise
##示例 ####config:
var DD_enterprise = require('dingtalk_enterprise');
var config = {
corpid : 'xxxxxxxxxxxxxxxx', //ISV套件控制的话,可不填
secret : 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxx', //ISV套件控制的话,可不填
getToken : function(callback){
//从数据库中取出Token,返回的data样式为:{value: 'xxxxxxx', expires:1452735301543}
fs.readFile(this.suiteid + 'token.txt',function(err, data){
if(err){
return callback(err);
}
data = JSON.parse(data.toString());
callback(null, data);
});
},
saveToken : function(data, callback){
//存储Token到数据库中,data样式为:{value: 'xxxxxxx', expires:1452735301543//过期时间}
fs.writeFile(this.suiteid + 'token.txt',JSON.stringify(data), callback);
},
getJsApiTicket : function(callback){
//从数据库中取出JsApiTicket,返回的data样式为:{value: 'xxxxxxx', expires:1452735301543}
fs.readFile(this.suiteid + 'JsApiTicket.txt',function(err, data){
if(err){
return callback(err);
}
data = JSON.parse(data.toString());
callback(null, data);
});
},
saveJsApiTicket : function(data, callback){
//存储JsApiTicket到数据库中,data样式为:{value: 'xxxxxxx', expires:1452735301543//过期时间}
fs.writeFile(this.suiteid + 'JsApiTicket.txt',JSON.stringify(data), callback);
},
token_expires_in : 1000 * 60 * 60 * 2 - 10000, //token过期时间,可不填。 默认1小时59分50秒(钉钉规定2小时),防止网络延迟.
};
###创建企业号API:
var api = new DD_enterprise(config);
###用ISV套件操作企业号?OK 只需要两个参数:
//newSuiteApi: 一个dingtalk_suite实例。
var suiteCtrlE = new DD_enterprise.CtrlBySuite(newSuiteApi, config);
//只需传入corpid, 和企业号的永久授权码就能控制企业号。
var api = suiteCtrlE.ctrl(corpid, permanent_code);
如果你获取永久授权码的同时,获得了token_cache,可以加上第三个参数,这样可以省一次数据库查询。
//token为Object格式 key为: value , expires
var api = suiteCtrlE.ctrl(corpid, permanent_code, token_cache);
如果你获取永久授权码的同时,获得了token_cache和jsapi_ticket_cache,可以加上第四个参数,这样可以省两次数据库查询。
//token和jsapi_ticket_cache为Object格式 key为: value , expires
var api = suiteCtrlE.ctrl(corpid, permanent_code, token_cache, jsapi_ticket_cache);
注:ISV套件主动调用api见: dingtalk_suite
##代理中间件
api.agentMiddleware
完全的代理模式,此方法可调用钉钉官方企业号文档的所有接口,而不用管token。
//例:
//如果是express,什么也不用参数。
app.use('/agent', api.agentMiddleware());
//不是express 怎么办?
app.use('/agent', api.agentMiddleware(
function(req, res){ //该方法必须是同步的。
return {
method: req.method, //钉钉的api方法。 必须
url: req.url, //钉钉的api的路径。 必须
errhandler: function(err){ }//错误处理 必须
}}));
客户端仿问ajax示例:
//获取部门列表
//钉钉文档:https://open-doc.dingtalk.com/docs/doc.htm?spm=a219a.7629140.0.0.9aG2FM&treeId=172&articleId=104979&docType=1 获取部门列表
var api = '/department/list'; //跟钉钉的一样。
$.get('/agent' + api, function(data){
console.log('data', data);
});
上传文件示例:
<form action="/agent/media/upload" method="post" enctype="multipart/form-data">
<input name="type" value="image">
<input name="media" type="file">
<input type="submit" value="提交">
</form>
###注意 agentMiddleware为新添加方法,是纯代理模式,它不再判断errcode了。比如说钉钉返回errcode = 1, 老方法会包含在error,而agentMiddleware则不会。
##接口方法 ###主要方法 ####api.getLatestToken(callback); 获得最新token。
//例:
api.getLatestToken(function(err, token){
if(err){
return console.error(err);
}
//token格式为:{value: 'xxxxxxx', expires:1452735301543//过期时间}
console.log('token',token);
});
####api.getUrlSign(url, callback); 生成url授权参数,用于前端jsConfig.
//例:
api.getUrlSign('http://www.test.com/path', function(err, result){
if(err){
return console.error('error', err);
}
/*
result格式为:{
signature: '23sadfasdfasdf',
timeStamp:'24234234234234',
nonceStr:'asfdasdfasdfasfdx'
}
*/
console.log('result',result);
});
#以下方法不推荐使用,只用上面的agentMiddleware足够了。将可能在下版废弃。 ####api.get(ddApiPath, opts, callback); 代理get方法。使有此方法可调用钉钉官方企业号文档的get接口,而不用管token。
//例:
//获取部门列表
//钉钉文档:http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.p5bAUd#获取部门列表
api.get('/department/list', function(err, result){
if(err){
return console.error('err', err);
}
console.log('result', result);
});
//获取部门详情
//钉钉文档:http://ddtalk.github.io/dingTalkDoc/?spm=a3140.7785475.0.0.p5bAUd#获取部门详情
api.get('/department/get', {id:2}, function(err, result){
if(err){
return console.error('err', err);
}
console.log('result', result);
});
####api.post(ddApiPath, opts, callback); 代理post方法。使有此方法可调用钉钉官方企业号文档的post接口,而不用管token。
用法同api.get。
###其它封装的一些方法。 ####部门
//获得部门列表
api.getDepartments(callback);
//获得部门详情
api.getDepartmentDetail(id, callback);
//创建部门
api.createDepartment(name, opts, callback);
//例
//名字,父id
api.createDepartment('部门一', 1, callback);
//名字,详细配置
api.createDepartment('部门一', {parentid: 1, order:1}, callback);
//更新部门
api.updateDepartment(id, opts, callback);
//删除部门
api.deleteDepartment(id, callback);
####微应用
api.createMicroApp(data, callback);
####消息
api.sendToConversation(callback);
api.send(agentid, to, msg, callback);
####用户
//获取部门用户
api.getDepartmentUsers(id,callback);
//获取部门用户详细
api.getDepartmentUsersDetail(id,callback);
//获取用户信息
api.getUser(id, callback);
//通过code获取用户一些信息(App登录用)。
api.getUserInfoByCode(code, callback);
具体详情请参照阿里钉钉文档
##更多钉钉相关 ISV套件主动调用API: dingtalk_suite ISV套件回调server: dingtalk_suite_callback ISV SSO 免登API: dingtalk_sso