C#開發微信入口網站及應用微信企業號的通訊錄管理開發之部門管理

 前面一篇隨筆企業號的一些基礎訊息，以及介紹如何配置企業號的回調方式實現和企業號伺服器進行溝通的橋樑。本篇主要還是繼續介紹企業號的開發工作的開展，介紹微信企業號通訊錄管理開發功能，介紹其中組織機構裡面如何取得和管理部門的資訊等內容。

 1、企業組織的創建和配置

首先我們可以在企業號的管理後台裡面創建一個組織機構，裡面創建一些部門和人員列表，方便我們開發和使用。

例如創建一個廣州愛奇迪的根結構，然後在其中在創建一些組織機構，如下圖所示。

然後為組織結構根節點「廣州愛奇迪」增加一個管理員權限，以後再開發介面裡面也就可以使用這個管理員所屬的權限Secret值進行調用了。

CorpID是企業號的標識，每個企業號擁有一個唯一的CorpID；Secret是管理群組憑證金鑰。
系統管理員可透過管理端的權限管理功能建立管理群組，指派管理群組對應用程式、通訊錄、介面的存取權限。完成後，管理組即可獲得唯一的secret。系統管理員可透過權限管理查看所有管理群組的secret，其他管理員可透過設定中的開發者憑證查看。

我的企業號的創建者和「廣州愛奇迪」組織結構的管理員是不同的，由於Secret是管理群組憑證金鑰，因此管理者負責不同的組織機構管理的話，自己的管理Secret值可能就不同了。如果我們需要呼叫接口，就需要用到這個屬於自己權限等級的Secret值，如下圖。

 如果不是企業號的創建者，那麼可能無法修改裡面的一些權限分配，只能查看。

2、API存取的全域唯一票據AccessToken的取得

和公眾號一樣，我們呼叫企業號API的第一步也是需要先取得訪問的票據AccessToken。這個票據是全局性的，有一定的時效和頻率控制，因此需要適當的進行緩存，不能每次調用都去刷新獲取。

企業號取得存取票據的主要的邏輯代碼如下所示，其主要的就是需要使用管理者的Secret值去取得對應的口令，這樣它就能夠知道管理的是那個組織結構的了。

        /// <summary>
        /// 获取每次操作微信API的Token访问令牌        /// </summary>
        /// <param>企业Id
        /// <param>管理组的凭证密钥
        /// <returns></returns>
        public string GetAccessTokenNoCache(string corpid, string corpsecret)
        {            var url = string.Format("http://www.php.cn/{0}&corpsecret={1}",
                                    corpid, corpsecret);

            HttpHelper helper = new HttpHelper();
            string result = helper.GetHtml(url);            
            string regex = "\"access_token\":\"(?<token>.*?)\"";            
            string token = CRegex.GetText(result, regex, "token");            
            return token;
        }</token>

微信企業號的說明如下所示：

當企業應用程式調用企業號介面時，企業號後台為根據此次存取的AccessToken,校驗存取的合法性以及所對應的管理群組的管理權限以傳回對應的結果。

#：你應該審慎設定管理群組的權限，夠用即好，權限過大會增加誤操作可能性及資訊安全隱憂。

AccessToken是企業號的全域唯一票據，呼叫介面時需攜帶AccessToken。 AccessToken需要用CorpID和Secret來換取，不同的Secret會回傳不同的AccessToken。 正常情況下AccessToken有效期為7200秒，有效期內重複取得回傳相同結果，並自動續期。由於取得access_token的api呼叫次數非常有限，建議企業全域儲存與更新access_token，頻繁刷新access_token會導致api呼叫受限，影響自身業務。

 

2、通訊錄管理之部門資訊的維護

有了第一節裡面的存取票據，我們就可以利用API來做很多事情了，包括組織結構的取得、建立、刪除等等功能。

建立部門的官方介面定義如下所示。

• 請求說明

Https请求方式: POST

https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN

请求包结构体为:

{
   "name": "邮箱产品组",
   "parentid": "1"
}

• 参数说明

参数	必须	说明
access_token	是	调用接口凭证
name	是	部门名称。长度限制为1~64个字符
parentid	是	父亲部门id。根部门id为1

 

• 返回结果

{
   "errcode": 0,
   "errmsg": "created",
   "id": 2
}

