66- 未实现 WxCpTpService 初始化,需要的小伙伴可以参考多 WxCpService 配置的实现。
77- 未实现 WxCpCgService 初始化,需要的小伙伴可以参考多 WxCpService 配置的实现。
88
9+ ## 关于 corp-secret 的说明
10+
11+ 企业微信中不同功能模块对应不同的 ` corp-secret ` ,每种 Secret 只对对应模块的接口具有调用权限:
12+
13+ | Secret 类型 | 获取位置 | 可调用的接口 | 是否需要 agent-id |
14+ | ---| ---| ---| ---|
15+ | 自建应用 Secret | 应用管理 → 自建应用 → 选择应用 → 查看 Secret | 该应用有权限的接口 | ** 必填** |
16+ | 通讯录同步 Secret | 管理工具 → 通讯录同步 → 查看 Secret | 部门/成员增删改查等通讯录接口 | ** 不填** |
17+ | 客户联系 Secret | 客户联系 → API → Secret | 客户联系相关接口 | 不填 |
18+
19+ > ** 常见问题** :
20+ > - 使用自建应用 Secret + agent-id 可以获取部门列表,但** 无法更新部门** (因为写接口需要通讯录同步权限)
21+ > - 使用通讯录同步 Secret 可以同步部门,但** 调用某些需要 agent-id 的应用接口会报错**
22+
23+ 如需同时使用多种权限范围,可在 ` wx.cp.corps ` 下配置多个条目,每个条目使用对应权限的 Secret,通过不同的 ` tenantId ` 区分后使用。
24+
25+ > ** 配置限制说明** :
26+ > - 当前 starter 实现会校验:同一 ` corp-id ` 下,` agent-id ` ** 必须唯一**
27+ > - 同一 ` corp-id ` 下,** 只能有一个条目不填 ` agent-id ` **
28+ > - 否则会因为 token/ticket 缓存 key 冲突而在启动时直接抛异常
29+ >
30+ > 因此,像"通讯录同步 Secret""客户联系 Secret"这类通常不填写 ` agent-id ` 的配置,** 不能** 在同一个 ` corp-id ` 下同时配置多个 ` agent-id ` 均为空的条目;如确有多个条目,请确保其中最多只有一个未填写 ` agent-id ` 。
31+
932## 快速开始
1033
11341 . 引入依赖
1841 ```
19422. 添加配置(application.properties)
2043 ```properties
21- # 应用 1 配置
22- wx.cp.corps.tenantId1.corp-id = @corp-id
23- wx.cp.corps.tenantId1.corp-secret = @corp-secret
24- ## 选填
25- wx.cp.corps.tenantId1.agent-id = @agent-id
26- wx.cp.corps.tenantId1.token = @token
27- wx.cp.corps.tenantId1.aes-key = @aes-key
28- wx.cp.corps.tenantId1.msg-audit-priKey = @msg-audit-priKey
29- wx.cp.corps.tenantId1.msg-audit-lib-path = @msg-audit-lib-path
30-
31- # 应用 2 配置
32- wx.cp.corps.tenantId2.corp-id = @corp-id
33- wx.cp.corps.tenantId2.corp-secret = @corp-secret
44+ # 自建应用 1 配置(使用自建应用 Secret,需填写 agent-id)
45+ wx.cp.corps.app1.corp-id = @corp-id
46+ wx.cp.corps.app1.corp-secret = @自建应用的Secret(在"应用管理-自建应用"中查看)
47+ wx.cp.corps.app1.agent-id = @自建应用的AgentId
3448 ## 选填
35- wx.cp.corps.tenantId2.agent-id = @agent-id
36- wx.cp.corps.tenantId2.token = @token
37- wx.cp.corps.tenantId2.aes-key = @aes-key
38- wx.cp.corps.tenantId2.msg-audit-priKey = @msg-audit-priKey
39- wx.cp.corps.tenantId2.msg-audit-lib-path = @msg-audit-lib-path
49+ wx.cp.corps.app1.token = @token
50+ wx.cp.corps.app1.aes-key = @aes-key
51+ wx.cp.corps.app1.msg-audit-priKey = @msg-audit-priKey
52+ wx.cp.corps.app1.msg-audit-lib-path = @msg-audit-lib-path
53+
54+ # 通讯录同步配置(使用通讯录同步 Secret,不需要填写 agent-id)
55+ # 此配置用于部门、成员的增删改查等通讯录管理操作
56+ wx.cp.corps.contact.corp-id = @corp-id
57+ wx.cp.corps.contact.corp-secret = @通讯录同步的Secret(在"管理工具-通讯录同步"中查看)
58+ ## agent-id 不填,通讯录同步不需要 agentId
4059
4160 # 公共配置
4261 ## ConfigStorage 配置(选填)
5978
6079```java
6180import com.binarywang.spring.starter.wxjava.cp.service.WxCpMultiServices;
81+ import me.chanjar.weixin.cp.api.WxCpDepartmentService;
6282import me.chanjar.weixin.cp.api.WxCpService;
6383import me.chanjar.weixin.cp.api.WxCpUserService;
84+ import me.chanjar.weixin.cp.bean.WxCpDepart;
6485import org.springframework.beans.factory.annotation.Autowired;
6586import org.springframework.stereotype.Service;
6687
@@ -70,27 +91,21 @@ public class DemoService {
7091 private WxCpMultiServices wxCpMultiServices;
7192
7293 public void test() {
73- // 应用 1 的 WxCpService
74- WxCpService wxCpService1 = wxCpMultiServices.getWxCpService("tenantId1");
75- WxCpUserService userService1 = wxCpService1.getUserService();
76- userService1.getUserId("xxx");
77- // todo ...
78-
79- // 应用 2 的 WxCpService
80- WxCpService wxCpService2 = wxCpMultiServices.getWxCpService("tenantId2");
81- WxCpUserService userService2 = wxCpService2.getUserService();
82- userService2.getUserId("xxx");
94+ // 使用自建应用的 WxCpService(对应 corp-secret 为自建应用 Secret)
95+ WxCpService appService = wxCpMultiServices.getWxCpService("app1");
96+ WxCpUserService userService = appService.getUserService();
97+ userService.getUserId("xxx");
8398 // todo ...
8499
85- // 应用 3 的 WxCpService
86- WxCpService wxCpService3 = wxCpMultiServices.getWxCpService("tenantId3");
87- // 判断是否为空
88- if (wxCpService3 == null) {
89- // todo wxCpService3 为空,请先配置 tenantId3 企业微信应用参数
90- return ;
91- }
92- WxCpUserService userService3 = wxCpService3.getUserService( );
93- userService3.getUserId("xxx" );
100+ // 使用通讯录同步的 WxCpService(对应 corp-secret 为通讯录同步 Secret)
101+ // 通讯录同步 Secret 具有部门/成员增删改查等权限
102+ WxCpService contactService = wxCpMultiServices.getWxCpService("contact");
103+ WxCpDepartmentService departmentService = contactService.getDepartmentService();
104+ // 更新部门示例(WxCpDepart 包含 id、name、parentId 等字段)
105+ WxCpDepart depart = new WxCpDepart() ;
106+ depart.setId(100L);
107+ depart.setName("新部门名称" );
108+ departmentService.update(depart );
94109 // todo ...
95110 }
96111}
0 commit comments