知识库

TAPD

以 Markdown 格式查看

TAPD 连接器用于把已批准 TAPD 项目空间中的需求、任务、缺陷和可选附件纳入艾维斯知识检索。它只读取管理员显式填写的项目空间 ID，不会扫描整个企业，也不提供 WPS 入口。

适用场景

场景建议
需求与缺陷问答按 TAPD 项目空间创建连接器，并启用需求、任务、缺陷。
项目复盘将需求描述、任务状态、缺陷描述和评论沉淀为检索上下文。
附件检索仅在附件内容已获批准且文件规模可控时启用。
多项目治理按业务线或客户拆分连接器，避免一个 API 账号覆盖过宽。
增量同步验证用边界时间附近的对象测试修改时间窗口，避免遗漏或重复。

当前索引内容

TAPD 连接器以一个或多个 workspace_id 作为范围。最多 100 个项目空间 ID，必须为正整数，不能重复。

TAPD 内容索引行为
需求启用包含需求后，索引需求标题、描述、状态、负责人、创建人、创建时间和更新时间。
任务启用包含任务后，索引任务标题、描述、状态、负责人、创建人、创建时间和更新时间。
缺陷启用包含缺陷后，索引缺陷标题、描述、状态、当前处理人、报告人、创建时间和更新时间。
附件启用包含附件后，连接器会读取已启用内容对象下的附件，并将可解析附件作为子文档。

至少需要启用需求、任务、缺陷中的一种。当前连接器不索引项目成员权限、迭代统计、工时、看板配置、报表、流程设置或企业下未列出的其他项目。

前置条件

  • 已准备 TAPD API 用户名和 API 密码。不要使用没有 API 权限的普通登录密码。
  • 已确认 API 账号能读取目标项目空间下需要索引的需求、任务、缺陷和附件接口。
  • 已整理目标项目空间 ID，例如 TAPD 项目 URL 中的数字空间 ID。
  • 已决定是否索引附件；附件会增加同步耗时、存储和解析失败概率。
  • 已规划艾维斯访问范围。只要连接器可见，用户就可能搜索到该连接器索引的全部内容。
  • 网络策略允许艾维斯后端访问 api.tapd.cn。

配置数据获取入口

配置数据获取方式
API 用户名 / API 密码在 TAPD 公司管理的开放平台配置中查看 api_user 与 api_password。可参考 TAPD 开放平台：API 配置指引。
项目空间 ID workspace_id在 TAPD 项目空间左上角项目名称处查看项目 ID，或调用 获取项目信息 验证。可先阅读 使用必读。
需求字段与可读性用目标 workspace_id 调用 获取需求 验证 API 账号是否能读取。
任务字段与可读性用目标 workspace_id 调用 获取任务 验证。
缺陷字段与可读性用目标 workspace_id 调用 获取缺陷 验证。

在艾维斯中配置

在管理后台打开连接器，选择 TAPD。先创建或选择 TAPD 凭据，再填写项目空间与内容类型。

字段填写方式说明
API 用户名TAPD 提供的 API 用户名用于访问 TAPD Open API。
API 密码TAPD API 密码保存后通常不会明文展示。
项目空间 ID每行一个正整数，例如 20000001只索引列出的项目空间，最多 100 个。
包含需求默认开启读取需求标题、描述和状态等字段。
包含任务默认开启读取任务标题、描述和状态等字段。
包含缺陷默认开启读取缺陷标题、描述和状态等字段。
包含附件默认开启读取已启用对象下的可解析附件。

建议先用一个测试项目空间和少量内容类型完成验证，再扩大范围。

同步行为

标准管理后台创建的 TAPD 连接器使用轮询索引，并支持 checkpoint 续跑。同步会按项目空间处理，每个空间内按已启用内容类型依次处理需求、任务和缺陷。

阶段同步细节
清单构建按页读取同步时间窗口内修改过的对象，并按修改时间和 ID 形成稳定顺序。
正文解析将 TAPD HTML 描述转换为可检索文本，同时保留状态、负责人和创建人等元数据。
附件附件作为父对象的子文档处理；单个对象最多处理 1000 个附件。
增量对象修改后会以稳定 ID 更新，不应产生重复文档。

权限边界

TAPD API 账号决定艾维斯能摄取哪些项目内容，但连接器不会把 TAPD 项目成员、角色、字段权限或单个对象权限同步到艾维斯。

艾维斯访问设置含义
私有群组只有选定艾维斯群组可搜索该连接器产生的全部文档。推荐用于项目、客户和研发数据。
公开所有可使用该知识范围的艾维斯用户都可能搜索到索引内容。仅适用于可公开给这些用户的项目。
自动同步权限TAPD 当前不支持此模式。

对于不同客户、项目组或保密等级，应使用不同 TAPD API 账号、连接器和艾维斯私有群组。

验证

  1. 用一个测试项目空间创建连接器，确认凭据和空间 ID 校验通过。
  2. 搜索一条已知需求、任务和缺陷的标题与描述关键词。
  3. 启用附件时，上传一个小型文本附件并确认可被检索。
  4. 修改一条测试对象，等待下一轮同步，确认搜索结果更新且没有重复文档。
  5. 搜索未列出的项目空间内容，确认不会返回结果。
  6. 使用群组内账号和群组外账号分别测试，确认艾维斯访问边界符合预期。

常见问题排查

现象优先检查项
认证失败API 用户名和 API 密码是否正确，账号是否仍有 API 权限。
项目空间校验失败workspace_id 是否为正整数，API 账号是否能读取该项目空间。
某类对象为空对应的需求、任务或缺陷开关是否开启，API 账号是否具备该接口权限。
附件没有进入索引是否开启包含附件，附件接口权限是否可用，文件类型和大小是否可解析。
增量结果缺失对象更新时间是否落在同步窗口内，是否需要重新运行完整同步进行对账。
搜索结果包含不该公开的项目调整艾维斯访问范围，或按项目/受众拆分连接器。

安全与维护建议

  • 使用专用 TAPD API 账号，不复用个人高权限账号。
  • 定期复核项目空间列表、内容类型、附件开关、API 账号负责人和艾维斯访问群组。
  • 附件体量较大时，先在测试环境测量解析耗时和失败率。
  • API 密码疑似泄露时，立即更换并更新艾维斯凭据。
  • 项目结束后，停用连接器或移除不再需要的项目空间 ID。

官方参考

相关页面