根据上面的一些类似的接口定义说明，我们先来定义下组织机构部门数据的维护接口，然后在逐步实现和调用。

        #region 部门管理        /// <summary>
        /// 创建部门。        /// 管理员须拥有“操作通讯录”的接口权限，以及父部门的管理权限。        /// </summary>
        CorpDeptCreateJson CreateDept(string accessToken, string name, string parentId);        /// <summary>
        /// 更新部门。        /// 管理员须拥有“操作通讯录”的接口权限，以及该部门的管理权限。        /// </summary>
        CommonResult DeleteDept(string accessToken, int id);        /// <summary>
        /// 删除部门.        /// 管理员须拥有“操作通讯录”的接口权限，以及该部门的管理权限。        /// </summary>
        CorpDeptListJson ListDept(string accessToken);        /// <summary>
        /// 获取部门列表.        /// 管理员须拥有’获取部门列表’的接口权限，以及对部门的查看权限。        /// </summary>
        CommonResult UpdateDept(string accessToken, int id, string name); 
        #endregion

如创建部门的接口实现如下所示，主要就是构建URL和POST的数据包，然后统一调用并获取返回数据，转换为具体的Json对象实体即可。其他接口的实现方式类似，不在赘述。

        /// <summary>
        /// 创建部门。        /// 管理员须拥有“操作通讯录”的接口权限，以及父部门的管理权限。        /// </summary>
        public CorpDeptCreateJson CreateDept(string accessToken, string name, string parentId)
        {            string urlFormat = "http://www.php.cn/{0}";            var data = new
            {
                name = name,
                parentId = parentId
            };            var url = string.Format(urlFormat, accessToken);            var postData = data.ToJson();

            CorpDeptCreateJson result = CorpJsonHelper<corpdeptcreatejson>.ConvertJson(url, postData);            return result;
        }</corpdeptcreatejson>

CorpDeptCreateJson 对象实体类的定义如下所示，我们主要是根据返回结果进行定义的。

    /// <summary>
    /// 创建部门的返回结果    /// </summary>
    public class CorpDeptCreateJson : BaseJsonResult
    {        /// <summary>
        /// 返回的错误消息        /// </summary>
        public CorpReturnCode errcode { get; set; }        /// <summary>
        /// 对返回码的文本描述内容        /// </summary>
        public string errmsg { get; set; }        /// <summary>
        /// 创建的部门id。        /// </summary>
        public int id { get; set; }
    }

 

 3、部门管理的API调用

 上面小节介绍了如何封装部门管理的API，那么我们封装好了对应的接口和接口实现，怎么样在实际环境里面进行调用处理的呢，为了方便我创建一个小的Winform程序来测试对应API的功能，如下所示。

下面我们来介绍一下调用的代码和效果展示。

        private void btnCreateDeleteDept_Click(object sender, EventArgs e)
        {
            ICorpAddressBookApi bll = new CorpAddressBookApi();            string name = "测试部门";
            CorpDeptCreateJson json = bll.CreateDept(token, name, "2");            if (json != null)
            {
                Console.WriteLine("创建了部门：{0}， ID:{1}", name, json.id);                //更新部门信息
                name = "测试部门修改名称";
                CommonResult result = bll.UpdateDept(token, json.id, name);                if(result != null)
                {
                    Console.WriteLine("修改部门名称:{0} {1}", (result.Success ? "成功" : "失败"), result.ErrorMessage);
                }                //删除部门
                result = bll.DeleteDept(token, json.id);                if (result != null)
                {
                    Console.WriteLine("删除部门名称:{0} {1}", (result.Success ? "成功" : "失败"), result.ErrorMessage);
                }
            }
            
        }

        /// <summary>
        /// 获取部门列表        /// </summary>
        private void btnListDept_Click(object sender, EventArgs e)
        {
            ICorpAddressBookApi bll = new CorpAddressBookApi();
            CorpDeptListJson list = bll.ListDept(token);            foreach (CorpDeptJson info in list.department)
            {                string tips = string.Format("{0}:{1}", info.name, info.id);
                Console.WriteLine(tips);
            }
        }

 

 更多C#開發微信入口網站及應用微信企業號的通訊錄管理開發之部門管理相关文章请关注PHP中文网！