變數¶

這頁能幫你做什麼¶

變數 (Variable) 讓你把一份設定資料集中存成 JSON，之後在多個工作流程 (Workflow) 中共用。例如把 API 網址、各種門檻值、狀態代碼對照表存成一個變數，要調整時改一個地方就好，不用到每個流程裡逐一修改。

常見情境：

集中管理 API 網址、逾時秒數、重試次數等設定常數。
存放業務規則門檻（字數上限、自動核可分數等）。
維護代碼對照表（狀態碼對應中文說明）。
控制功能開關 (feature flag)，決定哪些功能要啟用。

開始前¶

前置需求

建立變數不需要其他資源。請先想好這份資料的結構，並確認它是合法的 JSON 格式。

操作步驟¶

從左側資源選單進入「變數」清單頁，點建立入口（空清單時是有文字的建立按鈕；清單已有項目時是右上角無文字的「+」圖示）開啟建立表單。
在「名稱」欄輸入好辨識的名稱（例如 api-config）。
在「類型」選擇 JSON（選好後才會出現「值」欄位）。
在「值」欄填入 JSON 內容（見上圖編輯器內容）。
按右上角的「儲存」按鈕完成建立（見上圖右上角）。

完整欄位說明¶

欄位	必填	預設	說明
名稱	是	無	此變數的識別名稱。最多 64 個字，不可用 `default` 開頭。
類型	是	無（需選擇）	變數類型，目前僅 `JSON` 一種。建立後無法更改。選好後才會出現「值」欄位。
值	是	無	變數的實際內容，須為合法的 JSON。選「類型」為 `JSON` 後出現，提供 JSON 編輯器。

「值」可以放哪些 JSON

JSON 類型適合多層次或陣列型態的資料，「值」欄位接受任何合法 JSON：

字串："Hello World"
數字：42、3.14
布林值：true、false
空值：null
物件：{"key": "value", "nested": {"data": 123}}
陣列：[1, 2, 3]、["a", "b", "c"]

一個常見的範例是集中管理一組 API 設定：

{
  "base_url": "https://api.example.com/v1",
  "timeout_seconds": 30,
  "retry_attempts": 3
}

之後在多個工作流程引用同一份 api-config，要調整網址或逾時設定時，只需改這一個變數。

變數 (Variable) 與樣板 (Template) 的差異

存「資料值」（數字、物件、陣列、設定開關）用變數。
存「帶有替換位置的文字」（提示詞、信件範本）用樣板 (Template)。

變數詳細頁¶

建立完成後點進某個變數，詳細頁上方有三個頁籤：「一般」、「依賴資源」、「被依賴資源」。下圖為「一般」頁籤，可看到 ID、名稱、類型、狀態與變數值——其中 ID 就是後面用 .% 引用時要填的值，點 ID 左側的複製（）圖示即可複製：

變數詳細頁的「一般」頁籤，顯示 ID、名稱、類型、系統資訊、狀態、最後更新與 JSON 值，ID 左側有複製圖示，上方有「一般」「依賴資源」「被依賴資源」三個頁籤

頁籤	內容
一般	變數的基本資料：ID、名稱、類型、系統資訊、狀態、最後更新，以及完整的 JSON 值。卡片右上角的圖示鈕可編輯（）、複製（）或刪除（）。
依賴資源	這個變數用到的其他資源。
被依賴資源	反過來，有哪些資源用到這個變數（例如在欄位裡 `.%` 引用它的工作流程）。

變數沒有「驗證」功能

變數詳細頁不提供「驗證憑證／測試連線」按鈕——它只是一份儲存的資料，不連外部系統。要確認它有沒有用，看下方「使用效果」。

如何在工作流程中引用變數¶

把資料存成變數後，要在工作流程的任務欄位裡使用它，是透過 .% 引用語法（與 External Memory 同一套），而不是直接寫變數名稱。做法是把欄位的 key 加上 .% 後綴，值填一個指定 type、id、jsonpath 的物件：

{
  "api_settings.%": {
    "type": "variable",
    "id": "<變數的 id>",
    "jsonpath": "$"
  }
}

type：固定填 variable，代表要讀的是變數資源。
id：要引用的變數 id，即上方詳細頁「一般」頁籤裡的 ID（點複製圖示取得）。
jsonpath：要從變數值裡取哪一段；$ 代表整包，也可只取子欄位（例如 $.base_url）。

使用效果¶

變數不能單獨執行，它的價值在於「被工作流程的任務欄位引用、執行時即時展開」。建立好的變數會在這些地方被選用：

工作流程的任務欄位：用上方 .% 引用語法把變數值接進欄位，任務執行時即時載入該變數的內容。
多個流程共用：你在多個工作流程引用同一個變數，改了變數值之後所有引用處都會跟著更新——改一處、全部生效。

例如上方詳細頁的 api-config 變數，在某個工作流程的 HTTP 任務裡用 "url.%": {"type": "variable", "id": "<api-config 的 id>", "jsonpath": "$.base_url"} 引用，執行時 $.base_url 會即時展開成 https://api.example.com/v1。完整語法（動態 id 用 id.$、與 $. JSONPath 混用、常見錯誤）見 External Memory 語法。

下一步¶

樣板 (Template)：搭配變數，產生動態文字內容。
External Memory 語法：.% 引用的完整寫法。
資源總覽：查看其他資源類型。