最近朋友需要做个政务钉钉的接口，研究后发现没有现成的C#的SDK，于是我们按钉钉接口文档自行编写SDK。

如下政务钉钉的SDK文档：

HTTP Request构成说明

HTTP Request URL

访问API的URL由以下方式构成:

https://{openplatform-domain}/

• 其中：operation 业务开发配置暴露的api name，大小写敏感。
  api url要求必须是https

如下所示的URL是根据工号查询人员帐号信息， 请求的目标URL:

https://openplatform.dg-work.cn/rpc/enhancedUserQuery/getUserByEmpId.json

HTTP Request Header

API规定HTTP请求的Header必须包含以下信息：

• X-Hmac-Auth-IP
  用户的IP地址
• X-Hmac-Auth-MAC
  用户的MAC地址
• X-Hmac-Auth-Timestamp
  请求发出时间，使用UTC时间，ISO8601格式为"yyyy-MM-ddTHH:mm:ss.sss+08:00"
• X-Hmac-Auth-Version
  API的版本号，版本号目前值为1.0
• X-Hmac-Auth-Nonce
  API的nonce，建议使用13位时间毫秒数 + 4位随机数
• apiKey
  应用的appkey
• X-Hmac-Auth-Signature

    请求的签名。签名计算方法如下：

    1.获取签名字符串的字节数组：请求Method+'n'+请求Header中的Timestamp+'n'+请求Header中的Nonce+'n'+请求的的URL(不带域名)+'n'+请求参数

    2.HmacSha256(SecretKey,签名字符串字节数组)

    3.对第二步结果使用Base64，得到签名结果

• 伪代码中使用到的函数的说明:

      HmacSha256 - Hmac-Sha256加密算法

   计算请求签名时请将StringToSign作为消息，

   SecretKey作为密钥。            

 * base64 - base64 编码算法

 * HTTPRequestMethod

   HTTP请求方法，如GET、POST或PUT等，

   HTTP API只支持GET/POST方法。注意GET/POST需要大写。

 * HttpRequestHeaderTimestamp

   HTTP Request header中X-Hmac-Auth-Timestamp值

 * HttpRequestHeaderNonce

   HTTP Request Header中X-Hmac-Auth-Nonce值。

 * CanonicalURI

   HTTP URL中的路径部分，如"https://openplatform.dg-work.cn/rest/enhancedUserQuery/getUserByEmpId"中，

   CanonicalURI 为"/rest/enhancedUserQuery/getUserByEmpId"。

 * HttpRequestParams

   HTTP中POST和GET的参数，对其排序,忽略大小写的字典序排列。

   然后组装key1=value1&key2=value2。

   注意：如果出现类似key=value2&key=value1&key=value3时情况，请对值列表排序（升序），

        变成key=value1&key=value2&key=value3。

HTTP Response

HTTP Response Content

返回格式

{"_RequestId":"6D26836F-D51C-4716-9340-94C734B2F2BF",xxxx:xxx}

API Server会对HTTP请求进行验证:

• 验证请求头中包含的签名是否正确

• 验证X-Hmac-Auth-Timestamp包含的时间与服务器时间相差小 于15分钟，若认证未通过，Server会直接返回身份认证错误。

FAQ

• 如果出现tengine返回的400错误，提示：Your browser sent a request that this server could not understand.
  请检查先你的pom依赖，是不是有低版本的commons-codec，请exclude掉。
  原因是由于低版本的commons-codec的base64出来的字符串多了rn导致http报错格式错误。
• 上线前，请先你的线上机器确定网络是可以curl https://openplatform.dg-work.cn
• 签名报错，返回：SignatureDoesNotMatch
  请检查下自己的apiKey是否正确
  如果非java的客户端，检查下自己的参数是否按照升序排序
  如果参数是中文，签名时，中文参数不要encode，传参数时要url encode

在按上面文档写好SDK后，GET方法 以“查询组织下人员详情”为例

查询组织下人员详情

接口说明

查询组织下人员详情，包含个人信息和任职信息（为了保证查询效率，分页查询接口控制返回一万条数据）

调试

在API Explorer中调试该接口。

基本信息

中文名：查询组织下人员详情

接口名：/mozi/organization/pageOrganizationEmployeePositions

所在目录：获取通讯录用户信息

调用方式：GET（HTTPS）

请求参数

名称	类型	是否必填	示例值	描述
returnTotalSize	java.lang.Boolean	否		是否请求总数，默认是false
pageSize	java.lang.Integer	否		分页大小，默认是20，范围0-100
employeeStatus	java.lang.String	否		员工状态，A为有效，F为无效，默认是所有
organizationCode	java.lang.String	是		组织code
pageNo	java.lang.Integer	否		请求起始页，默认是1
tenantId	java.lang.Long	是		租户id

