如何通过ACC的POST issues API端点添加带定位图钉的问题位置？

要通过API在关联文档上生成高亮定位图钉，仅关联文档ID是不够的，需要在placement数组中传入视图ID和精确的坐标参数，以下是具体方案：

核心配置要点 #

• 放弃单独使用linkedDocuments，改用完整的placement对象定义定位信息
• 必须包含viewableId（对应文档的具体视图，如2D图纸页、3D视图）
• 提供视图坐标系下的精确x/y/z坐标（2D场景可忽略z值）

正确的请求体示例 #

{
  "title": "墙面开裂问题",
  "description": "文档指定位置的定位问题",
  "containerId": "b.xxxxxx",
  "placement": [
    {
      "documentId": "d.xxxxxx",
      "viewableId": "urn:adsk.viewing:fs.file:xxxxxx/contents/2D%20View",
      "location": {
        "x": 156.2,
        "y": 320.8,
        "zoom": 1.5
      },
      "type": "2d"
    }
  ],
  "status": "open"
}

关键注意事项 #

1. 获取有效viewableId：通过GET /data/v1/projects/{projectId}/documents/{documentId}/viewables接口获取目标文档的所有可视图ID，选择需要添加定位的视图
2. 坐标匹配视图坐标系：坐标需对应所选视图的本地坐标系，可通过手动添加图钉后，调用GET /issues/{issueId}接口查看已存在的定位坐标作为参考
3. 权限验证：确保请求携带的token拥有data:write权限，否则无法写入定位信息
4. 避免参数冲突：不要同时在请求中包含linkedDocuments和placement，优先使用placement定义带定位的关联

按照上述配置提交请求后，关联文档的指定位置会显示高亮的定位图钉，效果与手动添加一致。

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