TIPCommon.validation

TIPCommon.validation 模組包含 ParameterValidator 類別，這是確保整合中資料完整性的重要工具。可自動檢查輸入類型、強制執行限制 (例如數值範圍或電子郵件格式)，並提供安全的回退值，防止執行階段當機。

`ParameterValidator` 類別

ParameterValidator 類別提供標準化介面，可驗證各種參數類型。每種方法都會接受參數名稱和值，並以適當的 Python 型別傳回經過驗證的值。如果驗證失敗且未提供 default_value，系統會引發 ParameterValidationError。

使用範例

如要使用驗證器，請使用 siemplify SDK 物件初始化：

from TIPCommon.validation import ParameterValidator

# Initialize the validator
validator = ParameterValidator(siemplify)

# Validate and cast strings to specific types
validated_float = validator.validate_float(param_name='Threshold', value='3.7')
validated_int = validator.validate_integer(param_name='Retry Count', value='5')

數值和限制驗證

這些方法可確保數值輸入內容落在預期範圍內，並正確轉換為適當的 Python 型別。

函式	參數	說明與退貨
`validate_float()`	`param_name`：(字串) `value`：(str \| float)	傳回：`float` 驗證值是否可轉換為浮點數。適用於門檻或機率分數。
`validate_integer()`	`param_name`：(字串) `value`：(str \| int)	傳回：`int` 驗證值並將其轉換為整數。
`validate_range()`	`value`：(str \| int) `min_limit`：(整數) `max_limit`：(整數)	傳回：`int` 確保整數落在 `min_limit` 和 `max_limit` 定義的範圍內 (含首尾)。
`validate_percentage()`	`value`：(str \| int)	傳回：`int` 確保值是介於 `0` 和 `100` 之間的整數 (含首尾)。
`validate_non_negative()`	`value`：(str \| int)	傳回：`int` 確保值為整數 `≥ 0`。
`validate_non_zero()`	`value`：(str \| int)	傳回：`int` 確保值為整數，且不等於 `0`。
`validate_positive()`	`value`：(str \| int)	傳回：`int` 確保值為整數 `> 0`。
`validate_lower_limit()`	`value`：(str \| int) `limit`：(整數)	傳回：`int` 確保值為指定的 `limit` `≥`。
`validate_upper_limit()`	`value`：(str \| int) `limit`：(整數)	傳回：`int` 確保值為指定的 `limit` `≤`。

資料結構和字串驗證

這些方法會驗證較複雜的輸入類型，例如以分隔符號分隔的字串、JSON 物件，以及電子郵件地址等特定格式。

函式	參數	說明與退貨
`validate_csv()`	`csv_string`：(字串) `delimiter`：(str) 預設為 `', '`。 `possible_values`：(清單) 選用許可清單。	傳回：`list` 使用分隔符號將字串拆分成清單。如果提供 `possible_values`，系統會根據該清單驗證每個項目。
`validate_json()`	`json_string`：(字串) `**kwargs`：`json.loads()` 的轉送。	傳回：`dict \| list` 將字串剖析為 JSON 物件。如果字串不是有效的 JSON，則會引發錯誤。
`validate_email()`	`email`：(字串)	傳回：`str` 驗證提供的字串是否符合標準電子郵件格式。
`validate_ddl()`	`value`：(字串) `ddl_values`：(清單) 有效值的許可清單。 `case_sensitive`：(bool) 預設為 `False`。	傳回：`str` 驗證輸入內容是否與定義的 DDL 中的其中一個值相符。
`validate_severity()`	`severity`：(str \| int) `possible_values`：(清單)	傳回：`int` 驗證平台嚴重程度輸入內容。正確對應平台標準嚴重性標籤 (例如「高」) 和對應的整數等級。

全域驗證設定

ParameterValidator 類別中的每個驗證方法都支援下列選用關鍵字引數，可控制失敗時的行為或用於偵錯：

default_value：如果提供這個值，驗證失敗時會傳回這個值，而不是引發 ParameterValidationError。
print_value：(bool) 如果為 True，記錄訊息會包含導致失敗的無效值。預設值為 True。
print_error：(bool) 設為 True 時，平台記錄會包含特定例外狀況訊息。預設值為 False。