文档

权限管理

更新时间:

本文档描述PDS的权限管理功能,您可以通过PDS提供的默认客户端使用权限管理功能,也可以参考该文档调用API实现权限管理功能。

基本概念

示意图

image
  • 用户树是指用户和团队之间的关系构建出来的树状结构,有上下层级的关系(一个用户可以作为多个团队的成员,一个团队只能作为一个团队的成员)。

  • 文件树是指文件和文件夹之间的关系构建出来的树状结构,有上下层级的关系(如上图示例)。

  • 文件授权是指将一个文件夹作为资源授权给一个用户或者团队。当前只能对文件夹授权,不支持文件授权。

  • 所有文件授权都是通过角色的方式赋予操作权限,系统默认提供了一些常用角色(如下图)。

  • 每个角色都有一个权限列表,权限列表描述了当前角色的操作权限。

  • 团队权限继承是指给团队授权的权限,子孙团队下的用户是否能继承这些权限。 比如“研发部云盘”授权给“研发部”团队,如果不开启继承,则只有“用户4”作为“研发部”的直接成员可以使用这条权限,“用户2”和“用户3”就无法使用这条权限。

  • 文件权限继承是指如果文件树上的一个文件夹被授权,文件夹下所有子孙文件或文件夹都会继承此权限。

  • 权限覆盖是指当一个用户对一个资源有多条可用权限时,权限之间会相互覆盖。 比如上图的两条授权,使“用户4”对于“项目资料”文件夹同时拥有“预览者”和“编辑者”权限。“预览者”权限来自于父团队的授权,"编辑者"权限来自于给自己的授权。当多条权限同时作用于用户时,离用户近的权限会覆盖掉离用户远的权限,所以当“用户4”访问“项目资料”文件夹时,使用“编辑者”权限。这里有一种特殊情况,由于用户可以作为多个团队的成员,当用户归属的多个团队被授予不同权限时,会将多条权限取并集作为用户访问权限。

系统默认角色的权限列表:

imageimage

API调用及示例

1. 将文件夹共享授权给用户或团队

FileAddPermission - 文件共享授权给用户或组

共享授权分两种情况,一种是个人空间的文件共享,另一种是团队空间的文件授权。

  • 个人空间的共享是将文件夹直接作为顶层文件夹共享,不保留文件夹在空间中的路径,收到共享的用户看到的是被共享的文件夹列表。

  • 团队空间的授权是将文件夹授予对应权限并且逐级向上将所有父文件夹都设置为可见权限, 收到授权的用户看到的是有权限的空间列表,保留了每个授权文件夹的完整路径结构,更方便团队内部协作。如果想直接授权整个团队空间,file_id字段可以直接填root。

  • 共享时可以选择被共享者以何种角色访问资源,共有12种系统预定义角色可供选择,参见数据结构FilePermissionMember中关于role_id字段的描述。

  • 共享时支持批量配置,member_list字段是一个列表,其中每一项都是一个独立的权限配置请求。一次性为多个用户/团队授权只需在member_list中新增项即可。

说明

每个空间内的授权记录建议不超过5000条,每个文件夹的授权记录建议不超过500条,推荐使用团队授权来减少个人用户的相同授权记录。如果您有场景超出以上规格,请联系我们。

请求示例

{
  "drive_id": "1",
  "file_id": "63fad1c32fe8717da94e4b93b83fb248855f7fd6",
  "member_list": [{
    "identity": {
      "identity_type": "IT_User",
      "identity_id": "39df109b4f4f428db75898bbb0644fa5"
    },
    "expire_time": 1677599999999,
    "role_id": "SystemFileViewer"
  }]
}

响应示例

204 NoContent

2. 取消文件夹的共享授权

FileRemovePermission - 取消文件共享授权

通过member_list参数支持批量取消共享授权。

请求示例

{
  "drive_id": "1",
  "file_id": "63fad1c32fe8717da94e4b93b83fb248855f7fd6",
  "member_list": [{
    "identity": {
      "identity_type": "IT_User",
      "identity_id": "39df109b4f4f428db75898bbb0644fa5"
    },
    "role_id": "SystemFileViewer"
  }]
}

响应示例

204 NoContent

3. 列举文件夹的共享授权记录

FileListPermission - 列举文件的共享或授权记录

列举文件夹上已有的共享授权列表。

请求示例

{
  "drive_id": "1",
  "file_id": "63fad1c32fe8717da94e4b93b83fb248855f7fd6"
}

响应示例

