JSONPath 語法¶

JSONPath（$.）是你最常用的一種——它就是「把狀態裡某一欄調出來」的寫法（也就是前面比喻裡「翻開病歷夾、把某一欄調出來」那個動作）。工作流程輸入、前一個步驟的產出，都靠它接到下一步。

把 $. 想成門牌地址：$ 是「整塊狀態」，後面接的就是要找的那一欄的名字。例如 $.question = 「狀態裡那個叫 question 的欄位」；$.RetrievalActionResult.docs = 「狀態裡 RetrievalActionResult 那一區裡面的 docs」。

你不用手打這些 $. 字串

本頁的 { "field.$": "$.path" } 是平台在底層產生的長相，不是要你打字輸入。實際操作時你是在欄位標籤右側打開「JSONPath」開關、填路徑，平台才產生它。先看下面「在畫面上實際怎麼填」。

在畫面上實際怎麼填¶

以看診流程裡的「AI 分診」步驟為例：它要讀病人掛號時填的主訴。假設你的工作流程輸入長這樣：

{ "question": "我頭痛又發燒，該看哪一科？" }

要讓「AI 分診」步驟引用這筆主訴，你要改的是它的「提示詞」欄位——而那個欄位藏在兩層對話框裡面。設定入口是一層層相套的，請由外而內依序打開：

在畫布上點這個大型語言模型節點，右側滑出設定面板；在「設定」分頁找到「對話」表格。
在「對話」表格把滑鼠移到「使用者」那一列上，點該列的編輯（）圖示，開啟「編輯對話」。

看不到那顆鉛筆？把表格往右捲

節點面板不寬，「對話」表格的最後一欄（放編輯與刪除圖示的那一欄）常被切在畫面外。把表格左右捲動就會看到最右邊的鉛筆（）與垃圾桶（）。
在「編輯對話」的「內容」表格，同樣點該列的編輯（）圖示，開啟「編輯內容」。「提示詞來源」維持預設的「自訂提示詞」即可。
在「編輯內容」找到「提示詞」欄位，打開它標籤右側的「JSONPath」開關。開關要把滑鼠移到該欄位上才會出現，平常是隱藏的。
欄位會變成唯讀的路徑框；點右側的鉛筆鈕（）開啟「編輯參考路徑」對話框。
把「來源」選為「狀態輸入」，在「JSONPath」欄填 $.question。
由內而外逐層按「儲存」回到設定面板。平台會在底層產生 "text.$": "$.question"——也就是本頁範例看到的樣子。

JSONPath 要開在「提示詞」，不要開在整個「對話」

「對話」欄位的標籤旁邊也有一顆 JSONPath 開關（同樣 hover 才出現），很容易誤開。但「對話」要的是一串訊息（陣列），在那裡填單一個 $.question 會型別不符而執行失敗。動態帶入一定要開在內容區塊的「提示詞」欄位上，也就是上面的步驟。

如果你只是要填一段固定文字，就不要打開「JSONPath」開關，直接打字即可。

$.question 裡的 question 是哪來的？

它就是你工作流程輸入欄位的名字。上面輸入長這樣 { "question": "..." }，所以你填 $.question。如果你的輸入欄位取名叫 user_input，那就要填 $.user_input。這個名字是你在工作流程的輸入／觸發設定裡定的，不是固定咒語。

如果 AI 收到的是空的（null），先查這兩件事

新手最常遇到的就是「明明填了卻抓到空值」。九成是這兩個原因：

名字對不上——你填的 $.xxx 跟實際的欄位名稱不一樣（例如輸入其實叫 user_input，你卻填 $.question）。
你引用的那一步改過名字——引用前一步的產出時，路徑會跟步驟名稱有關；步驟改名後路徑不會自動更新（詳見下方存取任務結果）。

怎麼確認「真正」的路徑？到那一步的設定面板「輸入與輸出」分頁，看兩個欄位的實際值：ResultPath 是「這一步的輸出存在狀態的哪裡」，ResultSelector 決定「那底下的欄位叫什麼名字」。兩段接起來就是完整路徑。

大型語言模型任務的「輸入與輸出」分頁：ResultSelector 為 {"message.$": "$.Payload.message"}、ResultPath 為 $.LLMActionResult，所以完整路徑是 $.LLMActionResult.message

語法格式¶

平台在底層產生的長相是這樣：

