跳到主要内容

云效连接器

云效连接器按工作项的更新时间把云效中心版项目同步到 AntTodo。同步后的待办会挂到指定团队标签下；在 AntTodo 中完成待办时，会把云效工作项状态回写为接入时选择的完成状态。

团队空间的所有者和管理员可在 设置 → 团队配置 → 连接器 中接入、启停和手动同步。普通成员可以查看已接入连接器，但不能新增、启停或移除。

当前仅支持云效中心版（devops.aliyun.com）。若只需把单条云效链接变成待办、而不做定时同步，请改用 设置 → 快速创建 中的云效创建。

1. 申请云效个人访问令牌​

连接器使用云效个人访问令牌调用 OpenAPI。令牌权限应遵循最小授权：只需开通下方列出的「项目协作」权限，其他分类保持 0 个权限即可。

  1. 登录云效工作台。
  2. 点击右上角头像，打开 个人设置 → 个人访问令牌。
  3. 点击 新建访问令牌，填写名称并设置到期时间。令牌到期后同步会失败，需要重新生成并在 AntTodo 中更新。
  4. 在 项目协作 中按下面表格勾选权限，其余分类（组织管理、代码管理、流水线、制品仓库、应用交付）保持「已选权限: 0 个」。
  5. 点击 新建，立即复制令牌。云效只在创建时展示一次明文，之后无法再查看。
权限级别用途
项目只读列出组织下可见项目
工作项读写拉取工作项；在 AntTodo 完成待办时回写云效状态
工作项类型只读读取项目中的工作项类型
工作项工作流只读读取工作流，用于选择完成状态
工作项类型字段配置只读读取计划开始 / 截止等字段
工作项附件只读读取并转存工作项描述中的图片
工作项相关项只读读取工作项关联信息

云效个人访问令牌：项目协作下，项目为只读，工作项为读写，工作项类型、工作项工作流、工作项类型字段配置、工作项附件和工作项相关项为只读

令牌权限与账号权限同时生效

个人访问令牌只能访问令牌申请人自己可见的项目和工作项，并且还受令牌 API 权限范围限制。请使用对目标项目有权限的账号申请令牌，不要把令牌发给无关人员。AntTodo 会把令牌写入服务端保险库，界面只保留脱敏提示。

云效官方参考：

2. 创建云效连接器​

接入前请准备：

  • 上一步申请的个人访问令牌
  • 云效组织 ID：点击右上角头像 → 管理后台 → 基本信息，复制组织 ID。也可从地址栏 https://devops.aliyun.com/organization/【组织ID】 中读取
  • 至少一个当前账号可编辑的团队标签，用于存放同步过来的待办。没有可编辑标签时，「接入」按钮不可用

然后在 AntTodo 中完成接入：

  1. 使用团队空间所有者或管理员账号进入 设置 → 团队配置 → 连接器。
  2. 在 连接器市场 → 研发工具 中找到「云效」，点击 接入。
  3. 填写 同步任务名、组织 ID 和 个人令牌，点击 验证组织与令牌。验证成功后会加载该组织下可见的项目。
  4. 依次选择 项目、工作项类型、云效完成状态。完成状态用于：云效工作项已是该状态时，AntTodo 待办显示为已完成；在 AntTodo 中勾选完成时，回写云效到该状态。
  5. 选择 同步到该标签下 和 同步间隔（5 分钟、30 分钟、1 小时、3 小时或 24 小时）。
  6. 过滤条件可保持空数组 []。若需缩小范围，可填写云效官方 conditionGroups 对象或条件数组；系统会为每一组自动追加 gmtModified BETWEEN 时间窗。
  7. 点击 保存并接入。个人令牌校验通过后，首次同步会立即排队。

同一团队空间可以接入多个云效连接器，例如分别同步不同项目或不同类型的工作项。

3. 自动同步与手动同步​

接入并启用后，连接器会按所选间隔自动拉取更新；接入时首次同步已排队，无需再等一个完整间隔。

需要立刻拉取时，打开 已接入，在对应连接器上点击 同步。仅启用中的连接器可以手动同步。

在已接入卡片中还可以：

  • 查看项目 / 类型、目标标签、同步间隔、完成状态、最近同步时间
  • 停用 / 启用 定时同步
  • 更新个人令牌（令牌过期或轮换后使用）
  • 移除 连接器。若该连接器还有未删除的待办（包含回收站），系统会拒绝移除，避免留下无来源的外部任务

4. 机制与限制​

同步按云效工作项的 更新时间（gmtModified）降序查询，因此每次都会先处理最近改动过的工作项。

场景行为
首次同步从当前时刻往回拉取，最多处理 100 条符合条件的工作项，然后记下本次同步开始时的时间作为游标
后续同步从上次保存的游标继续。已跑完上一时间窗时，只拉取游标之后新更新的工作项；若上一轮因分页未完成，则从保存的页码和偏移接着拉

因此：首次接入不会把项目里的全部历史工作项都同步进来，只覆盖最近更新的 100 条。更早且之后没有再更新的工作项不会自动补齐。若某次后续同步因数量较大未能一次跑完，游标会保留进度，下一轮（定时或手动）会接着同步。

其他限制：

  • 同步范围为所选项目、工作项类型，以及可选过滤条件；不会同步其他类型。
  • 同步内容包括标题、描述、计划开始 / 截止时间，以及云效状态、负责人和原文链接（写入待办描述）。描述块会记录最后同步时间，云效地址以「跳转」链接呈现。云效富文本（含 htmlValue JSON）会转为 Markdown 后保存；已是 Markdown 的描述只规范换行，不会再转一遍。描述中的图片会尽量转存到 AntTodo。
  • 同步过来的待办带有「云效」标记。标题、描述、日期等内容只读，不会从 AntTodo 写回云效。有编辑权限的成员可以把待办移到回收站、恢复，以及增删本地标签；这些整理结果会在后续同步中保留。只有连接器创建者可以在 AntTodo 中将其勾选为完成，并回写云效状态。连接器目标标签会在每次同步时重新挂上。
  • 云效侧之后的标题、描述、截止时间和状态变更，会在后续同步中覆盖到 AntTodo。
  • 个人令牌过期、权限不足或账号看不到目标项目时，同步会失败。可在已接入详情中查看最近一次错误，更新令牌后重试。