如何通过ACC API获取项目角色ID？现有方案存隐患求最优解

问题背景 #

在通过ACC API向项目添加用户时，必须指定角色ID，但存在以下痛点：

• 官方文档未提供获取ACC项目可用角色ID的合规接口
• ACC用户无法直接在UI中查看角色ID

现有的两种临时方案均存在明显不足：

• 方案1：调用BIM 360的Industry Roles接口获取角色ID，当前可用于ACC项目，但官方明确标注该接口不支持ACC，长期使用存在兼容性风险
• 方案2：手动为某文件夹添加所有可用角色，再通过ACC文档管理的文件夹权限接口提取角色信息，操作繁琐且无法自动同步角色的新增或变更

合规解决方案 #

官方推荐的可靠方式是使用ACC Admin API的项目角色查询接口，该接口专门用于获取ACC项目下的完整角色信息（包含角色ID）：

• 接口调用：GET /construction/admin/v1/projects/{projectId}/roles
• 权限要求：需具备项目管理员权限，且请求令牌需包含data:read和account:read权限范围

接口响应会返回每个角色的id（即添加用户时所需的角色ID）、角色名称、描述等关键信息，完全满足业务需求，且属于ACC官方原生支持的接口，无兼容性风险。

若需批量获取多个项目的角色ID，可结合ACC Admin API的项目列表接口，遍历项目ID后批量调用角色查询接口，实现自动化的角色信息同步。

注意事项 #

• 确保请求令牌的权限范围覆盖目标项目及账户资源
• 角色配置可能随项目管理需求更新，建议定期拉取最新角色数据，避免使用过期的角色ID

内容的提问来源于stack exchange，提问作者Guy Hareuveni