[{
  "identity": {
    "identity_type": "IT_User",
    "identity_id": "39df109b4f4f428db75898bbb0644fa5",
    "identity_name": "测试用户1"
  },
  "role_id": "SystemFileViewer",
  "expire_time": 1677599999999,
  "disinherit_sub_group": true
}]

4. 列举收到的个人空间共享列表

ListReceivedFile - 收到的共享文件夹列表

请求示例

{
  "limit": 100,
  "marker": ""
}

响应示例

{
  "items": [{
    "drive_id": "1",
    "domain_id": "bj3231",
    "file_id": "63fad1c32fe8717da94e4b93b83fb248855f7fd6",
    "name": "新建文件夹",
    "type": "folder",
    "created_at": "2023-02-26T03:28:03.744Z",
    "updated_at": "2023-02-26T03:28:03.747Z",
    "hidden": false,
    "starred": false,
    "status": "available",
    "parent_file_id": "root",
    "encrypt_mode": "none",
    "creator_type": "User",
    "creator_id": "superadmin",
    "creator_name": "superadmin",
    "last_modifier_type": "User",
    "last_modifier_id": "superadmin",
    "last_modifier_name": "superadmin",
    "action_list": ["FILE.LIST", "FILE.VISIBLE", "FILE.PREVIEW"]
  }],
  "next_marker": ""
}

5. 列举有权限访问的团队空间列表

ListMyGroupDrive - 收到的授权团队空间列表

请求示例

{
  "limit": 100,
  "marker": ""
}

响应示例

{
  "items": [{
    "domain_id": "bj3231",
    "drive_id": "1020",
    "drive_name": "某公司",
    "description": "",
    "creator": "superadmin",
    "owner": "929bf1cec48d4eb28a6cca0af29f1b8f",
    "owner_type": "group",
    "drive_type": "normal",
    "status": "enabled",
    "used_size": 0,
    "total_size": -1,
    "store_id": "e28815e2f4e9434c90a5209a6943a536",
    "action_list": ["FILE.VISIBLE", "FILE.LIST"],
    "created_at": "2023-02-26T03:28:40.875Z",
    "updated_at": "2023-02-26T03:28:40.877Z",
    "category": ""
  }],
  "next_marker": ""
}

6. 将用户配置为团队管理员

AssignRole - 分配角色

调用该接口进行权限配置,配置的实体对象为目标user,配置的角色为团队管理员,管理的资源对象为目标团队。

请求示例

{
  "role_id": "SystemGroupAdmin",
  "identity": {
    "identity_type": "IT_User",
    "identity_id": "user2"
  },
  "is_sub_group_inheritable": true,
  "manage_resource_type": "RT_Group",
  "manage_resource_id": "9dcabccf59464b4f9a5693d972b8af58"
}

响应示例

204 NoContent

7. 取消用户的团队管理员授权

CancelAssignRole - 取消分配的角色

调用该接口删除已有的授权记录,即需取消用户的团队管理员角色。

请求示例

{
  "role_id": "SystemGroupAdmin",
  "identity": {
    "identity_type": "IT_User",
    "identity_id": "user2"
  },
  "is_sub_group_inheritable": false,
  "manage_resource_type": "RT_Group",
  "manage_resource_id": "9dcabccf59464b4f9a5693d972b8af58"
}

响应示例

204 NoContent

8. 列举团队管理员

ListAssignment - 列举已分配的角色列表

该接口的作用是根据指定的资源类型和ID,列举所有管理它的对象。如根据团队ID,获取所有的团队管理员授权记录。

请求示例

{
  "manage_resource_type": "RT_Group",
  "manage_resource_id": "105***b82",
  "marker": "",
  "limit": 100
}

响应示例

{
  "assignment_list": [
    {
      "domain_id": "hz1",
      "identity": {
        "identity_type": "IT_User",
        "identity_id": "164***3dw"
      },
      "role_id": "SystemGroupAdmin",
      "manage_resource_type": "RT_Group",
      "manage_resource_id": "105***b82",
      "creator": "216***c83",
       "created_at": 1622682267564
    },
    {
      "domain_id": "hz1",
      "identity": {
        "identity_type": "IT_User",
        "identity_id": "39d***fa5"
      },
      "role_id": "SystemGroupAdmin",
      "manage_resource_type": "RT_Group",
      "manage_resource_id": "105***b82",
      "creator": "216***c83",
      "created_at": 1622682267564
    }
  ],
  "next_marker": "NWQ1Yjk4YmI1ZDRlYmU1Y2E0YWE0NmJhYWJmODBhNDQ2NzhlMTRhMg"
}