field.$: "$.path.to.value"

規則是：凡是動態引用資料的欄位，欄位名稱後面都會多一個 .$ 後綴。

這條規則是給「看懂」用的，不是要你自己加後綴

在畫面上操作時，.$ 是平台幫你加的——你只要打開「JSONPath」開關、填路徑就好。會需要認得這條規則的情況有兩個：看編輯器「程式碼」檢視或詳細頁「定義」卡片裡的 JSON 時，知道 field.$ 代表「這一欄是動態的」；以及真的要手寫定義時（進階，見編輯器介面導覽）。

常見模式¶

存取 Workflow 輸入¶

{
  "query.$": "$.user_question"
}

存取前一個任務輸出¶

{
  "url.$": "$.RetrievalActionResult.docs[0].url"
}

路徑的第一段一定是那個任務的 ResultPath

本頁範例統一用 $.<任務名稱>Result（例如 $.RetrievalActionResult）這種形式，因為那才是平台實際產生的 ResultPath。不要自己另取小寫的名字——路徑必須和該任務「輸入與輸出」分頁 ResultPath 欄位裡的值一字不差。

存取巢狀屬性¶

{
  "customer_id.$": "$.HttpsApiActionResult.output.data.customer.id"
}

存取陣列元素¶

{
  "first_result.$": "$.search_results[0].title",
  "all_ids.$": "$.items[*].id"
}

實用範例¶

範例 1：把病人主訴傳給「AI 分診」步驟¶

工作流程輸入：

{
  "question": "我頭痛又發燒，該看哪一科？"
}

AI 分診（大型語言模型任務）設定：

在「對話」表格裡「角色」為「使用者」那一列，點進去的「編輯內容」對話框中，把「提示詞」欄位設成 $.question（大型語言模型任務沒有叫「User Message」的欄位）。

分診步驟就會收到來自工作流程輸入的主訴。畫面上實際怎麼一層層打開、怎麼填，見本頁開頭「在畫面上實際怎麼填」。

範例 2：在下一個任務中使用 API 回應¶

HTTPS API 任務輸出：

{
  "action_type": "https_api_action",
  "status": 200,
  "body": {
    "user_id": "12345",
    "email": "user@example.com"
  }
}

下一個任務設定：

{
  "user_id.$": "$.HttpsApiActionResult.output.body.user_id",
  "email.$": "$.HttpsApiActionResult.output.body.email"
}

範例 3：串連兩個工作流程執行任務¶

這兩個任務在畫面上的名字是「執行工作流程」與「查看工作流程執行」（面板的「新增狀態」→「工作流程執行」分類裡就是這兩個字）。

「執行工作流程」任務的輸出：

{
  "execution_arn": "arn:aws:states:us-east-1:<你的帳號 ID>:execution:child-wf:exec-123"
}

「查看工作流程執行」任務的設定：

{
  "execution_arn.$": "$.StartWorkflowExecutionActionResult.execution_arn"
}

路徑中間那一段 StartWorkflowExecutionActionResult 不是要背的固定字串，而是上一步的 ResultPath——它預設是 $.<步驟名稱>Result，本例中上一步的「名稱」是 StartWorkflowExecutionAction，兩者合起來就是這個路徑。你的步驟取什麼名字，這裡就跟著換；若你自己改過那一步的 ResultPath，就以你填的為準（見任務通用設定 › 輸入與輸出設定）。

存取任務結果¶

當引用前一個任務的資料時，使用 ResultPath 加上它底下的欄位名稱：

{
  "query.$": "$.LLMActionResult.message"
}

每個任務在「建立當下」的輸出儲存位置（ResultPath）會依它的預設名稱產生一次。例如：

任務名稱為「LLMAction」→ $.LLMActionResult
任務名稱為「RetrievalAction」→ $.RetrievalActionResult

大型語言模型任務底下的欄位叫 message，不是 text

大型語言模型任務預設的 ResultSelector 是 {"message.$": "$.Payload.message"}，所以它的回答存在 $.LLMActionResult.message。寫 $.LLMActionResult.text 會抓到 null。不同任務的欄位名稱不一樣（例如「文字」任務是 $.TextActionResult.text），不確定時到該任務「輸入與輸出」分頁看 ResultSelector 的實際內容，見 Path Parameters。

改名任務後，ResultPath 不會自動更新

