跳到主要内容

API v1

v1 的资源直接挂在客户端上：client.projects、client.workItems、client.cycles，等等。每一个工作区级 别的调用都先传工作区 slug，然后是 URL 中包含的项目 id（如果有）。和 v2 不同，这里的 project 是项目的 UUID，并且较早的类把删除方法拼作 delete 或 del（以你编辑器显示的方法列表为准）。

import { PlaneClient } from "@hoyasumii/plane";

const client = new PlaneClient({ apiKey: "your-api-key" });

const projects = await client.projects.list("workspace-slug");

const project = await client.projects.create("workspace-slug", {
  name: "My Project",
  description: "A new project",
});

const item = await client.workItems.create("workspace-slug", project.id, { name: "First task" });
await client.workItems.comments.create("workspace-slug", project.id, item.id, { comment_html: "<p>Hello</p>" });

// 用一个人类可读的键，在整个工作区范围内查找一个工作项。
const byKey = await client.workItems.retrieveByIdentifier("workspace-slug", "ENG-12");

资源​

  • Projects：项目管理与组织
  • WorkItems：工作项与任务管理，具有完整的 CRUD 操作
  • WorkItemTypes：自定义工作项类型的定义与管理
  • WorkItemProperties：工作项的自定义属性
  • Labels：工作项分类与标签管理
  • States：工作流状态管理
  • Users：用户管理与资料
  • Roles：工作区和项目角色定义（只读）
  • Estimates：项目估算与估算点数
  • Modules：功能组织与模块管理
  • Cycles：迭代周期管理
  • Customers：客户管理与操作
  • Pages：工作区和项目页面管理
  • Links：工作项链接与关联关系
  • Workspace：工作区级别的操作
  • Epics：史诗（Epic）管理与组织
  • Intake：接收表单与请求管理
  • Stickies：便签管理
  • Teamspaces：团队空间管理
  • Milestones：里程碑跟踪与管理
  • Initiatives：计划（Initiative）管理
  • WorkspaceTemplates：工作区级别的工作项、项目和页面模板
  • WorkspaceWorkItemTypes：带属性关联的工作区级别工作项类型管理
  • WorkspaceWorkItemProperties：带选项的工作区级别自定义属性管理
  • WorkspaceProjectLabels：工作区级别的项目标签管理
  • WorkspaceProjectStates：工作区级别的项目状态管理
  • WorkItemRelationDefinitions：自定义工作项关系类型定义
  • Releases：带标签（tags）、标签（labels）、条目标签、变更日志、评论、链接和工作项的发布管理
  • Collections：对工作区页面进行分组的文件夹，带成员和页面管理
  • AgentRuns：AI 代理运行的编排与活动跟踪
  • Workflows：带状态关联、转换、转换钩子、活动和工作项审批的项目工作流管理
  • ProjectTemplates：按项目划分的工作项和页面模板管理
  • Features：工作区和项目功能管理
  • WorkspaceStates：工作区治理下的工作区级别（目录）工作项状态——双模式读取，仅受治理的写入
  • WorkspaceWorkflows：工作区治理下的工作区级别工作流目录，带链条（状态）、转换、使用情况、活动和转换钩子
  • WorkItemTypeGovernance：管理一个工作区级别的工作项类型可以使用哪些工作流（any/constrained/required 模式），带按项目的固定设置以及项目侧的选取/回退预览接口
  • Instance：来自 GET /api/instances/ 的实例配置与元数据（版本、版次、认证提供方、SMTP、上传限制）

子资源挂在它们各自的父资源下：workItems.comments、workItems.attachments、workItems.activities、 workItems.relations、workItems.workLogs、customers.properties、customers.requests、 teamspaces.members、teamspaces.projects、initiatives.labels、initiatives.projects、 initiatives.epics、agentRuns.activities、workItemProperties.options、workItemProperties.values， 等等。

实例信息​

const info = await client.instance.retrieve();
console.log(info.instance.current_version, info.config.is_smtp_configured);

下载附件​

workItems.attachments.download 会解析一个附件的签名 URL 并下载它，而不会把 API 密钥发送给存储主机。 传入 maxBytes 之后，更大的文件会被拒绝，并抛出 AttachmentTooLargeError：如果存储提前公布了它的 Content-Length，就会提前拒绝；否则会在响应体一旦超过这个上限时立刻拒绝。

import { AttachmentTooLargeError } from "@hoyasumii/plane";

try {
  const { data, contentType } = await client.workItems.attachments.download("acme", projectId, itemId, "asset-1", {
    maxBytes: 20 * 1024 * 1024,
  });
  console.log(contentType, data.length);
} catch (error) {
  if (error instanceof AttachmentTooLargeError) console.log("too large");
  else throw error;
}

错误​

一次失败的 v1 请求会抛出 HttpError，带有状态码、响应体和响应头（全部小写，所以 429 时可以用 headers["retry-after"]）。完整的层级结构参见 错误。