Convilyn 使用手冊

API 金鑰

API 金鑰讓另一個應用程式——Ainalyn 桌面應用程式、命令列，或你自己的整合——能以你的 Convilyn 帳號身分執行操作。你可以在網頁版的 Settings → API，或完整的 API 主控台中管理金鑰。

API 金鑰的用途

金鑰會驗證代表你發出的呼叫，讓你在瀏覽器之外也能使用 Convilyn：

  • Ainalyn 桌面應用程式——貼上一組金鑰即可把應用程式連上你的帳號（見 Convilyn 與 Ainalyn）。
  • 命令列——convilyn CLI 會從你的環境變數讀取金鑰。
  • 你自己的整合——任何呼叫 Convilyn API 的腳本或服務。

金鑰會代表你執行操作，所以請把它當成密碼看待。 任何持有它的人都能花掉你的點數。

建立金鑰

  1. 開啟 Settings → API（請先登入）。
  2. 選擇 Create key，並取一個你日後認得出來的名稱——例如「My desktop」。
  3. 選擇金鑰的範圍 (scopes)，並可選擇性設定到期日 (expiry)（兩者皆於下方說明）。預設為完整存取、永不到期，適合個人金鑰。
  4. 複製完整金鑰。它以 ck_ 開頭，而且只會顯示一次——請妥善保存，因為你之後將無法再次看到它。

範圍

範圍會限制金鑰可執行的操作：

  • 讀取 (Read)——唯讀存取：列出工作流程、查詢狀態、下載結果、檢視使用量。
  • 寫入 (Write)——執行會消耗點數的工作流程。

新金鑰預設為完整存取（讀取＋寫入）。若金鑰只用於報表或唯讀自動化，可只選 讀取——它無法消耗點數，因此即使外洩也無法產生費用。

到期

可為金鑰設定選擇性的到期日。一旦超過，金鑰會自動停止驗證。留空表示金鑰永不到期。

使用金鑰

把金鑰以 Bearer token 形式放在 Authorization 標頭中送出：

curl https://convilyn.corenovus.com/api/v1/workflows/catalog \
  -H "Authorization: Bearer ck_your_key"

把 ck_your_key 換成你建立的金鑰。完整的程式化介面——Python SDK、convilyn CLI 與 REST API——請見開發者文件。

管理你的金鑰

你可以在 Settings → API 中：

  • 輪替金鑰——發給一組新的密鑰，同時讓舊金鑰在短暫的寬限期內（24 小時）繼續運作，方便你無中斷地切換到新金鑰。寬限期過後，舊金鑰會自動停用。
  • 撤銷單一金鑰——它會立即停止運作，且無法復原。
  • 全部撤銷——當你懷疑金鑰外洩時的事件應變控制項。

監看使用情況

系統會追蹤每組金鑰的活動，方便你掌握費用與狀態：

  • 使用量——每組金鑰的請求數、錯誤數與已用點數，可選預設或自訂時間範圍。
  • 請求記錄——檢視近期的 API 呼叫（方法、端點、狀態、耗時、費用）。
  • 速率限制——各端點類別對每組金鑰強制執行的請求上限。

方案與供應狀態

API 存取是 Business 方案的功能，目前向所有已登入使用者開放。以金鑰發出的雲端呼叫，與網頁版共用同一份點數餘額。

Webhooks

註冊一個 HTTPS 端點，Convilyn 會在工作完成時對它發出 POST，讓你的整合無需輪詢即可對結果做出反應。

  • 事件——job.completed 與 job.failed。
  • 簽章——每次傳遞都帶有 X-Convilyn-Signature 標頭（對內容做 HMAC-SHA256），讓你的接收端能驗證它確實來自 Convilyn。簽章密鑰只會在你建立 hook 時顯示一次。
  • 可靠——傳遞失敗會以指數退避重試，多次失敗後移入死信佇列 (dead-letter queue)。傳遞與你的工作彼此隔離，因此接收端緩慢或失敗都不會拖慢工作本身。
  • 可測試——可對 hook 發送一則範例事件，在正式倚賴前先驗證你的端點。

在 API 主控台中建立與管理 webhooks——顯示密鑰、啟用或停用 hook，或發送測試事件。

API 主控台

若需完整的管理介面，請使用獨立的 API 主控台——以你的 Convilyn 帳號登入。它把上述所有功能集中在一處，並提供更深入的檢視：

  • 金鑰——建立、輪替、撤銷；設定範圍與到期日。
  • 使用量——可用預設或自訂時間範圍的分析，並含每組金鑰的細分。
  • 請求記錄——逐頁瀏覽近期的 API 呼叫。
  • 速率限制——各端點類別對每組金鑰的上限。
  • Webhooks——註冊、測試與管理對外的 webhooks。

網頁版的 Settings → API 是核心功能的快速檢視（金鑰、使用量與桌面應用程式）；主控台則是完整體驗。

接下來