跳到內容

跑工作流

開始一次工作流、查它走到哪、拿輸出欄位、取消。同一個 Idempotency-Key 只會開始一次,重送不會重複做。

工作流有固定的輸入與輸出欄位,所以適合接進系統的流程。你們的系統送輸入,工作流照步驟做完,再交回輸出欄位。

你們的系統開始一次工作流、收到結果示意圖
開始一次,工作流照步驟做。做完時回呼,或用查詢拿到結果。

開始一次

POST /api/v1/workflows/{id}/runs

{ "inputs": { "po_no": "PO-0042", "amount": 82000 } }
  • 只收工作流「開始」宣告過的輸入欄位,其他欄位會被略過。
  • 串接設了 工作流的固定輸入 的欄位,一律用固定值。你們送的值會被換掉。回應裡的 inputs 是實際用的值。
  • 缺必填欄位時回 400 bad_request,訊息寫出缺哪一個。
  • 新開始的回 202,內容跟查詢一樣。
  • 串接的 能開始的工作流 沒有打開這個工作流時,回 404。我們不說它存不存在。

同一個請求不重複開始

在標頭帶 Idempotency-Key,例如你們的單號。同一個串接、同一個鍵只開始一次。再送一次會回 200 和同一次的內容。網路斷掉時,放心重送就好。

查詢

GET /api/v1/workflow-runs/{id}

{
  "id": "3f2c…",
  "workflow": { "id": "…", "name": "採購核准" },
  "run": 12,
  "status": "waiting",
  "inputs": { "po_no": "PO-0042", "amount": 82000 },
  "outputs": null,
  "error": null,
  "waiting": [{ "id": "9b1e…", "kind": "gate", "title": "核准採購單?", "actions": ["approve", "deny"] }],
  "created_at": "…",
  "finished_at": null
}
status 意思
running 正在做
waiting 在等決定。waiting 列出等你們決定的事
succeeded 做完,outputs 是輸出欄位
failed 沒做完,error 寫原因
cancelled 取消了

只查得到這個串接開始的那幾次。

取消

POST /api/v1/workflow-runs/{id}/cancel

還在 running 或 waiting 的才能取消。已經結束的回 409 conflict。

通知等待中的那一次

工作流裡的「等待」步驟可以設成 等外部系統通知。走到這一步就停下來,等你們的系統通知:

POST /api/v1/workflow-runs/{id}/signal

{ "data": { "shipped": true, "tracking_no": "TW123" } }
  • 這一步的輸出是 signaled(有沒有收到通知)與 data(你們送的資料)。後面的步驟可以用它們。
  • 步驟上有設最多等幾分鐘時,時間到了沒收到通知,signaled 是 false,照樣往下走。
  • 沒有在等通知的那一次,回 409 conflict。

相關頁

本頁對應 v0.168.0