调用Autodesk Data API获取文件夹内容返回不全问题

接口固有行为说明 #

• 你调用的 /data/v1/projects/[ProjectID]/folders/[folderId]/contents 接口默认仅返回目标文件夹下的直接子项，不支持递归查询深层级内容，无论是否携带分页参数，都不会自动遍历子文件夹返回嵌套内容。要获取深层文件/子文件夹，必须拿到当前层返回的子文件夹ID后，循环调用该接口逐层拉取。

筛选参数不生效的核心原因 #

• filter[fileType]=rvt 筛选规则仅对当前查询层级下的直接文件生效，不会穿透文件夹匹配深层文件。如果你的Project Files根目录下没有直接存放.rvt格式文件，所有rvt文件都保存在一级或多级子文件夹内，加了该筛选参数后自然不会返回任何文件数据。
• 该参数不会过滤文件夹类型的子项，因此你会看到接口仅返回根目录下的一级子文件夹，没有匹配的文件返回。
• 额外注意：filter[fileType] 匹配的是文件元数据的type字段，部分旧版上传的rvt文件、云端工作共享模式同步的rvt文件，该字段值可能不是rvt，如果要精准筛选rvt格式文件，建议搭配 filter[extension]=rvt 参数共同使用，避免漏匹配。

需逐一排查的遗漏项 #

• 校验传入的Project Files根文件夹ID正确性：BIM 360/ACC项目的Project Files根文件夹ID不等于项目ID，需要先调用项目顶层文件夹列表接口获取，对应实体类型为folders:autodesk.bim360:Folder，如果误传了其他普通文件夹ID，会直接导致返回内容不符合预期。
• 校验账号实际文件夹权限：你当前申请的token scope（data:search、data:create、data:read、data:write）满足接口调用要求，但要确保生成token使用的账号本身已经被加入对应BIM 360/ACC项目，且对Project Files下的目标内容有至少查看权限，后台文件夹权限配置如果屏蔽了账号对特定文件的访问，接口不会返回对应内容。
• 校验分页逻辑：page[limit]参数的最大有效值为200，你当前传值符合规范。如果当前层级子项总数超过200，接口响应头会携带next分页链接，需要逐页拉取完当前层所有内容，不要默认单次请求就能拉完当前层全部子项。

获取全项目rvt文件的正确实现逻辑 #

1. 以Project Files根文件夹ID为起点，调用contents接口拉取当前层直接子项，处理完当前层所有分页数据
2. 遍历当前层返回结果，将类型为items:autodesk.bim360:File、扩展名为rvt的条目存入结果集
3. 提取当前层返回结果中类型为folders:autodesk.bim360:Folder的子项，逐个记录子文件夹ID，递归调用contents接口拉取每个子文件夹下的内容
4. 重复上述步骤直到所有子文件夹遍历完成，即可拿到项目下所有rvt文件

不存在单接口一次性拉取全目录所有rvt文件的用法，官方接口本身没有提供全局递归查询能力，必须通过逐层遍历的方式实现。

内容的提问来源于stack exchange，提问作者Xero Phane