如何通过Forge获取BIM360文件夹、问题、碰撞及人员全量数据

这个需求完全可以通过Forge官方接口实现，核心是按模块做分页全量拉取+本地缓存，不要直接在看板前端直连Forge接口，避免鉴权泄露、接口限流、加载慢的问题，具体路径如下：

前置准备 #

• 先在Forge开发者后台创建应用，开通对应API的读权限：data:read、account:read、issues:read、clashes:read，给应用授权目标BIM360账号的访问权限，获取可调用接口的access_token作为所有请求的鉴权凭证。
• 第一步先拉取当前账号下所有有权限访问的项目ID列表，后续所有业务数据都按项目维度拉取。

各模块数据拉取方法 #

文件夹/子文件夹层级数据 #

• 先调用项目顶层内容接口，拿到项目根节点的folder_id
• 从根文件夹ID开始做递归遍历：循环调用文件夹内容查询接口，单页请求拉满最大支持的100条数据，把返回结果中类型为folders的条目提取出来，记录每个文件夹的父ID、名称、创建信息，再把每个子文件夹ID加入遍历队列，继续向下查询，直到队列里没有新的文件夹ID为止，本地存储时直接按父ID关联就能拼出完整层级树。
• 请求时带上filter[deleted]=false参数过滤掉已删除的无效节点，不需要额外过滤隐藏文件夹，避免漏掉权限可见的归档内容。

Issues（问题）全量数据 #

• 直接调用项目维度的Issues列表接口，单页拉100条循环翻页，直到返回空结果就完成全量拉取。拉取时不要加状态过滤参数，把问题ID、关联模型/位置、指派人、状态、创建/更新时间、关联附件评论这些字段全部落本地库即可。
• 如果单项目Issues总量超过1万条，不要硬翻页，按更新时间分段拉取，避免接口截断返回导致漏数。

Clashes（碰撞）全量数据 #

• 碰撞数据不在通用文档接口里，先拉取项目下所有模型集（Model Set）的ID，再逐个拉取每个模型集下的碰撞检测任务列表，拿到每个任务最新一次运行的结果ID。
• 基于结果ID分页拉取所有碰撞点数据，包含碰撞构件信息、位置、状态、责任人、分配时间字段即可，同样单页拉满100条循环翻页。
• 注意区分碰撞来源：如果你们的碰撞数据是在老版BIM360 Glue里生成的，要走Glue专属接口拉取，不要用Docs模块的碰撞接口，否则会拿不到数据。

Employees（人员）全量数据 #

• 先拿到BIM360的账号ID（注意不是单个项目的ID），调用账号维度的用户列表接口，分页拉取整个账号下所有激活成员的基础信息：用户ID、姓名、邮箱、公司、全局角色。
• 再逐个调用每个项目的成员列表接口，拉取用户在对应项目内的角色、项目权限字段，和之前拉到的账号层用户基础信息做关联匹配即可，不需要重复拉取用户基础属性。

同步优化注意事项 #

• Forge接口有明确的限流规则，单应用每分钟请求数不要超过600次，首次全量拉取时加100ms左右的请求间隔，避免被临时封禁。
• 首次全量同步完成后，后续做看板更新只需要跑增量同步：每次只拉取lastModifiedTime晚于上次同步时间的条目，不需要每次重拉全量，能把请求量降到原来的10%以下。
• 一定要搭中间层做数据缓存：把拉到的所有数据存在自己的业务数据库里，看板直接读本地库的数据，一来不会暴露Forge应用的密钥，二来看板加载速度比直连Forge快几个量级，也不会触发Forge的端侧访问限制。
• 翻页时直接用接口返回的next字段里的链接请求下一页，不要自己拼接分页参数，避免接口版本迭代后参数规则变化导致拉取漏数。

内容的提问来源于stack exchange，提问作者Praveen UnoTEAM