跳轉到
版本 v1.0.34

變數 (Variable)

設計工作流程 (Workflow) 時，常會有一些固定、又被很多步驟或多個流程共用的值——API 網址、逾時秒數、各種門檻、狀態代碼對照表…。這些值可以直接打在每一個用到它的欄位裡，但那樣之後要改就得把每一條流程、每一個步驟翻出來逐一修（英文常說的 hardcode，「寫死」）。比較好的做法是把它們抽出來、存成一個變數 (Variable)：集中存一份，所有流程引用同一份，要調整時只改一個地方。

變數本身是一種資源——存放在平台上的一份 JSON。把它想成一座倉庫：值先存進去，哪個流程要用就去取。

這頁講的是「在流程裡怎麼引用變數」：它跟其他資料來源怎麼分、什麼東西適合抽成變數、以及引用的寫法。至於怎麼建立與管理這個資源（操作步驟、欄位、截圖），請見 變數資源指南。

跟另外兩種資料來源怎麼分

工作流程裡的資料常見有三個來源，很容易搞混。分辨的重點是「這份資料是誰的、存多久」：

來源 是什麼 存活範圍 引用語法
狀態 (State) 這次執行當下流動的資料（工作流程輸入、前一步的產出） 只在這一次執行裡 JSONPath（.$）
變數 (Variable) 預先存好、跨流程共用的設定 長期保留，跨執行、跨流程 外部記憶體語法（.%，type 設 variable）
外部記憶體 (External Memory) 太大、塞不進狀態的資料，寄放在狀態外 跟著該次執行（由平台管理） 外部記憶體語法（.%，type 設 external_memory）

變數和外部記憶體都用 .% 取回，但不是同一件事

兩者剛好共用同一套 .% 取回語法，所以常被混為一談。差別在 .% 物件裡的 type：

  • type: "variable" → 從已存的變數讀（倉庫裡的常備設定）。
  • type: "external_memory" → 從某步驟移到狀態外的大資料讀（置物櫃裡的暫存）。

一句話：變數是「你主動存的設定」，外部記憶體是「系統幫你暫放的大資料」。

哪些東西適合抽成變數

判準是「固定、但偶爾要調整，而且不只一個地方會用到」：

  • API 網址、逾時秒數、重試次數等設定常數。
  • 業務規則門檻（字數上限、自動核可分數…）。
  • 代碼對照表（狀態碼對應中文說明）。
  • 共用的提示詞 (Prompt) 或信件樣板文字。
  • 功能開關 (feature flag)。

把這些抽成變數後，改一個地方、所有引用它的流程一起生效，不用逐一進每個流程改。

判斷方式很簡單：如果這個值有一天要改，而且要改的地方超過一處，就適合抽成變數。

怎麼在流程裡取用變數

這一段在畫面上就做得到，不必手寫定義

引用變數不需要碰 ASL。在任務的設定面板上：把滑鼠移到要填的欄位上 → 打開標籤右側浮出的「JSONPath」開關 → 欄位變成唯讀路徑框，點那個框（或右側的 鉛筆）開啟「編輯參考路徑」對話框 → 把對話框裡的「來源」從「狀態輸入」改成「變數」→ 填變數的 ID 與要取的 jsonpath → 按「儲存」。

下面那段 .% JSON 是平台照填入的內容自動產生的長相，不必自己寫。看懂它有助於除錯（例如打開「定義」開關對照），但操作上只要走上面那條路。對話框的完整說明見任務通用設定 › 欄位的輸入方式切換。

在任務 (Action) 的輸入用 .% 語法，把 type 設成 variable，指定變數的 id 與要取的 jsonpath：

{
  "api_settings.%": {
    "type": "variable",
    "id": "var-api-config",
    "jsonpath": "$"
  }
}

id 是那筆變數的識別碼（到「資源 (Resources) → 變數 (Variable)」點進詳細頁可複製），jsonpath 指要取變數裡的哪一段（$ 代表整份）。逐欄位的詳細說明見 變數資源指南的「如何在工作流程中引用變數」；動態 id.$、與 .$ 混用、常見錯誤等完整語法見 外部記憶體語法。

相關主題