返回参数

参数	说明
_RequestId	网关请求ID
success	网关调用是否成功
errorCode	网关错误码
HostId	网关HostId
Code	网关Code
errorMsg	网关错误信息
errorLevel	网关错误级别
Message	网关信息
content.success	业务调用是否成功
content.requestId	业务请求ID
content.responseCode	业务响应Code
content.responseMessage	业务响应信息
content.data	业务返回值
content.totalSize	组织下用户总数
content.currentPage	当前页
content.pageSize	分页大小
content.data[].employeeName	员工名称
content.data[].employeeCode	员工Code
content.data[].gmtCreate	员工创建时间
content.data[].empGender	员工性别，具体参见‘人员数据字典表’
content.data[].empPoliticalStatusCode	政治面貌，具体参见‘人员数据字典表’
content.data[].empJobLevelCode	职级，具体参见‘人员数据字典表’
content.data[].empBudgetedPostCode	编制，具体参见‘人员数据字典表’
content.data[].status	人员状态，A 在职； F 离职
content.data[].govEmployeePositions	组织范围下的任职信息
content.data[].govEmployeePositions[].posJobRankCode	职务层次，具体参见‘人员数据字典表’
content.data[].govEmployeePositions[].orderInOrganization	任职在组织内排序
content.data[].govEmployeePositions[].mainJob	是否主职
content.data[].govEmployeePositions[].empPosUnitCode	任职所在单位
content.data[].govEmployeePositions[].gmtCreate	任职创建时间
content.data[].govEmployeePositions[].empPosInnerInstitutionCode	所在内设机构
content.data[].govEmployeePositions[].employeeCode	员工编码
content.data[].govEmployeePositions[].jobAttributesCode	任职属性
content.data[].govEmployeePositions[].organizationCode	部门编码
content.data[].govEmployeePositions[].empPosVirtualOrganizationCode	所在虚拟组织
content.data[].govEmployeePositions[].status	任职状态，A有效，F无效

DEMO例子：

在按上面文档写好SDK后，POST方法 以“根据组织Code查询详情”为例

接口说明

根据组织 Code 查询详情

调试

在API Explorer中调试该接口。

基本信息

中文名：根据组织Code查询详情

接口名：/mozi/organization/getOrganizationByCode

所在目录：获取通讯录部门信息

调用方式：POST（HTTPS）

请求参数

名称	类型	是否必填	描述
tenantId	Long	是	租户Id
organizationCode	String	是	组织 Code

返回参数

参数	说明
_RequestId	网关请求ID
success	网关调用是否成功
errorCode	网关错误码
HostId	网关HostId
Code	网关Code
errorMsg	网关错误信息
errorLevel	网关错误级别
Message	网关信息
content.success	业务调用是否成功
content.requestId	业务请求ID
content.responseCode	业务响应Code
content.responseMessage	业务响应信息
content.data	业务返回值
content.data.organizationCode	组织code
content.data.organizationName	显示名称
content.data.displayOrder	排序码
content.data.parentCode	父组织Code
content.data.parentName	父组织名称
content.data.status	组织状态
content.data.typeCode	组织类型Code
content.data.typeName	组织类型名称
content.data.gmtCreate	创建时间
content.data.responsibleEmployeeCodes	负责人code，|拼接多个
content.data.businessStripCodes	条线codes,多个用|拼接
content.data.address	详细地址
content.data.contactEmployeeCode	联系人code
content.data.contactNumber	联系人号码
content.data.divisionCode	行政区划code
content.data.shortName	组织全称
content.data.institutionCode	组织机构代码
content.data.otherName	规范化简称
content.data.postalCode	邮政编码
content.data.remarks	备注
content.data.unifiedSocialCreditCode	统一社会信用代码
content.data.institutionLevelCode	机构/单位级别
content.data.organizationExtProperties	组织扩展属性，自定义的拓展组织信息字段 注意：不同组织类型有各自的扩展属性
content.data.organizationExtProperties.code	组织扩展属性的Code
content.data.organizationExtProperties.type	扩展属性的类型： 0字符串类型 1数字类型 2 单选 3 多选
content.data.organizationExtProperties.value	扩展属性职： 字符串类型时，返回一个数值，如 ["stringValue"] 数字类型，返回一个数值，如 ["numberValue"] 单选，返回一个选项code，如 ["code1"] 多选，返回若干个选项code，如 ["code1","code2"]

DEMO例子：

 各位遇有任何问题或开发需求，欢迎与QQ：1828825660  （加好友请注明：CSDN）交流探讨。