Validate Payload

基本用法​

Validate Payload 是 Automation Tool 的資料驗證器，專門用來檢查 API 調用時傳入的資料是否正確。它就像是 API 的「門衛」，確保只有格式正確的資料才能進入後續處理流程。

主要功能​

1. 驗證資料結構：使用 JSON Schema 檢查傳入的資料格式、類型、必填欄位等
2. 檢查檔案上傳：驗證上傳檔案的類型（圖片、影片、文件等）和格式
3. 提供安全防護：防止錯誤或惡意的資料影響後續處理

工作流程​

• 驗證成功：資料通過檢查，工作流程繼續執行，驗證後的資料會以 prevPayload 變數提供給後續 processor 使用
• 驗證失敗：資料不符合要求，進入錯誤處理流程，產生 prevError 變數記錄錯誤資訊

重要特色​

• 這是 Automation Tool 工作流程的必需入口點，所有 API 工具都必須從這裡開始
• 與 Response processor 配對使用，形成完整的 API 工具架構
• 支援複雜的資料驗證規則，包括字串長度、數值範圍、列舉值等
• 可以驗證巢狀資料結構中的特定部分

配置參數​

Name​

顯示在畫布上的名稱，用於在工作流程中識別此 processor。

Description​

用於補充此 processor 的用途，提升工作流程的可讀性。

Properties​

Schema（必填）​

用於驗證輸入資料的 JSON Schema，定義 API 請求應該符合的資料結構、類型和限制條件。

Path​

指定要驗證的資料範圍，使用 JSON Path 語法來選擇特定的資料路徑。預設值為 $，表示驗證整個根物件。在 Automation Tool 中，此欄位為唯讀狀態，無法修改。

File Requirements​

設定檔案上傳的驗證要求，可以檢查檔案數量、類型和格式：

• File Alias：為檔案設定別名變數，驗證通過後可透過此變數名稱存取檔案資訊
• File Type：限制檔案類型，支援 IMAGE、VIDEO、AUDIO、DOCUMENT、BINARY 等類型

在 Workflow CRD 中的設定​

- name: proc-validate
  type: validate-payload
  labels:
    display_name: 驗證輸入
  configs:
    - name: path
      value: $.prevPayload
    - name: schema
      value: |-
        {
          "type": "object",
          "required": ["order_id"],
          "properties": {
            "order_id": {
              "type": "string",
              "description": "要查詢的訂單編號"
            }
          }
        }

path 的預設值是 $.prevPayload，也就是驗證上一個節點傳來的整包 payload。要驗證其中某個欄位時把 JSONPath 往下指，例如 $.prevPayload.order。

schema 是一段 JSON Schema 字串，新增節點時會帶一份只有 foo 欄位的範例 schema，實務上要整段換掉。

連接關係​

Success​

當資料結構驗證通過且檔案要求符合時，工作流程會從此連接點繼續執行。驗證後的資料會以 prevPayload 變數提供給後續 processor 使用，檔案別名變數也會被建立。

Failure​

當資料驗證失敗或檔案要求不符合時，工作流程會從此連接點繼續執行，並產生 prevError 變數儲存錯誤資訊。

適用範圍​

Validate Payload processor 僅適用於 Automation Tool 類型的工作流程，不適用於 Bot 類型。它與 Response processor 配對使用，Validate Payload 負責驗證輸入，Response 負責格式化輸出。

使用範例​

API 資料存取工具​

建立一個存取外部 API 的工具。Validate Payload 驗證調用端傳入的參數（如 ID），驗證通過後使用 HTTP Request 調用外部 API，最後透過 Response 回傳結果。

Schema 範例：

{
  "type": "object",
  "properties": {
    "todoId": {
      "type": "string",
      "description": "要查詢的 Todo ID"
    }
  },
  "required": ["todoId"]
}

圖片辨識 API 工具​

建立一個圖片辨識 API 工具。Validate Payload 驗證使用者問題和上傳的圖片格式，驗證通過後使用支援視覺的 LLM 進行辨識，最後回傳辨識結果。

Schema 範例：

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "使用者的問題"
    }
  },
  "required": ["question"]
}

File Requirements：

• File Type: IMAGE
• File Alias: img

複合資料處理工具​

建立一個整合多個資料來源的 API 工具。Validate Payload 驗證必要的查詢參數，然後依序從資料庫和外部 API 取得資料，最後整合回傳。

Schema 範例：

{
  "type": "object",
  "properties": {
    "userId": {
      "type": "string",
      "description": "使用者 ID"
    },
    "category": {
      "type": "string",
      "enum": ["A", "B", "C"],
      "description": "查詢類別"
    }
  },
  "required": ["userId", "category"]
}

Schema 設計指南​

常見驗證規則​

{
  "type": "object",
  "required": ["name", "email"],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "number",
      "minimum": 0,
      "maximum": 150
    },
    "category": {
      "type": "string",
      "enum": ["A", "B", "C"]
    }
  }
}

檔案類型說明​

• IMAGE：圖片檔案，如 JPEG、PNG、GIF 等
• VIDEO：影片檔案，如 MP4、MOV 等
• AUDIO：音訊檔案，如 MP3、M4A、WAV 等
• DOCUMENT：文件檔案，如 PDF、DOCX、TXT 等
• BINARY：無法確定類型的二進位檔案

輸出變數​

驗證成功後，會產生以下變數供後續 processor 使用：

• prevPayload：驗證通過的資料物件
• 檔案別名變數：包含 blobId、fileType、fileName、size、mime 等檔案資訊

預覽測試​

建立 Validate Payload 後，可以使用 Automation Tool 的 Preview 功能進行測試：

1. 點擊 Preview 按鈕
2. 根據 Schema 定義輸入測試資料
3. 如有檔案要求，上傳對應的測試檔案
4. 檢查驗證結果和後續處理

注意事項​

• 這是 Automation Tool 工作流程的必要入口節點。
• Schema 要符合 JSON Schema 標準。
• 檔案型別的檢查同時看 MIME Type 和副檔名。