HTTPS API¶
這頁的用途¶
HTTPS API 任務讓工作流程 (Workflow) 呼叫外部的 REST API 或網路服務，把回應帶進後續步驟。常見情境：
- 串接第三方 SaaS（CRM、金流、分析平台）。
- 透過 Webhook 送通知（如 Slack、Teams）。
- 取得外部即時資料（天氣、匯率、股價）。
- 更新外部系統的記錄（工單、試算表、資料庫）。
開始前
一般呼叫不需前置資源。若要安全存放共用的驗證標頭，可建立一個 HTTP 類型的連結器 (Connector)，再於此選用。建立方式見 連結器資源頁。
操作步驟¶
-
新增一個 HTTPS API 任務節點，點選它開啟右側設定表單（如何新增請見 任務使用指南）。
-
在「名稱」填步驟名稱。
- 在「方法」選 HTTP 方法（GET、POST、PUT 等）。
- 視需要在「連結器」選一個 HTTP 連結器，套用其共用的驗證標頭。
- 在「網址」填目標端點（必須是
https://開頭）。 - 視需要在「參數」（查詢字串，欄名為「名稱／值」）與「主體」（請求內容，欄名為「鍵／值」）的表格按 逐列新增。若要整包從上一步的輸出帶入，把滑鼠移到欄位上、打開右側的「JSONPath」開關（見下方範例）；若只是想讓其中某幾個值動態帶入、其餘寫死，改開「JSON」開關手寫 JSON，並在動態取值的鍵名結尾加
.$。兩個開關互斥，一次只能開一個。 -
視需要展開「進階任務設定」，在「HTTP 標頭」鍵值表格逐列新增標頭。
-
設定「下一個狀態」，視需要填「附註」，再用「測試任務」按鈕（）試跑。
完整欄位說明¶
下表只列 HTTPS API 任務特有的欄位。名稱、附註、下一個狀態、輸入與輸出、錯誤處理等共用分區，請見 任務通用設定。
設定分頁（基本欄位）¶
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 方法 | 是 | GET | HTTP 請求方法，可選 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。 |
| 連結器 | 否 | 無 | 選一個 HTTP 類型的連結器，套用其共用的驗證標頭到每次請求。可清除、也可從輸入動態帶入。建立方式見 連結器資源頁。 |
| 網址 | 是 | https:// | 目標 API 端點，必須是 https:// 開頭的合法網址。要讓網址隨執行資料改變時，把滑鼠移到欄位上、打開右側的「JSONPath」開關，欄位會變成唯讀的路徑框——點這個框或它右側的 鉛筆鈕開啟「編輯參考路徑」對話框，在裡面填一個指向完整網址的路徑（例如 $.target_url）再按「儲存」，直接打字打不進去（見任務通用設定）；這個開關是「整個欄位換成一條路徑」；手冊把「把路徑直接串進字串中間」（如 https://api.example.com/users/$.user_id）列為要避免的寫法，見 變數與資料引用 › 要避免的常見錯誤（路徑寫法見 JSONPath 語法）。若只有網址尾端的一小段是動態的，改用下方的「參數」欄位，或先用 文字 (Text) 任務／程式碼 (Code) 任務 把完整網址組好再帶進來。 |
| 參數 | 否 | 空表格 | 附加在網址後方的查詢字串參數，常用於篩選、搜尋或分頁。是一張「名稱／值」表格（注意這欄叫「名稱」，不是「鍵」），按 逐列新增。這裡一填，這一步就只用填入的參數——上游步驟或工作流程輸入送進來的參數會被忽略；想改成完全由上游決定，就把這張表清空、改用「JSONPath」開關整包帶入。 |
| 主體 | 否 | 空表格 | 請求主體內容，適用 POST、PUT 等。是一張「鍵／值」表格，按 逐列新增。同樣地，這裡一填，這一步就只用填入的內容，不接受上游傳進來的主體。若整包主體要來自上一步的輸出（例如 $.user_update），把滑鼠移到欄位上、打開「JSONPath」開關，欄位會變成唯讀路徑框，點它或右側鉛筆鈕在「編輯參考路徑」對話框裡填 $.user_update。 |
進階任務設定（摺疊區塊）¶
展開設定分頁底部的「進階任務設定」可看到下列欄位：
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| HTTP 標頭 | 否 | 空表格 | 附加到請求的自訂 HTTP 標頭，例如內容類型或驗證。是一張「鍵／值」表格，按 逐列新增。若已指定連結器，會與連結器的標頭合併，同名時以此處任務設定為優先。需隱藏敏感資訊時建議改放在連結器。 |
敏感資訊放連結器
驗證金鑰、Token 等敏感標頭建議放在 HTTP 連結器中，不要直接填在 HTTP 標頭欄位（直接填會以明文儲存）。
執行設定（摺疊區塊）¶
「設定」分頁底部除「進階任務設定」外，還有一個「執行設定」摺疊區，內含上傳輸出至外部記憶體、即時輸出串流、錯誤時中止等所有任務共用的欄位，完整說明見 任務通用設定。
實際範例與預期結果¶
設定內容：
- 方法：
PUT - 連結器：選一個 HTTP 連結器（
Authorization之類的驗證標頭放在這裡，不要填在「HTTP 標頭」） - 網址：打開「JSONPath」開關，再點路徑框（或右側鉛筆鈕）在「編輯參考路徑」對話框填
$.target_url（整條網址由上一步準備好） - 參數：只有
id這個值要從輸入帶入，所以這一欄改開「JSON」開關（不是「JSONPath」，兩者互斥）填{ "id.$": "$.user_id" }（鍵名結尾的.$代表值是路徑；若填的是寫死的固定值，用預設的「名稱／值」表格逐列填即可） - HTTP 標頭（「鍵／值」表格一列）：鍵
Content-Type、值application/json - 主體：打開「JSONPath」開關，再點路徑框（或右側鉛筆鈕）在「編輯參考路徑」對話框填
$.user_update（整包主體從輸入帶入）
工作流程輸入：
{
"target_url": "https://api.example.com/v1/users",
"user_id": "12345",
"user_update": {
"name": "John Doe",
"status": "active"
}
}
測試輸出（API 回應放在 output）：
{
"errors": null,
"action_type": "https_api_action",
"output": {
"id": "12345",
"name": "John Doe",
"status": "active"
}
}
Note
輸出以後端實際回傳為準：API 回應放在 output，action_type 固定為 https_api_action。回應為 JSON 時 output 是物件或陣列，為純文字時是字串，二進位回應會以 [binary response, N bytes] 形式呈現。後續步驟可用 JSONPath 取值，例如 $.output.id。
下一步¶
- 用 程式碼 (Code) 任務 解析與重組 API 回應。
- 把回應交給 LLM 任務 或 Agent 任務 做進一步處理。
- 在「錯誤處理」分頁設定重試與捕捉，因應外部 API 不穩；見 任務通用設定。