ResultPath 只在建立步驟時依預設名稱產生一次。之後就算你把任務改名，ResultPath 也不會跟著變。 例如把「LLMAction」改名為「Triage」後，它的 ResultPath 仍然是 $.LLMActionResult，執行結果也仍掛在 LLMActionResult 底下。這時如果你照著新名字去引用 $.TriageResult.message，會抓到 null。

所以不要假設 ResultPath 一定等於「目前的任務名稱 + Result」。要確認真正的 ResultPath，請到該步驟設定面板的「輸入與輸出」分頁查看 ResultPath 欄位的實際值；若想讓它跟著新名字走，需在該欄位手動改。

→ 了解更多關於 Path Parameter

陣列與物件存取¶

陣列索引¶

{
  "first_item.$": "$.results[0]",
  "last_item.$": "$.results[-1]"
}

萬用字元選擇¶

{
  "all_ids.$": "$.items[*].id"
}

注意： [*] 取回來的是一份清單（陣列），就算符合的只有一筆也一樣。要確認接這個值的欄位本來就吃清單。

巢狀存取¶

{
  "value.$": "$.HttpsApiActionResult.output.data.items[0].properties.name"
}

最佳實踐¶

這一節開始技術味較重，第一次讀可以先跳過

下面幾條是實務上踩過雷才會在意的細節。第一次學只要記住「打開 JSONPath 開關、填 $.欄位名」就夠用；等到真的遇到「抓到空的」「型別不符」再回來看這幾條。

路徑越短越好：

能寫 $.user.name 就不要寫一長串巢狀路徑
需要大幅改資料形狀時，拆成一個獨立的步驟去做（例如「傳遞資料」或「程式碼」任務），不要靠一條超長的路徑硬撈

先想過「資料不如預期」的情況：

清單是空的：如果 items 一筆都沒有，$.items[0]（取第一筆）就取不到、會失敗
欄位根本沒出現：選填欄位（例如 $.user.optional_field）在這次執行可能不存在，取到的是「沒有值」
需要「取不到時補一個預設值」，用「傳遞資料」任務先補上（見傳遞資料）

使用有意義的名稱：

$.customer_id 比 $.id 更清楚
$.LLMActionResult.message 一看就知道值從哪一步來

除非必要，避免使用萬用字元 [*]：

$.items[0].id（明確取第一筆）比 $.items[*].id 更可預測
[*] 代表「全部」，所以取回來的一定是一份清單（陣列），就算只有一筆也是清單；如果下一步的欄位只吃單一個值，就會型別不符

常見錯誤¶

❌ 遺漏 .$ 後綴

{
  "query": "$.user_question"  // 錯誤！
}

✅ 動態引用一律使用 .$

{
  "query.$": "$.user_question"  // 正確
}

❌ 字串串接

{
  "url": "https://api.example.com/users/$.user_id"  // 錯誤！不支援
}

✅ 引用完整值

{
  "url.$": "$.full_api_url"  // 正確 - full_api_url 包含完整 URL
}

所以要組出一段「網址＋動態值」的字串，得先用「傳遞資料」或「程式碼」任務把完整網址組好，再整個引用它。（「資料轉換（Transformation）」任務在平台上已標為「資料轉換 (已棄用)」，新流程請改用前述兩種。）

❌ 取清單的第一筆，但沒想過清單可能是空的

{
  "item.$": "$.results[0]"
}

如果 results 這次一筆都沒有，這個路徑取不到值，那一步就會失敗。

✅ 先確保清單一定有內容，或用「傳遞資料」任務補一個預設值

在取第一筆之前，先用「依條件分類」判斷清單有沒有內容（見流程控制節點），或用「傳遞資料」任務先填一個預設值進去（見傳遞資料）。

何時使用 JSONPath¶

使用 $. 語法當：

✅ 存取工作流程輸入
✅ 使用前一個任務輸出
✅ 資料不大（工作流程狀態每次執行約有 256 KB 上限，一般的問答、表單欄位遠遠用不到）
✅ 資料只跟這一次執行有關（下一次執行不需要沿用）

不要使用 $. 當：

❌ 資料超過狀態上限（約 256 KB，例如整份文件）→ 改用外部記憶體
❌ 要一份「每次執行都沿用、改一次全部生效」的設定 → 使用變數 (Variable)
❌ 要套一段帶變數的罐頭文字 → 使用 Template 語法