How to Create Issue Subtypes and Custom Attributes via APIs in Autodesk?

在建筑信息模型（BIM）与云端协作平台日益普及的今天，Autodesk 旗下的 BIM 360 与 Autodesk Construction Cloud（ACC）已成为全球工程团队管理项目质量、安全与进度的核心工具。其中，“问题”（Issue）作为追踪现场缺陷、设计变更和任务分配的关键模块，其灵活性与可定制性直接影响项目效率。然而，许多用户仍受限于默认的问题类型与字段，无法满足复杂业务场景。实际上，通过 Autodesk API，开发者完全可以自主创建问题子类型（Issue Subtypes）和自定义属性（Custom Attributes），实现精细化的数据管理。本文将深入解析这一技术路径的操作细节与实用价值。

为什么需要自定义问题子类型与属性？

在标准配置中，Autodesk 的 Issue 模块通常仅提供“一般问题”、“安全观察”等有限类别，且每个问题仅包含标题、描述、指派对象等基础字段。但在实际工程项目中，团队可能需要区分“土建钢筋绑扎偏差”、“机电管道碰撞”、“安全防护缺失”等数十种子类型，每种类型还需绑定特定的优先级、责任人、施工阶段或验收状态。若依赖手动调整，不仅耗时且容易出错。通过 API 自动化创建子类型与自定义字段，能显著提升数据标准化水平，为后续的报表分析、自动化通知甚至 AI 辅助决策奠定基础。

核心API概览

Autodesk 提供了一套基于 RESTful 架构的 Data Management API 与 Issue API（要求版本为 v2+）。创建问题子类型和自定义属性主要涉及以下端点：

问题子类型管理：通常通过 POST /issues/v2/containers/:container_id/issue-subtypes 实现，其中容器 ID 对应项目在 ACC 或 BIM 360 中的唯一标识。
自定义属性定义：使用 POST /issues/v2/containers/:container_id/attributes 创建针对特定子类型或全局的附加字段，支持文本、数字、日期、列表、布尔等数据类型。
属性值与子类型的关联：还可通过 PATCH 请求将自定义属性绑定到特定子类型上，实现字段的动态显示与填充。

所有请求均需携带由 OAuth 2.0 认证获取的 Bearer Token，并确保应用拥有对目标项目的 issues:write 权限。

实战操作步骤

第一步：获取项目容器ID

首先，通过 GET /projects/v1/hubs/:hub_id/projects 列举用户下的所有项目，从返回的 JSON 中提取 project_id，并与数据中心 ID 组合为容器 ID。例如：urn:adsk.construction:container:US:12345678-xxxx。

第二步：创建问题子类型

向指定容器发送 POST 请求，Body 示例：

{
  "name": "结构缺陷-混凝土裂缝",
  "description": "用于记录混凝土表面或深层裂缝问题",
  "color": "#FF5733"
}

成功后将返回包含该子类型唯一 ID（subtypeId）的响应，可在后续关联中使用。

第三步：定义自定义属性

若需为上述子类型添加“裂缝宽度（mm）”字段，可调用创建属性接口：

{
  "name": "裂缝宽度",
  "dataType": "number",
  "unit": "mm",
  "isRequired": false,
  "defaultValue": null
}

系统会返回属性 ID（attributeId）。类似地，还可创建多项下拉列表等复杂类型。

第四步：将属性绑定到子类型

使用 POST /issues/v2/containers/:container_id/issue-subtypes/:subtypeId/attributes 将上一步的属性与该子类型关联。此后，用户在创建该子类型的问题时，系统将自动显示“裂缝宽度”输入框。

第五步：通过API创建含自定义属性的问题

最后，当创建具体 Issue 时，在请求体中的 attributes 字段内传入属性 ID 与对应值即可。

典型应用场景

质量巡检自动化：质检员在现场使用移动端拍照上报“混凝土裂缝”问题时，可直接按预设的下拉框选择裂缝等级（例如：0.2mm/0.5mm/1.0mm），数据自动记录并推送至BIM模型关联。
安全合规报告：通过自定义属性捕捉“违规类型”、“处罚措施”等字段，每周自动生成统计图表，供管理层审查趋势。
多专业协同：为机电、装修、土建各自创建独立的子类型与属性，防止字段混淆，同时支持交叉引用。

注意事项与最佳实践

权限控制：仅在项目管理员或开发者模式下可操作属性定义，普通成员无法修改。
命名规范：建议使用英文或拼音+中文的组合（如 crack_width）作为属性标识符，便于后续脚本处理。
性能考量：每个项目最多可创建 100 个子类型和 200 个自定义属性，请合理规划。
版本兼容：Autodesk 于 2024 年 9 月更新了 Issue API v3，新增了“属性组”功能，建议优先使用新版接口。

展望

随着 Autodesk 平台向“可扩展生态”演进，API 已成为企业实现数字化转型的利器。通过自定义问题子类型与属性，项目团队不仅能摆脱固定模板的束缚，更能将现场数据与 ERP、AI 分析系统无缝对接。未来，结合 Autodesk 的 Forge 平台与低代码工具，非编程人员也可能通过拖拽式界面完成类似配置——但掌握 API 的核心逻辑，始终是深度定制的基石。

对于正在寻求提升项目数据治理能力的团队来说，现在正是动手尝试的最佳时机。从一段简单的 API 调用开始，你将发现 Autodesk 的世界远比你想象的更加开放与强大。