Pentaho 安全管理一把梭：用 Rest API 搞定用户、角色与文件权限

Words 3663Read Time≈ 10 min
2026-2-11
cover
type
Post
status
Published
date
Feb 5, 2020 11:29
slug
summary
本文全面梳理了 Pentaho BA Server 的 Rest API 安全管理功能，涵盖用户增删改查与角色分配、角色的创建/删除/权限配置，以及文件与文件夹的 ACL 权限控制。所有示例基于 Basic Auth 认证，附带完整的 curl 请求指令与状态码说明。
tags
Pentaho
Data Warehouse
category
Data Engineering
icon
password
739
wordCount

前言

本文系统梳理了 Pentaho BA Server 中 用户、角色与文件权限管理 的全套 Rest API，覆盖三大领域：
  • 用户管理：创建、删除、改密码、查列表、角色分配与移除
  • 角色管理：创建、删除、查列表、查成员、权限分配与查询
  • 文件权限：文件夹创建、元数据获取、隐藏控制、ACL 权限配置
📌
认证方式：所有 API 调用均需 Pentaho 认证，本文示例统一使用 Basic Auth（Authorization: Basic YWRtaW46cGFzc3dvcmQ=）
通用请求格式：[server path]/[rest path]/[query parameter]
权限提示：大部分写操作需要管理员权限，文中以 ⚠️ 标注
官方文档：Pentaho REST API 认证教程

Users

用户是 Pentaho 安全体系的基本单元。通过以下 API，你可以像操控数据库一样批量管理平台用户——创建、删除、改密码、查列表、分配角色，统统用 curl 搞定。

创建用户

创建一个用户包括创建用户名和密码。此请求封装在具有用户名和密码值的user对象中，请注意创建用户不包括为其分配角色，若要分配角色需要建立另外的请求。 ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

Http Verb
Example Request
PUT
PUT /pentaho/api/userroledao/createUser

参数

Name
Description
Type
user
用于传递userName和password的对象
query

Request Body

user对象传递userName&password的示例如下：
Element
Media Types
user
*/*application/xmlapplication/octet-stream

Response Body

Response Body包含操作状态码
Element
Media Types
(custom)
*/*application/xmlapplication/octet-stream

请求指令

创建viviran的用户

状态码

Code
Description
200*
Successfully created new user(实际上是204,无返回内容)
400
Provided data has invalid format.
401
未认证
403
Only users with administrative privileges can access this method.
412
Unable to create user.

删除用户

