API / SDK / developer guide
Flow definition
| 目標讀者 TA | 流程作者 |
|---|---|
| 官方文件能力 | 定義協調單元及任務。 |
| 輸入 → 輸出 | 流程定義 → 可執行版本化流程。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 語法有效不代表引用外掛或服務可用。 |
| 本站建議驗證 | 驗證定義並解析所有任務相依項。 |
工作流程自動化 · API / SDK
Kestra API
Kestra
透過官方 API 資源串接工作流程協調。
KESTRA / DEVELOPER FIELD GUIDE
選對接口，定義可驗證的結果。
公司／專案背景、十個技術入口，以及每份引用的實作分析。
2026-10-08 · 串接尚未實測
公司／專案背景全貌
依官方公司或專案自述撰寫的原創概要；完整原文請見來源。
| 公司及專案 | Kestra 開發宣告式協調平台，涵蓋資料管線、基礎設施、應用及 AI 流程。 |
|---|---|
| 工程重點 | About 頁面強調品質、協作、使用者回饋及透明度。 |
| 版本選擇 | API 文件區分開源及 Enterprise 版本；實作前須對應部署能力。 |
| 適用角色 | 進行 AI 供應商初選的採購、合作夥伴與產品負責人。 |
|---|---|
| 本站評估 | 用定位與公司背景判斷初步適配度；另行取得專案部署、支援與商務條件。 |
已核對官方來源；未執行真實 API、推論或效能測試。預期結果為建議內部契約。
十項技術入口比較
依開發任務選出的十個有文件技術入口；不是十套獨立 SDK 或官方排名。
| 接口 | 用途與 TA |
|---|---|
| 01 · Flow definitionAPI / SDK / developer guide | 定義協調單元及任務。流程作者 |
| 02 · ExecutionsAPI / SDK / developer guide | 啟動及觀察個別流程執行。流程協調整合者 |
| 03 · Workflow inputsAPI / SDK / developer guide | 宣告及驗證流程參數。契約設計者 |
| 04 · Workflow outputsAPI / SDK / developer guide | 在任務間傳遞結果並提供流程輸出。管線工程師 |
| 05 · Webhook triggerAPI / SDK / developer guide | 透過 HTTP 事件啟動流程。事件整合團隊 |
| 06 · Error handlingAPI / SDK / developer guide | 定義流程內失敗處理。可靠性負責人 |
| 07 · Task retriesAPI / SDK / developer guide | 依宣告策略重試暫時錯誤。整合工程師 |
| 08 · Task timeoutAPI / SDK / developer guide | 限制任務執行時間。營運團隊 |
| 09 · Flow concurrencyAPI / SDK / developer guide | 限制同時執行數量。容量規劃者 |
| 10 · Task plugin developmentAPI / SDK / developer guide | 實作自訂任務行為。外掛工程師 |
逐份文件分析
能力摘要依據官方文件；限制與建議測試為本站工程評估。
API / SDK / developer guide
Executions
| 目標讀者 TA | 流程協調整合者 |
|---|---|
| 官方文件能力 | 啟動及觀察個別流程執行。 |
| 輸入 → 輸出 | 流程及輸入 → 執行 ID 及生命週期狀態。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 建立執行不等於終態成功。 |
| 本站建議驗證 | 將任務狀態與執行終態結果關聯。 |
API / SDK / developer guide
Workflow inputs
| 目標讀者 TA | 契約設計者 |
|---|---|
| 官方文件能力 | 宣告及驗證流程參數。 |
| 輸入 → 輸出 | 提供值 → 型別流程輸入。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 缺少必要值及錯誤型別不可靜默變預設值。 |
| 本站建議驗證 | 測試缺少、格式錯誤及邊界輸入。 |
API / SDK / developer guide
Workflow outputs
| 目標讀者 TA | 管線工程師 |
|---|---|
| 官方文件能力 | 在任務間傳遞結果並提供流程輸出。 |
| 輸入 → 輸出 | 任務結果 → 可引用輸出值。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 任務可能在產生輸出前失敗。 |
| 本站建議驗證 | 驗證缺少輸出處理及型別一致性。 |
API / SDK / developer guide
Webhook trigger
| 目標讀者 TA | 事件整合團隊 |
|---|---|
| 官方文件能力 | 透過 HTTP 事件啟動流程。 |
| 輸入 → 輸出 | 授權 webhook 事件 → 執行。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 事件發送者重試可能產生重複業務操作。 |
| 本站建議驗證 | 定義去重鍵並驗證重複事件行為。 |
API / SDK / developer guide
Error handling
| 目標讀者 TA | 可靠性負責人 |
|---|---|
| 官方文件能力 | 定義流程內失敗處理。 |
| 輸入 → 輸出 | 任務失敗 → 設定錯誤路徑。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 清理成功不表示原工作成功。 |
| 本站建議驗證 | 注入失敗並保留原失敗結果。 |
API / SDK / developer guide
Task retries
| 目標讀者 TA | 整合工程師 |
|---|---|
| 官方文件能力 | 依宣告策略重試暫時錯誤。 |
| 輸入 → 輸出 | 失敗嘗試 → 有限後續嘗試。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 副作用需要冪等性或對帳。 |
| 本站建議驗證 | 驗證嘗試限制及無重複外部變更。 |
API / SDK / developer guide
Task timeout
| 目標讀者 TA | 營運團隊 |
|---|---|
| 官方文件能力 | 限制任務執行時間。 |
| 輸入 → 輸出 | 超時任務 → 設定逾時行為。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 流程逾時不一定撤回外部副作用。 |
| 本站建議驗證 | 檢查取消行為並核對下游狀態。 |
API / SDK / developer guide
Flow concurrency
| 目標讀者 TA | 容量規劃者 |
|---|---|
| 官方文件能力 | 限制同時執行數量。 |
| 輸入 → 輸出 | 進入執行 → 設定佇列／限制處理。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 並行設定影響等待時間及下游容量。 |
| 本站建議驗證 | 提交有限突發工作並驗證宣告溢出策略。 |
API / SDK / developer guide
Task plugin development
| 目標讀者 TA | 外掛工程師 |
|---|---|
| 官方文件能力 | 實作自訂任務行為。 |
| 輸入 → 輸出 | 任務輸入及 context → 任務輸出。 |
| 執行環境 | 固定 Kestra 伺服器、外掛及設定的任務執行器 |
| 本站選型評估 | 外掛 API 及伺服器相容性须共同固定。 |
| 本站建議驗證 | 測試有效輸入、例外及取消行為。 |
API reference
| TA | API 整合團隊 |
|---|---|
| 本站驗證建議 | 使用符合選定版本、伺服器版本與認證模式的文件。 |
04 / INPUT · EXPECTED OUTPUT · ACCEPTANCE
實作前先看懂預期結果
建議執行收據，不是 Kestra 原生 API 回應。未執行流程、任務、webhook 或外部服務。
示意契約 · 未呼叫 API 或執行模型 · 不是供應商實測輸出
執行成功
| 輸入 | 有效輸入及所有必要任務完成。 |
|---|---|
| 預期結果 | ok 與終態執行狀態及宣告輸出。 |
| 驗收條件 | 確認每個必要相依項完成且輸出存在。 |
空工作量
| 輸入 | 有效輸入清單無合格項目。 |
|---|---|
| 預期結果 | 若流程定義空工作有效，則 ok 且 processed_count: 0。 |
| 驗收條件 | 不建立虛構外部操作。 |
執行排隊
| 輸入 | 流程並行容量已滿。 |
|---|---|
| 預期結果 | 依設定策略 pending／queued，尚未完成。 |
| 驗收條件 | 呈現等待狀態並限制約定最長等待。 |
重試後任務失敗
| 輸入 | 暫時失敗持續超過重試上限。 |
|---|---|
| 預期結果 | error 與任務、執行識別；保留失敗狀態。 |
| 驗收條件 | 驗證重試次數並核對先前外部副作用。 |
將預期結果對應至你的應用
整合後將實際 SDK 或服務回應對應至此建議內部契約。下列識別碼與數值均為示意；不含憑證或真實請求。
預期輸出 JSON — 示意，非實測 · KestraAPI-expected-results.json
{
"schema_version": "1.0.0",
"example": true,
"provider": "Kestra",
"status": "ok",
"input_id": "sample-001",
"data": {
"execution_id": "example-execution",
"flow_id": "example-flow",
"flow_revision": 1,
"execution_state": "SUCCESS",
"outputs": {
"processed_count": 3
}
},
"error": null,
"verification": "illustrative-only;not-provider-response"
}| 結果解讀 | 傳輸或執行成功不代表模型準確。有效空結果須與操作失敗分開。 |
|---|---|
| 可重現性 | 記錄模型、環境、設定與輸入識別；代表性測試前約定品質及延遲條件。不宣稱已實測效能。 |
| 操作範圍 | 建議執行收據，不是 Kestra 原生 API 回應。未執行流程、任務、webhook 或外部服務。 |
開發評估
證據擷取工作流程
開發構想規格・串接尚未實測
接口能力依據官方文件或程式庫；以下產品方向、輸入、交付與驗收條件則是我們的開發評估。
可先做小原型
確認存取後，用少量真實樣本測試一個有文件的操作。此為開發判斷，不是交期估算。
- 原型輸入規劃
- 一筆範例事件、經授權系統與一個明確流程轉換。
- 原型交付規劃
- 單一流程的可見工作狀態與操作紀錄。
- 驗收條件
- 重送事件不得重複建立工作；上游不可用時需保留等待或失敗狀態。
- 依賴條件
- 執行環境存取、流程權限與已核對的通知或寫入目的地。
開發順序
- 確認 Kestra API 的存取、授權與支援版本。
- 準備上述樣本，針對「證據擷取工作流程」先實作一個有官方文件的操作。
- 整理輸出時保留來源、時間與錯誤狀態，並保留供應商回應供審核。
- 通過驗收條件後，再估算擴展投入與客戶交付。
如何驗證需求
記錄產品瀏覽、官方文件點擊、規格下載與技術 Hub 點擊。這些是事件次數，不等於獨立人數或已完成串接。
本次可行性評估依實作條件判斷；尚未給定流量排名或交期承諾。