Skip to main content

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. 多個檔案要求時，檔案順序對應設定順序，確保檔案上傳順序正確。