跳轉到
版本 v1.0.25

變數 (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)。

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

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

怎麼在流程裡取用變數

先說清楚：這一段目前在畫面上做不到，需要手寫定義

一般欄位的動態引用（.$）有「JSONPath 開關／編輯參考路徑」可以一步步點；但引用變數用的 .% 物件在節點設定面板上沒有對應的表單，必須在工作流程編輯器的「程式碼」檢視（ASL 編輯器）裡手動寫進定義，見編輯器介面導覽。

所以下面這段主要是讓你看懂它的結構與意義，並在跟工程同事討論時講得出要什麼。若要實際做，建議請工程同事協助——找他們時把三件事講清楚就夠了：要用哪一個變數的 ID、要取變數裡的哪一段（jsonpath），以及要塞進哪一個任務的哪一個欄位。（建立與管理變數資源本身則是完整的畫面操作，不受此限，見變數。）

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

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

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

相關主題