TIPCommon.utils

TIPCommon.utils 模块是集成开发者的基础工具包。它为字符串操作、安全类型转换、OData 查询构建和特定于环境的检查提供了必要的辅助程序，以确保集成在不同的平台版本和执行状态下顺利运行。

数据清理和类型转换

这些函数可处理数据的“预处理”，确保变量在用于逻辑或发送到外部 API 之前采用正确的格式。

函数	参数	说明和退货
`camel_to_snake_case()`	`string`：(str) 目标 `camelCase` 字符串。	返回：`str` 将 `camelCase` 或 `PascalCase` 字符串转换为 `snake_case`。对于将 API 响应规范化为 Python 式命名惯例至关重要。
`cast_keys_to_int()`	`data`：（字典）具有数字字符串键的字典。	返回：`dict` 创建一个新字典，其中所有键都转换为整数。在处理将 ID 表示为字符串的 JSON 数据时经常使用。
`clean_result()`	`value`：（字符串）目标字符串。	返回：`str` 去除开头和结尾的空格。一种用于清理集成参数中的用户输入的关键实用程序。
`none_to_default_value()`	`value_to_check`：（任意）输入值。 `value_to_return_if_none`：（任意）回退。	返回：`Any` 检查某个值是否为 `None`。如果存在，则返回默认回退值；否则，返回原始值。
`safe_cast_bool_value_from_str()`	`default_value`：（任意）要评估的值。	返回：`bool \| Any` 将字符串布尔值（例如“true”）转换为实际的布尔值。如果转换失败，则返回 `default_value`。
`safe_cast_int_value_from_str()`	`default_value`：（任意）要评估的值。	返回：`int \| Any` 尝试将值转换为整数。如果转换不成功，则返回 `default_value`。

这些实用程序允许脚本识别其运行时上下文，例如它们是作为测试、异步操作还是在特定版本的平台上运行。

函数	参数	说明和退货
`is_first_run()`	`sys_argv`：(list) 来自 `sys.argv` 的实参。	返回：`bool` 确定是否首次异步执行操作。用于管理轮询操作中的状态。
`is_test_run()`	`sys_argv`：(list) 来自 `sys.argv` 的实参。	返回：`bool` 标识脚本是否正在 IDE 中以“测试”模式运行。在开发期间使用此方法可绕过实际的 API 调用。
`is_overflowed()`	`siemplify`：(SiemplifyConnectorExecution) `alert_info`：(AlertInfo) `is_test_run`：（布尔值）	返回：`bool` 检查提醒是否符合平台的溢出条件。对于连接器而言至关重要，可防止冗余的提醒提取。
`is_python_37()`	无	返回：`bool` 检查当前 Python 版本是否至少为 3.7。有助于在旧版和新版语言功能之间切换。
`platform_supports_1p_api()`	无	返回：`bool` 检查实例是否支持第一方 (1P) 统一 API。为多平台支持启用动态回退逻辑。
`platform_supports_db()`	`siemplify`：(ChronicleSOAR) SDK 对象。	返回：`bool` 确定环境是否支持 DataStreams。如果为 `False`，集成应回退到基于文件的状态。

用于确保数据完整性、执行集合运算以及从复杂的 JSON 结构中检索值的实用程序。

函数	参数	说明和退货
`escape_odata_literal()`	`value`：（任意）原始查询值。	返回：`Any` 将字符串中的单引号加倍，以符合 OData 标准。重要提示：这可防止 `$filter` 表达式中出现查询注入和语法错误。
`get_unique_items_by_difference()`	`item_pool`：（可迭代）源项。 `items_to_remove`：（可迭代）排除列表。	返回：`list` 计算集合差（Pool - Remove），并以列表形式返回唯一项。有助于过滤已处理的提醒。
`get_value_from_json()`	`data`：(dict) 要搜索的 JSON 数据。 `*keys`：(str) 有序的后备键。 `default`：（任意）后备值。	返回：`Any` 使用“瀑布式”键从嵌套 JSON 中检索值。如果所有键都不存在，则返回 `default`。
`is_empty_string_or_none()`	`data`：(str) 要检查的字符串。	返回：`bool` 如果输入为 `None` 或仅包含空字符串 `""`，则返回 `True`。对于 API 响应的安全检查至关重要。
`is_valid_email()`	`email_addr`：(str) 要检查的字符串。	返回：`bool` 使用标准正则表达式验证电子邮件地址格式。在外部 API 调用之前预先验证参数时非常有用。
`is_valid_uuid()`	`string`：(str) 要检查的字符串。	返回：`bool` 确保字符串是有效的 UUID 版本 4。防止在将 ID 传递给平台端点时出现 400 错误。

用于与操作系统交互、管理临时文件和处理实体元数据的辅助程序。

函数	参数	说明和退货
`create_and_write_to_tempfile()`	`content`：(str \| bytes) 要写入的数据。	返回：`Path` 将内容写入安全的临时文件。适用于需要将数据传递给命令行工具的操作。
`get_entity_original_identifier()`	`entity`：（实体）目标实体对象。	返回：`str` 检索实体的原始标识符，确保准确地映射回来源提醒。
`get_function_arg_names()`	`func`：（可调用）目标函数。	返回：`list` 使用反射来检索函数中定义的所有实参名称。对于构建动态封装容器至关重要。
`get_sdk_api_uri()`	`chronicle_soar`：(ChronicleSOAR) SDK 实例。	返回：`str` 检索当前环境的基本 API URI。对于在标准封装容器之外构建自定义 REST 调用至关重要。
`safe_json_for_204()`	`response`：（响应）HTTP 响应对象。 `default_for_204`：（任意）后备值。	返回：`list \| dict \| Any` 安全处理 204（无内容）响应。返回空列表或 `default_for_204` 值，而不是在 JSON 解析期间崩溃。
`temporarily_remove_header()`	`header_name`：(str) 要抑制的标头。	返回：`callable` 装饰器：在单次调用的持续时间内，暂时从会话中移除标头（例如 `'Prefer'`）。