前面一篇隨筆企業號的一些基礎信息，以及介紹如何配置企業號的回調方式實現和企業號服務器進行溝通的橋梁。本篇主要還是繼續介紹企業號的開發工作的開展，介紹微信企業號通訊錄管理開發功能，介紹其中組織機構裡面如何獲取和管理部門的信息等內容。
首先我們可以在企業號的管理後台裡面創建一個組織機構，裡面創建一些部門和人員列表，方便我們開發和使用。
例如創建一個廣州愛奇迪的根結構，然後在其中在創建一些組織機構，如下圖所示。
然後給組織結構根節點“廣州愛奇迪”增加一個管理員權限，以後再開發接口裡面也就可以使用這個管理員所屬的權限Secret值進行調用了。
CorpID是企業號的標識，每個企業號擁有一個唯一的CorpID；Secret是管理組憑證密鑰。
系統管理員可通過管理端的權限管理功能創建管理組，分配管理組對應用、通訊錄、接口的訪問權限。完成後，管理組即可獲得唯一的secret。系統管理員可通過權限管理查看所有管理組的secret，其他管理員可通過設置中的開發者憑據查看。
我的企業號的創建者和“廣州愛奇迪”組織結構的管理員是不同的，由於Secret是管理組憑證密鑰，因此管理者負責不同的組織機構管理的話，自己的管理Secret值可能就不同了。如果我們需要調用接口，就需要用到這個屬於自己權限級別的Secret值，如下圖所示。
如果不是企業號的創建者，那麼可能不能修改裡面的一些權限分配，只能查看。
和公眾號一樣，我們調用企業號API的第一步也是需要先獲取訪問的票據AccessToken。這個票據是全局性的，有一定的時效和頻率控制，因此需要適當的進行緩存，不能每次調用都去刷新獲取。
企業號獲取訪問票據的主要的邏輯代碼如下所示，其主要的就是需要使用管理者的Secret值去獲取對應的口令，這樣它就能夠知道管理的是那個組織結構的了。
/// <summary>
/// 獲取每次操作微信API的Token訪問令牌
/// </summary>
/// <param name="corpid">企業Id</param>
/// <param name="corpsecret">管理組的憑證密鑰</param>
/// <returns></returns>
public string GetAccessTokenNoCache(string corpid, string corpsecret)
{
var url = string.Format("https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={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;
}
微信企業號的說明如下所示：
當企業應用調用企業號接口時，企業號後台為根據此次訪問的AccessToken,校驗訪問的合法性以及所對應的管理組的管理權限以返回相應的結果。
注：你應該審慎配置管理組的權限，夠用即好，權限過大會增加誤操作可能性及信息安全隱患。
AccessToken是企業號的全局唯一票據，調用接口時需攜帶AccessToken。AccessToken需要用CorpID和Secret來換取，不同的Secret會返回不同的AccessToken。正常情況下AccessToken有效期為7200秒，有效期內重復獲取返回相同結果，並自動續期。由於獲取access_token的api調用次數非常有限，建議企業全局存儲與更新access_token，頻繁刷新access_token會導致api調用受限，影響自身業務。
有了第一節裡面的訪問票據，我們就可以利用API來做很多事情了，包括組織結構的獲取、創建、刪除等等功能。
創建部門的官方接口定義如下所示。
Https請求方式: POST
https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token=ACCESS_TOKEN
請求包結構體為:
{
"name": "郵箱產品組",
"parentid": "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 = "https://qyapi.weixin.qq.com/cgi-bin/department/create?access_token={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 對象實體類的定義如下所示，我們主要是根據返回結果進行定義的。
/// <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; }
}
上面小節介紹了如何封裝部門管理的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#開發微信門戶及應用》系列感興趣，可以關注我的其他文章，系列隨筆如下所示：
C#開發微信門戶及應用(16)-微信企業號的配置和使用
C#開發微信門戶及應用(15)-微信菜單增加掃一掃、發圖片、發地理位置功能
C#開發微信門戶及應用(14)-在微信菜單中采用重定向獲取用戶數據
C#開發微信門戶及應用(13)-使用地理位置擴展相關應用
C#開發微信門戶及應用(12)-使用語音處理
C#開發微信門戶及應用(11)--微信菜單的多種表現方式介紹
C#開發微信門戶及應用(10)--在管理系統中同步微信用戶分組信息
C#開發微信門戶及應用(9)-微信門戶菜單管理及提交到微信服務器
C#開發微信門戶及應用(8)-微信門戶應用管理系統功能介紹
C#開發微信門戶及應用(7)-微信多客服功能及開發集成
C#開發微信門戶及應用(6)--微信門戶菜單的管理操作
C#開發微信門戶及應用(5)--用戶分組信息管理
C#開發微信門戶及應用(4)--關注用戶列表及詳細信息管理
C#開發微信門戶及應用(3)--文本消息和圖文消息的應答
C#開發微信門戶及應用(2)--微信消息的處理和應答
C#開發微信門戶及應用(1)--開始使用微信接口
&可以作為“按位與”或是“取地址”運算符
下面是作為兩種用法的介紹：
1. 按位與運算 按位與運算符"&"是雙目運算符。其功能是參與運算的兩數各對應的二進位相與。只有對應的兩個二進位均為1時，結果位才為1 ，否則為0。參與運算的數以補碼方式出現。
例如：9&5可寫算式如下： 00001001 (9的二進制補碼)&00000101 (5的二進制補碼) 00000001 (1的二進制補碼)可見9&5=1。
按位與運算通常用來對某些位清0或保留某些位。例如把a 的高八位清 0 ， 保留低八位， 可作 a&255 運算 ( 255 的二進制數為0000000011111111)。
2.取地址
&作為一元運算符，結果是右操作對象的地址。
例如&x返回x的地址。
地址本身是一個抽象的概念，用於表示對象在存儲器中的邏輯位置
&可以作為“按位與”或是“取地址”運算符
下面是作為兩種用法的介紹：
1. 按位與運算 按位與運算符"&"是雙目運算符。其功能是參與運算的兩數各對應的二進位相與。只有對應的兩個二進位均為1時，結果位才為1 ，否則為0。參與運算的數以補碼方式出現。
例如：9&5可寫算式如下： 00001001 (9的二進制補碼)&00000101 (5的二進制補碼) 00000001 (1的二進制補碼)可見9&5=1。
按位與運算通常用來對某些位清0或保留某些位。例如把a 的高八位清 0 ， 保留低八位， 可作 a&255 運算 ( 255 的二進制數為0000000011111111)。
2.取地址
&作為一元運算符，結果是右操作對象的地址。
例如&x返回x的地址。
地址本身是一個抽象的概念，用於表示對象在存儲器中的邏輯位置
