17. 整合 API 與 API 金鑰

整合 API 可以讓你自己的程式、試算表或腳本以機器方式讀取專案資料：專案清單、電纜與材料清單、配電箱的迴路表與端子清單、數量統計以及圖紙包的組成。此 API 唯讀：不會修改圖紙與專案。

誰可以取得 API 金鑰

API 金鑰由營運方依帳號啟用。帳號取得權限後，個人資料頁面會顯示 API 金鑰卡片；沒有權限時該卡片不會顯示。一個帳號同時最多可有 5 把有效金鑰。

金鑰看到的專案與你自己看到的相同：你自己的專案，以及依請求與你共享的專案。對於共享專案，只有在共享設定允許匯出時，才會回傳其清單與統計。

建立金鑰

在個人資料頁面的 API 金鑰卡片上，按一下新增金鑰按鈕。
為金鑰取一個名稱（例如將要使用它的程式名稱）。
選擇權限範圍：讀取專案提供專案清單與專案資料，讀取文件提供清單、統計與圖紙包。只選擇程式真正需要的權限。
選擇有效期限：30、90 或 365 天。過期的金鑰不再有效，請改為建立新的金鑰。
輸入你目前的密碼（沒有密碼的帳號需要重新登入）。建立第一把金鑰時，請接受 API 使用條款。

建立之後，金鑰只會顯示一次：請複製並保存在安全的地方。之後清單中只會顯示它的前綴（avk_…），以及建立與到期日期、最近一次使用和呼叫次數。我們也會就新金鑰寄送電子郵件通知（不含金鑰本身）。

撤銷金鑰

按一下卡片上金鑰旁邊的撤銷按鈕，該金鑰會立即失效；此操作無法復原。當你不再使用某把金鑰、停用了使用它的程式，或懷疑它已外洩時，請撤銷該金鑰。

安全建議

把金鑰當作密碼來對待：任何知道它的人都可以在其權限範圍內讀取你的專案。
請存放在機密儲存區（密碼管理器、伺服器的環境變數或 CI 的機密變數），而不是原始碼中：不要提交到 git 儲存庫，也不要放進共享的試算表或電子郵件。
不要在瀏覽器中執行的程式碼裡使用（網頁、瀏覽器擴充功能）：在那裡任何人都可以讀取它。金鑰應放在伺服器、腳本或桌面程式中。
讓每個程式都有自己的金鑰，權限範圍盡量狹窄，有效期限盡量短；這樣撤銷一把金鑰不會讓其他程式停止運作。

在程式中使用

金鑰以 Bearer 權杖的形式放在請求標頭中傳送：Authorization: Bearer avk_…。端點位於 /api/v1/ 之下（例如 GET /api/v1/projects），回應為 JSON。OpenAPI 格式的完整說明可在 /api/v1/openapi.json 取得；大多數開發工具都可以匯入它。

呼叫次數依金鑰與依帳號分別限制（預設每分鐘 60 次，每天 10,000 次）；超過限制時伺服器會回應 429，此時請稍等片刻。透過網站登入（Cookie）不會開放 API，金鑰也無法用來登入網頁介面。