跳轉到

JSONPath 語法

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

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

你不用手打這些 $. 字串

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

在畫面上實際怎麼填

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

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

要讓「AI 分診」步驟引用這筆主訴：

  1. 在這個大型語言模型步驟的內容區塊（例如「提示詞」欄位）旁，勾選右上角的「JSONPath」開關。

    「提示詞」欄位右上角的「JSONPath」開關

  2. 欄位會變成可填參考路徑的狀態；點旁邊的「編輯參考路徑」開啟對話框。

  3. 把「來源」選為「狀態輸入」，在「JSONPath」欄填 $.question。

    「編輯參考路徑」對話框：「來源」選「狀態輸入」、「JSONPath」填 $.question

  4. 儲存後，平台會在底層產生 "text.$": "$.question"——也就是本頁範例看到的樣子。

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

$.question 裡的 question 是哪來的？

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

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

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

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

怎麼確認「真正」的路徑？到那一步的設定面板「輸入與輸出」分頁，看欄位裡填的實際值。

語法格式

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

關鍵要求： 所有動態欄位引用都必須使用 .$ 後綴。

常見模式

存取 Workflow 輸入

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

存取前一個 Action 輸出

{
  "url.$": "$.retrieval_action.documents[0].url"
}

存取巢狀屬性

{
  "customer_id.$": "$.api_response.data.customer.id"
}

存取陣列元素

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

實用範例

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

Workflow 輸入：

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

AI 分診（LLM Action）設定：

  • User Message: $.question

分診步驟就會收到來自 Workflow 輸入的主訴。畫面上實際怎麼勾選、怎麼填，見本頁開頭「在畫面上實際怎麼填」。

範例 2：在下一個 Action 中使用 API 回應

HTTPS API Action 輸出：

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

下一個 Action 設定：

{
  "user_id.$": "$.api_call.body.user_id",
  "email.$": "$.api_call.body.email"
}

範例 3：串連 Workflow 執行

Start Workflow Execution 輸出：

{
  "execution_arn": "arn:aws:states:us-east-1:123456789012:execution:child-wf:exec-123"
}

Describe Workflow Execution 設定：

{
  "execution_arn.$": "$.start_child.execution_arn"
}

存取 Action 結果

當引用前一個 Action 的資料時，使用 ResultPath：

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

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

  • Action 名稱為「LLMAction」→ $.LLMActionResult
  • Action 名稱為「RetrievalAction」→ $.RetrievalActionResult

改名 Action 後，ResultPath 不會自動更新

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

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

→ 了解更多關於 Path Parameter

陣列與物件存取

陣列索引

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

萬用字元選擇

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

注意： 萬用字元會回傳陣列。確保使用的 Action 預期收到陣列資料。

巢狀存取

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

最佳實踐

保持表達式簡單：

  • 偏好使用 $.user.name 而非複雜的巢狀路徑
  • 將複雜的轉換拆分成多個 Action

測試邊界情況：

  • 空陣列：如果 items 為空，$.items[0] 會失敗
  • 遺漏的欄位：$.user.optional_field 可能是 undefined
  • 如需預設值，使用 Pass Action 新增

使用有意義的名稱：

  • $.customer_id 比 $.id 更清楚
  • $.llm_response.text 顯示資料來源

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

  • $.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
}

在引用 URL 之前，使用 Pass Action 或程式碼（Code）Action 建構 URL。（「資料轉換（Transformation）」已棄用，請改用前述替代。）

❌ 陣列存取沒有邊界檢查

{
  "item.$": "$.results[0]"  // 如果 results 為空會失敗
}

✅ 新增驗證或使用 Pass Action 搭配預設值

何時使用 JSONPath

使用 $. 語法當：

  • ✅ 存取 Workflow 輸入
  • ✅ 使用前一個 Action 輸出
  • ✅ 資料為小至中型大小（< 256 KB）
  • ✅ 資料特定於當前執行

不要使用 $. 當：

相關主題