PAYATHON 2026

如何在不反复查询权限的情况下检测 ACC 文件夹权限变更？

数据阿明

能否不查询权限就发现变更？

父文件夹的更新时间和通用文件夹 webhook 都不能可靠地标记权限变更。要只查询权限发生变化的文件夹，需要有能够覆盖这些变更的通知或增量记录，或者由应用掌握全部权限写入操作。

本次查阅的 Autodesk 公开资料未能确认是否存在可完整追踪 ACC 文件夹权限变更的专用事件或增量查询机制。因此，如果管理员还会通过 ACC 界面或其他集成修改权限，仍需周期性核对权限。可以降低查询频率、避免重复同步，但无法保证既完全免除查询又不漏掉变更。

父文件夹能提供什么信息？

Data Management 的文件夹接口提供 lastModifiedTime 和 lastModifiedTimeRollup。后者描述文件夹或其子项的最近更新时间，但文档没有明确保证权限变更一定会更新这些字段。因此，即使 Drawings 的时间戳没有变化，也不能跳过 Folder_6 的权限检查。If-Modified-Since 同样不能直接证明权限未变。文件夹查询接口文档

子文件夹会继承父文件夹的权限，父级权限调整可能影响下级。父级未发生变化，也不能说明子文件夹没有单独调整权限。文件夹权限管理说明

Webhooks 和 audit logs 能否替代轮询？

Webhooks 只能用于明确支持的事件。不能仅凭 dm.folder.modified 的名称，就认定它覆盖权限的新增、修改和删除。本次未取得能确认该覆盖范围的官方事件说明，因此不宜将它作为权限同步的唯一触发器。

官方说明指出，文件夹 webhook 的 scope 可以递归覆盖子项。在父文件夹上订阅已支持的事件，可以扩大监听范围，但这并不意味着事件本身能覆盖权限变更。Webhooks Field Guide

使用 audit logs 前，需要确认是否有可供程序消费的变更记录。即使管理界面能查看日志，也要进一步确认：

  • 是否记录权限的新增、修改和删除，并包含目标文件夹 ID。
  • 是否有适用于当前产品和项目的公开读取 API。
  • 是否支持稳定分页、增量游标，以及足够的保留期限。

在确认这些条件之前，不能把日志当作完整的权限同步来源。

如何减少调用和重复同步？

可以根据权限修改入口选择方案。

修改方式可采用的方案适用限制
全部通过自己的应用修改权限写入成功后，将受影响文件夹加入刷新队列必须覆盖所有写入入口
ACC 界面和多个集成都能修改本地权限快照、分层轮询和周期性完整核对存在由轮询周期决定的检测延迟
已确认有完整的权限事件或日志接口按通知刷新目标文件夹，并保留核对任务必须确认事件覆盖范围和恢复机制

具体可以这样做：

  1. 建立初始快照。读取需要管理的文件夹权限，在本地保存规范化后的授权记录。官方 Folder Permission API 提供按文件夹读取、创建、更新和删除权限的接口。Folder Permission API 说明
  2. 记录应用内写入。权限修改成功后，将目标文件夹加入队列；涉及继承时，标记可能受影响的后代。短时间内对同一文件夹的多次修改可以合并刷新。
  3. 按需读取并比较。定时任务或刷新队列读取完整权限数据，规范化后与快照比较，仅在变化时执行下游同步。
  4. 安排周期性核对。活跃文件夹可以更频繁检查，稳定文件夹可以降低检查频率，但仍需定期覆盖全部目标，以发现应用外的修改。

快照比较可以减少重复写入和下游处理；要提前知道哪些权限查询可以省略，还需要可靠的变更来源。

权限快照如何比较？

下面的 Python 示例只负责生成本地摘要。normalized_entries 是应用根据实际 API 响应整理出的授权记录，并非 Autodesk 定义的响应结构。

import hashlib
import json


def permission_digest(normalized_entries):
    # 调用方须先统一字段，并对 actions 等无序集合排序、去重。
    rows = [
        json.dumps(
            entry,
            sort_keys=True,
            ensure_ascii=False,
            separators=(",", ":"),
        )
        for entry in normalized_entries
    ]
    canonical = json.dumps(
        sorted(rows),
        ensure_ascii=False,
        separators=(",", ":"),
    )
    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()

规范化时，应保留授权主体类型、主体 ID、权限动作，以及接口实际返回且影响判断的继承信息，排除请求时间等临时字段。如果响应存在分页，必须读取完整结果再比较。下游同步成功后再提交新摘要，避免因快照提前更新而跳过失败任务。

实施时还要注意什么？

  • 摘要表示已读取数据的状态。本地 hash 无法在调用 API 前告知远端是否改变；两次检查之间的短暂变更也可能无法通过快照发现。
  • 授权记录与用户最终访问权限有区别。用户的角色、公司归属或管理员身份变化，也可能影响访问能力。如果同步目标是用户的有效权限，需要同时考虑这些信息。文件夹权限管理说明
  • 查询失败不能视为空权限。遇到 403、429 或其他错误时，保留旧快照并记录失败；不要将失败结果同步为权限清空。
  • 轮询周期取决于允许的延迟。如果业务要求立即发现任何入口的权限变化，而平台又没有覆盖这些变化的可靠通知或变更记录，单靠缓存和父文件夹元数据无法满足要求。

备注：内容仅供参考。