跳至主要内容

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"]）。完整的層級結構參見 錯誤。