# 基础开发文档-权限API
本页主要介绍权限的API方法，开发者可以调用这些接口达到验权的目的。
例如验证指定用户是否具有某身份（管理员，全功能用户），获取指定用户所拥有的权限范围，指定用户在某个查询范围下是否有权，具有什么字段权限和数据规则等。

如果您有什么建议，欢迎在[金蝶社区](https://club.kdcloud.com/)留言反馈，我们会根据您的需求进行优化。







## 获取指定用户的权限信息


### 获取当前用户有权的所有实体信息

**接口名：getUsableEntitiesInfo**

该接口会获取当前用户有权“查看”的所有表单实体的信息（包括未开启权限控制的表单实体，全员应用下的表单实体，当前用户通过直接授权以及角色授权分配到的表单实体）。返回值是一个有多层结构的json字符串，包含云、应用、实体等层级。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID

**返回值**

返回值是一个JSON字符串，这是一个包含云、应用、实体层级的JSON字符串

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ;         //userId是指定的用户的ID（Long类型）
PermissionServiceHelper.getUsableEntitiesInfo(userId);
```






## 获取用户有权限的组织范围



### 获得用户所有有授权的组织（与具体表单实体无关）

**接口名：getUserHasPermOrgs**

该接口会获取当前用户有权“查看”的所有组织，和具体表单实体无关。这个组织范围等于用户直接授权+角色授权（通用角色和业务角色）中分配的组织的总和。

**参数说明：**


参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID

**返回值**

返回值是一个 HasPermOrgResult 对象，当 HasPermOrgResult 的 hasAllOrgPerm() 为true时，HasPermOrgResult 的 getHasPermOrgs() 返回值的内容为空，表示有权范围为所有组织。注意：务必先判断 HasPermOrgResult 的 hasAllOrgPerm() 方法。

**代码示例：**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;  //userId是指定的用户的ID（Long类型）
HasPermOrgResult hasPermOrgResult = PermissionServiceHelper.getUserHasPermOrgs(userId);
if(hasPermOrgResult.hasAllOrgPerm()){
    //这个表明拥有所有组织权限。
} else {
    //这个时候hasPermOrgIds才有意义。
    List<Long> hasPermOrgIds = hasPermOrgResult.getHasPermOrgs();
}
```



### 获取指定用户有权限的组织范围

**接口名：getAllPermOrgs**

该接口会获取指定用户在指定应用下指定实体上的有权组织范围，这个组织范围等于用户直接授权+角色授权（通用角色和业务角色）中在指定应用下指定实体上分配的组织的总和。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识
permItemId | String | 是 | 常用的可以使用 PermItemConst 下的常量，或查询 t_perm_permitem 表的FID 

**返回值**

返回值是一个 HasPermOrgResult 对象，当 HasPermOrgResult 的 hasAllOrgPerm() 为 true 时，HasPermOrgResult 的 getHasPermOrgs() 返回值的内容为空，表示有权范围为所有组织。注意：务必先判断 HasPermOrgResult 的 hasAllOrgPerm() 方法。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ;         //userId是指定的用户的ID（Long类型）
String appId = ;        //应用ID（注意是FID,而不是FNUMER）
String entityNum = ;    //实体编码
String permItemId = ;   //权限项ID（常用ID可以使用PermItemConst下的常量）
HasPermOrgResult hasPermOrgResult = PermissionServiceHelper.getAllPermOrgs(userId, appId, entityNum, permItemId);
if(hasPermOrgResult.hasAllOrgPerm()){
    //这个表明拥有所有组织权限。
} else {
    //这个时候hasPermOrgIds才有意义。
    List<Long> hasPermOrgIds = hasPermOrgResult.getHasPermOrgs();
}
```



### 获取指定用户有权限的组织范围（带职能类型）
**接口名：getAllPermOrgs**

该接口和上述2的区别就是多了一个职能类型参数，会在2的基础上过滤出符合指定职能类型下的组织，如果不存在符合的组织，则范围为空。

**参数说明**



| 参数        | 数据类型 | 必选 | 说明                                                         |
| ----------- | -------- | ---- | ------------------------------------------------------------ |
| userId      | Long     | 是   | 指定具体的用户ID                                             |
| orgViewType | String   | 是   | 值可以使用OrgViewType下的常量                                |
| appId       | String   | 是   | 是应用内码（FID）,而不是编码（FNUMER）                       |
| entityNum   | String   | 是   | 实体的标识                                                   |
| permItemId  | String   | 是   | 常用的可以使用 PermItemConst 下的常量，或查询 t_perm_permitem 表的 FID |

**返回值**

返回值是一个 HasPermOrgResult 对象，当 HasPermOrgResult 的 hasAllOrgPerm() 为true时，HasPermOrgResult 的 getHasPermOrgs() 返回值的内容为空，表示有权范围为所有组织。注意：务必先判断 HasPermOrgResult 的 hasAllOrgPerm() 方法。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ;         //userId是指定的用户的ID（Long类型）
String orgViewType = ;  //职能类型，值可以使用OrgViewType下的常量
String appId = ;        //应用ID（注意是FID,而不是FNUMER）
String entityNum = ;    //实体编码
String permItemId = ;   //权限项ID（常用ID可以使用PermItemConst下的常量）
HasPermOrgResult hasPermOrgResult = PermissionServiceHelper.getAllPermOrgs(userId, orgViewType, appId, entityNum, permItemId);
if(hasPermOrgResult.hasAllOrgPerm()){
    //这个表明拥有所有组织权限。
} else {
    //这个时候hasPermOrgIds才有意义。
    List<Long> hasPermOrgIds = hasPermOrgResult.getHasPermOrgs();
}
```



### 获取指定用户有权限的组织范围（带职能类型，“是否必须查出组织ID”等参数）
**接口名：getAllPermOrgs**

该接口和上述3的唯一区别是多了一个“必须查出组织列表内容”的参数，这个参数为true时，当HasPermOrgResult的hasAllOrgPerm（）为true， HasPermOrgResult的getHasPermOrgs()的返回值不为空，而是包含所有符合条件的组织ID。

**参数说明**

| 参数        | 数据类型 | 必选 | 说明                                                         |
| ----------- | -------- | ---- | ------------------------------------------------------------ |
| userId      | Long     | 是   | 指定具体的用户ID                                             |
| orgViewType | String   | 是   | 值可以使用 OrgViewType 下的常量                              |
| appId       | String   | 是   | 是应用内码（FID）,而不是编码（FNUMER）                       |
| entityNum   | String   | 是   | 实体的标识                                                   |
| permItemId  | String   | 是   | 常用的可以使用 PermItemConst 下的常量，或查询 t_perm_permitem 表的 FID |
| mustQuery   | Boolean  | 是   | 如果为 true，则 HasPermOrgResult 的 getHasPermOrgs() 的集合为空时，意味着有权组织范围为空。<br/>如果为 false，则和接口3是一样的。 |

**返回值**

该接口和上述3的唯一区别是多了一个“必须查出组织列表内容”的参数，这个参数为true时，当 HasPermOrgResult 的 hasAllOrgPerm() 为true， HasPermOrgResult 的 getHasPermOrgs() 的返回值不为空，而是包含所有符合条件的组织ID。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ;         //userId是指定的用户的ID（Long类型）
String orgViewType = ;  //职能类型，值可以使用OrgViewType下的常量
String appId = ;        //应用ID（注意是FID,而不是FNUMER）
String entityNum = ;    //实体编码
String permItemId = ;   //权限项ID（常用ID可以使用PermItemConst下的常量）
Boolean mustQuery = true;  
HasPermOrgResult hasPermOrgResult = PermissionServiceHelper.getAllPermOrgs(userId, orgViewType, appId, entityNum, permItemId, mustQuery);
//不需要判断 hasPermOrgResult.hasAllOrgPerm() 这个的真假了
List<Long> hasPermOrgIds = hasPermOrgResult.getHasPermOrgs();

```





## 功能权限验权接口



### 判断指定用户在特定条件下是否有权（指定应用指定表单的指定权限项，不考虑组织的情况）

**接口名：checkPermission**

判断指定用户是否拥有指定应用指定表单的指定权限项。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识
permItemId | String | 是 | 权限项目ID

**返回值**

返回值是一个Boolean，如果为 true，表明验证有权，否则无权。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;     
String appId = ...;  
String entityNum = ...;
String permItemId = ...;
Boolean hasPerm = PermissionServiceHelper.checkPermission(userId, appId, entityNum, permItemId);
```



### 判断指定用户在特定条件下是否有权（指定组织下，指定应用下，指定表单的指定权限项。考虑组织的情况）
**接口名：checkPermission**

判断指定用户在指定组织下是否拥有指定应用下指定表单的指定权限项

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID
orgId | Long | 是 | 指定组织的ID
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识
permItemId | String | 是 | 权限项目ID

**返回值**

返回值是一个 int，如果为1，表明验证有权，否则无权。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;     
Long orgId = ...;  
String appId = ...;  
String entityNum = ...;
String permItemId = ...;
Integer hasPermResult = PermissionServiceHelper.checkPermission(userId, orgId, appId, entityNum, permItemId);
if(hasPermResult==1) {
    //有权
} else {
    //无权
}

```



## 数据规则接口



### 获取指定用户，指定实体下的数据规则（返回结果含组织条件）

**接口名：getDataPermWithOrg**

获取指定用户、指定实体的数据规则。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识

**返回值**

返回值是一个 QFilter 对象，多个组织下的同一个实体的数据规则用 or 拼接取并集，
条件中会包含组织的条件。
例如 (orgid=1L and 规则1) or (orgid=2L and 规则2) or (orgid=3L and 规则3) ....

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;      
String appId = ...;  
String entityNum = ...;
QFilter qf = PermissionServiceHelper.getDataPermWithOrg(userId, appId, entityNum);
```




### 获取指定用户，指定实体下的数据规则（返回结果无组织条件，把多个组织下的规则取并集）
**接口名：getDataPermission**

获取指定用户、指定实体的数据规则。返回结果无组织条件，把多个组织下的规则取并集。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识

**返回值**

返回值是一个 QFilter 对象，返回结果无组织条件，把多个组织下的规则取并集。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;     
String appId = ...;  
String entityNum = ...;
QFilter qf = PermissionServiceHelper.getDataPermission(userId, appId, entityNum);
```




## 字段权限接口

### 获取指定用户，指定实体下的字段权限规则

**接口名：getFieldRulesSum**

不区分组织，获取指定用户、指定实体的字段权限规则（单个字段的权限范围将会是多个组织下的最小权限）

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识

**返回值**

返回值是一个 FieldControlRule 对象，调用 getCanNotReadFields() 和 getCanNotWriteFields() 可以分别获取到不可见和不可改的字段列表。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;     
String appId = ...;  
String entityNum = ...;
QFilter qf = PermissionServiceHelper.getFieldRulesSum(userId, appId, entityNum);
```




## 获取特殊数据权限

### 获取指定条件下的特殊数据权限的规则

**接口名：getOperationRuleFilter**

获取指定应用下指定实体的指定操作下特殊数据权限的规则。另外，可以指定受控组织。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
appId | String | 是 | 是应用内码（FID）,而不是编码（FNUMER）
entityNum | String | 是 | 实体的标识
operationKey | String | 是 | 操作标识（注意是操作标识而不是类型）
sbNotMatchTips | StringBuilder | 是 | 提示语 

**返回值**

返回值是一个 QFilter 对象,记录当前规则下的过滤条件。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

String appId = ...;  
String entityNum = ...;
String operationKey = ...;
StringBuilder sbNotMatchTips = new StringBuilder();
QFilter qf = PermissionServiceHelper.getOperationRuleFilter(appId, entityNum, operationKey, sbNotMatchTips);
```



## 授权接口

### 用户分配角色

**接口名：userAssignRole**

根据提供的权限信息完成用户分配角色的授权。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定用户ID
dimType | String | 是 | 取值来源于perm_ctrltype实体的编码（例如DIM_ORG是组织）
assignInfo | Map | 是 |  键是组织ID，值是角色ID的集合
orgInfo | Map | 否 | 键是组织ID，值是“是否包含下级”；可以传null，传null意味着默认所有组织都“不包含下级”。
ifAdd | Boolean | 是 | 如果是true，则为添加，false为删除；为false时，参数“orgInfo”传null即可。

**返回值**

返回值是 Boolean, 分配成功则返回 true，反之为 false。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;
String dimType = ...;
Map<Long, List<String>> assignInfo = ...;
Map<Long, Boolean> orgInfo = ...;
boolean ifAdd = ...;
Boolean success = PermissionServiceHelper.userAssignRole(userId, dimType, assignInfo, orgInfo, ifAdd);
```



### 角色分配组织用户

**接口名：roleAssignOrgUser**

根据提供的权限信息完成角色分配组织用户的授权。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
roleId | String | 是 | 指定角色ID
dimType | String | 是 | 取值来源于perm_ctrltype实体的编码（例如DIM_ORG是组织）
assignInfo | Map | 是 |  键是组织ID，值是角色ID的集合
orgInfo | Map | 否 | 键是组织ID，值是“是否包含下级”；可以传null，传null意味着默认所有组织都“不包含下级”。
ifAdd | Boolean | 是 | 如果是true，则为添加，false为删除；为false时，参数“orgInfo”传null即可。

**返回值**

返回值是 Boolean, 分配成功则返回 true，反之为 false。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long roleId = ...;
String dimType = ...;
Map<Long, List<Long>> assignInfo = ...;
Map<Long, Boolean> orgInfo = ...;
boolean ifAdd = ...;
Boolean success = PermissionServiceHelper.roleAssignOrgUser(roleId, dimType, assignInfo, orgInfo, ifAdd);
```



### 角色分配用户组织
**接口名：roleAssignUserOrg**

根据提供的权限信息完成角色分配用户组织的授权。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
roleId | String | 是 | 指定角色ID
dimType | String | 是 | 取值来源于perm_ctrltype实体的编码（例如DIM_ORG是组织）
assignInfo | Map | 是 |  键是组织ID，值是角色ID的集合
orgInfo | Map | 否 | 键是组织ID，值是“是否包含下级”；可以传null，传null意味着默认所有组织都“不包含下级”。
ifAdd | Boolean | 是 | 如果是true，则为添加，false为删除；为false时，参数“orgInfo”传null即可。

**返回值**

返回值是 Boolean, 分配成功则返回 true，反之为 false。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long roleId = ...;
String dimType = ...;
Map<Long, List<Long>> assignInfo = ...;
Map<Long, Boolean> orgInfo = ...;
boolean ifAdd = ...;
Boolean success = PermissionServiceHelper.roleAssignUserOrg(roleId, dimType, assignInfo, orgInfo, ifAdd);
```




### 用户直接授权
**接口名：userDirectAssignPerm**

根据提供的权限信息完成用户直接授权。

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定用户ID
dimType | Long | 是 |可能是业务单元ID，合并报表的体系ID，或者其他ID
dimObjId | String | 是 |  取值来源于perm_ctrltype的编码
appEntityPermItemMap | Map | 否 | 键是应用ID，值是实体和权限项的映射
addOrRemove | Boolean | 是 |  true 为授权 , false为取消授权

**返回值**

返回值是 Boolean, 分配成功则返回 true，反之为 false。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;  
String dimType = ...;  
Long dimObjId = ...;
Map<String, Map<String, List<String>>> appEntityPermItemMap = ...;
boolean addOrRemove = ...;
Boolean success = PermissionServiceHelper.userDirectAssignPerm(userId, dimType, dimObjId, appEntityPermItemMap, addOrRemove);

```



## 判断指定用户是否是管理员

**接口名：isAdminUser**

该接口会判断指定用户是否管理员

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定具体的用户ID

**返回值**

返回值Boolean，true表明是管理员，否则不是。

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;   //userId是指定的用户的ID（Long类型）
Boolean isAdmin = PermissionServiceHelper.isAdminUser(userId);
```




## 判断指定用户是否是全功能用户
**接口名：isSuperUser**

该接口会判断指定用户是否全功能用户

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定用户ID

**返回值**

返回值Boolean，true表明是全功能用户，否则不是。

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;   //userId是指定的用户的ID（Long类型）
Boolean isSuperUser = PermissionServiceHelper.isSuperUser(userId);

```



## 获取断用户和应用的权限关系


### 获取指定用户有权的应用ID列表

**接口名：getUserBizApps**

该接口会获取用户有权使用的应用ID列表

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
userId | Long | 是 | 指定用户ID

**返回值**

返回值是一个List<String>，包含所有有权的应用ID

**代码示例**

```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

Long userId = ...;   //userId是指定的用户的ID（Long类型）
List<String> list = PermissionServiceHelper.getUserBizApps(userId);
```



### 获取拥有指定应用权限的用户ID列表
**接口名：getAppUser**

该接口会根据应用ID，获取拥有该应用权限的用户ID列表

**参数说明**

参数 | 数据类型 | 必选 | 说明
---|---|---|---
appId | String | 是 | 指定应用ID

**返回值**

返回值是一个Set<Long>，包含所有对指定应用有权的用户ID列表

**代码示例**
```java
import kd.bos.servicehelper.permission.PermissionServiceHelper;

String appId = ...; 
Set<Long> userIds = PermissionServiceHelper.getAppUser(appId);


```