Validate Payload

Validate Payload 是 Automation Tool 專用的輸入驗證 processor。

基本用法

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 等類型

連接關係

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. 檢查驗證結果和後續處理

注意事項

1. Validate Payload processor 是 Automation Tool 工作流程的必需入口點。

2. JSON Schema 需要符合標準規範，建議使用線上工具驗證 Schema 正確性。

3. 檔案類型檢查是基於 MIME Type 和副檔名，確保上傳檔案的正確性。

4. 建議為 Failure 分支設計適當的錯誤回應，提供清楚的驗證失敗原因。

5. Path 參數使用 JSON Path 語法，可以驗證複雜巢狀結構中的特定部分。

6. 多個檔案要求時，檔案順序對應設定順序，確保檔案上傳順序正確。