使用一个query parameter实现用户列表的删除，若要批量删除用户，userName以tab(分隔. ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
PUT
PUT pentaho/api/userroledao/deleteUsers?userNames=user1%09user2%09

参数

Name
Description
Type
userName
用户名列表以tab (分隔
query

Request Body

无

Response Body

Response Body包含操作状态码
Element
Media Types
(custom)
*/*application/xmlapplication/octet-stream

请求指令

删除viviran

状态码

Code
Description
200*
Successfully created new user(实际上是204,无返回内容)
401
未认证
403
Only users with administrative privileges can access this method.
500
Internal server error prevented the system from properly retrieving either the user or roles.

修改用户密码

修改信息封装在ChangeUserPassword对象：userName, newPassword, oldPassword.

支持方法

HTTP Verb
Example Request
PUT
PUT pentaho/api/userroledao/user

参数

Name
Description
Type
ChangePasswordUser
封装了需要修改的用户的用户名、旧密码、新密码字段
query

Request Body

ChangePasswordUser对象传递的示例如下：

Response Body

Response Body包含操作状态码
Element
Media Types
(custom)
*/*application/xmlapplication/octet-stream

请求指令

修改suzy的密码password->newpassword

状态码

Code
Description
200*
Successfully created new user(实际上是204,无返回内容)
400
Provided data has invalid format.
401
未认证
403
Only users with administrative privileges can access this method.
412
Unable to create

获得用户列表

返回Pentaho资源库中的用户列表。

支持方法

HTTP Verb
Example Request
GET
GET pentaho/api/userroledao/users

参数

无

Request Body

无

Response Body

返回平台的用户列表。
Element
Media Types
userList
application/xmlapplication/json

请求指令

返回结果：

状态码

Code
Description
200
Successfully returned the list of users.
500
An error occurred in the platform while trying to access the list of users.

获取用户的角色

获得某一个用户的所有角色。

支持方法

HTTP Verb
Example Request
GET
GET pentaho/api/userroledao/userRoles?userName=suzy

参数

Name
Description
Type
userName
需要获得角色的用户
query

Request Body

无

Response Body

返回平台的用户的角色。
Element
Media Types
roleList
application/xmlapplication/json

请求指令

获得用户suzy的角色
返回结果：

状态码

Code
Description
200
Successfully retrieved the list of roles.
500
Invalid user parameter.

给用户分配角色

使用query parameters将系统存在的角色分配给系统已存在的用户。 如果用户名存在，但是角色系统不存在，也会返回204。这意味着调用是成功的，用户名也可以在系统找到，但是没有为用户分配该角色。这可以避免为用户分配多个角色时，其中一个角色不存在就报错的问题。 ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
PUT
PUT pentaho/api/userroledao/assignRoleToUser?userName=admin&roleNames=power%20user%09cto%09

参数

Name
Description
Type
userName
需要分配角色的用户名
query
roleNames
系统存在的角色名，分配多个角色时以tab(/t)分隔
query

Request Body

无

Response Body

Response Body包含状态码
Element
Media Types
(custom)
*/*application/xmlapplication/json

请求指令

给admin分配power user和cto的角色，注意特殊符号转译：&,space,tab

状态码

Code
Description
200*
Successfully append the roles to the user.(实际上是204)
403
Only users with administrative privileges can access this method.
500
Internal server error prevented the system from properly retrieving either the user or roles.

删除用户的角色

通过query parameters删除系统已存在的用户的指定角色 ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
PUT
PUT pentaho/api/userroledao/removeRoleFromUser?userName=admin&roleNames=Business%20User%09Power%20User%09

参数

Name
Description
Type
userName
需要删除角色的用户名
query
roleNames
平台存在的角色列表，删除多个时，用tab(分隔
query

Request Body

无

Response Body

Response Body包含操作状态码
Element
Media Types
(custom)
*/*application/xmlapplication/json

请求指令

删除admin的cto和power user的角色，注意特殊符号转译：&,space,tab

状态码

Code
Description
200*
Successfully removed the roles from the user.(实际是204)
403
Only users with administrative privileges can access this method.
500
Internal server error prevented the system from properly retrieving either the user or roles.

Roles

如果说用户是演员，角色就是剧本——决定了每个人能在舞台上做什么。Pentaho 的角色机制支撑着整套权限体系，以下 API 帮你编排这一切。

创建角色

创建一个角色，该角色默认没有任何权限。若要分配权限，需额外调用「给角色分配权限」接口。
⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
PUT
PUT pentaho/api/userroledao/createRole?roleName=rName

参数

Name
Description
Type
roleName
新建的角色名
query

Request Body

无

Response Body

Response Body包含操作状态码 | Element | Media Types | | ——– | ——————————————- | | (custom) | */*
application/xml
application/json |

请求指令

新增cto的角色

状态码

Code
Description
200*
Successfully created new role.（实际上是204）
400
Provided data has invalid format.
403
Only users with administrative privileges can access this method.
500
Unable to create role objects.

删除角色

删除平台角色，可批量删除 ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
PUT
PUT pentaho/api/userroledao/deleteRoles?roleNames=role1%09

参数

Name
Description
Type
roleNames
平台存在的角色，批量删除以tab(分隔
query

Request Body

无

Response Body

Response Body包含操作状态码 | Element | Media Types | | ——– | ——————————————- | | (custom) | */*
application/xml
application/json |

请求指令

删除角色role5，role6

状态码

Code
Description
200*
Successfully deleted the list of roles.（实际上是204）
403
Only users with administrative privileges can access this method.
500
The system was unable to delete the roles passed in.

获取角色列表

获得平台的角色列表。

支持方法

HTTP Verb
Example Request
GET
GET pentaho/api/userroledao/roles

参数

Name
Description
Type

Request Body

无

Response Body

返回平台的角色列表
Element
Media Types
roleList
application/xmlapplication/json

请求指令

返回结果：

状态码

Code
Description
200
Successfully retrieved the list of roles.
500
The system was not able to return the list of roles.

获取角色下的用户列表

获取某一角色下的用户列表，角色要在平台中存在。 ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
GET
GET pentaho/api/userroledao/roleMembers?roleName=Power%20User

参数

Name
Description
Type
roleName
获取用户列表的角色名
query

Request Body

无

Response Body

返回角色的用户列表
Element
Media Types
userList
application/xmlapplication/json

请求指令

返回结果：

状态码

Code
Description
200*
Successfully retrieved the list of Users.（实际上是204）
403
Only users with administrative privileges can access this method.
500
The system was not able to return the list of users.

给角色分配权限

为角色分配系统的物理权限，该调用将为角色重新设置权限列表。如果新分配权限列表包含角色以前没有的权限，则增加权限。如果新分配权限列表去掉了角色以前的权限，则删除权限。 ⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
PUT
PUT /pentaho/api/userroledao/roleAssignments

参数

Name
Description
Type
roleAssignments
Built from the Request payload, an example of the role assignments exists in the example request.
query

Request Body

Built from the Request payload, an example of the role assignments exists in the example request.
Element
Media Types
logicalRoleAssignments
application/xmlapplication/json

Response Body

Response Body包含操作状态码
Element
Media Types
(custom)
*/*application/xmlapplication/json

状态码

Code
Description
200*
Successfully applied the logical role assignment.(实际上是204)
403
Only users with administrative privileges can access this method.

列出角色的权限

检索平台中的角色列表和操作权限映射，以及操作权限列表。逻辑角色名称映射由地区决定。如果区域设置为空，系统将使用默认的区域设置 en。
⚠️ 终端用户必须有管理权限才可以执行。

支持方法

HTTP Verb
Example Request
GET
GET pentaho/api/userroledao/logicalRoleMap?locale=en

参数

Name
Description
Type
locale
locale参数是可选的，它决定系统角色映射中物理权限的本地化角色名称。
query

Request Body

无

Response Body

当前系统的角色映射。每个赋值都包含不可变标志，不可变赋值的角色不能被编辑。这对于管理员之类的角色非常有用，他们不应该失去管理特权。分配中的逻辑角色是当前映射到角色的物理权限。角色名是可以分配给用户的角色的名称。系统角色映射还包括系统中所有物理权限的列表及其本地化的角色名称。本地化角色名基于传递给调用的本地角色名，默认为“en”。这些是可用于创建角色的物理权限。
Element
Media Types
systemRolesMap
application/xmlapplication/json

请求指令

返回结果

状态码

Code
Description
200
Successfully retrieved the permissions of roles.
403
Only users with administrative privileges can access this method.

文件权限

搞定了用户和角色，接下来是重头戏——文件权限。谁能看什么文件、谁能改什么目录，这些都可以通过 API 精确控制。下面的示例使用 Cookie 认证（JSESSIONID），展示更贴近实际的调用方式。

创建文件夹

获取文件元数据信息

删除文件

修改文件是否对用户隐藏（用户不拥有管理安全性权限）

设置了隐藏，则 用户 zcyuan 对其文件不可见
notion image

获取文件权限信息

  • aces : 角色或用户
    • modifiable : （用户或角色）的权限
      • 完全控制 ： <permissions> 4</permissions>
      • 删除： <permissions>3</permissions>
          • <permissions>2</permissions>
          <permissions>4</permissions>
      • 写：<permissions>1</permissions>
          • <permissions>0</permissions>
      • 读 ：<permissions>0</permissions>

给文件添加用户或角色

notion image

给zcyuan添加zjft角色，登录查看文件

notion image

表结构

ab_files
字段名
类型
描述
id
int
no
int
功能点
file_id
int
文件id
file_name
varchar
文件名
described
varchar
文件描述
theme
varchar
主题
source
tinyint
文件来源（1:superset，2:pentaho）
path
varchar
iframe url
type
tinyint
文件类型（0：chart，1:dashbord，2:prpt ）
cover
varhcar
模版路径
is_delete
int
该文件是否删除
create_dtm
datedtime
创建时间
ab_file_flag
字段名
类型
描述
id
int
user_id
int
用户id
file_id
int
文件id
board
tinyint
是否加入看板
top
tinyint
是否置顶
top_dtm
datetime
置顶时间
row
int
看板排序
由图可知zcyuan用户可看zjft角色下所有的文件，且用户文件/home/zcyuan文件夹被隐藏

结语

到这里，Pentaho Rest API 的用户、角色与文件权限管理就全部覆盖了。快速回顾一下：
领域
核心能力
典型场景
用户管理
CRUD + 角色分配/移除
批量创建新员工账号、离职账号清理
角色管理
CRUD + 权限配置
按部门或项目划分权限组
文件权限
ACL + 隐藏控制
多租户文件隔离、敏感报表保护
这些 API 的真正威力在于 自动化。想象一下：新员工入职时，HR 系统触发一个脚本，自动创建 Pentaho 账号、分配对应部门角色、配置文件目录权限——整个过程零人工干预。结合 CI/CD 流水线，你甚至可以把权限配置纳入版本控制，实现「权限即代码」。
掌握了这套 API，Pentaho 的安全管理就从「手动点按钮」进化到了「一键自动化」。🚀

参考资料

https://help.pentaho.com/Documentation/8.3/Developer_center/REST_API_Reference/User_Role_Management/0O0
Loading...