TIPCommon.utils

Le module TIPCommon.utils sert de boîte à outils de base pour les développeurs d'intégrations. Il fournit des outils essentiels pour la manipulation de chaînes, le transtypage sécurisé, la construction de requêtes OData et les vérifications spécifiques à l'environnement afin de garantir le bon fonctionnement des intégrations sur différentes versions de plates-formes et états d'exécution.

Nettoyage des données et conversion de type

Ces fonctions gèrent le "prétraitement" des données, en veillant à ce que les variables soient au bon format avant d'être utilisées dans la logique ou envoyées à des API externes.

Fonction	Paramètres	Description et retours
camel_to_snake_case()	string : (str) chaîne camelCase cible.	Renvoie str Convertit les chaînes camelCase ou PascalCase en snake_case. Essentiel pour normaliser les réponses de l'API selon les conventions de dénomination Python.
cast_keys_to_int()	data : dictionnaire avec des clés de chaîne numérique.	Renvoie dict Crée un dictionnaire dans lequel toutes les clés sont converties en entiers. Souvent utilisé lors du traitement de données JSON qui représentent des ID sous forme de chaînes.
clean_result()	value : (str) chaîne cible.	Renvoie str Supprime les espaces de début et de fin. Utilitaire svital permettant de nettoyer les entrées utilisateur à partir des paramètres d'intégration.
none_to_default_value()	value_to_check : (tout) valeur d'entrée. value_to_return_if_none : (Toute valeur) Action de remplacement.	Renvoie Any Vérifie si une valeur est None. Si c'est le cas, renvoie la valeur de remplacement par défaut. Sinon, renvoie la valeur d'origine.
safe_cast_bool_value_from_str()	default_value : (tout) valeur à évaluer.	Renvoie bool | Any Convertit les valeurs booléennes de type chaîne (comme "true") en valeurs booléennes réelles. Renvoie default_value si le casting échoue.
safe_cast_int_value_from_str()	default_value : (tout) valeur à évaluer.	Renvoie int | Any Tente de convertir une valeur en nombre entier. Renvoie default_value si le cast échoue.

Environnement et logique d'exécution

Ces utilitaires permettent aux scripts d'identifier leur contexte d'exécution, par exemple s'ils s'exécutent en tant que test, action asynchrone ou sur une version spécifique de la plate-forme.

Fonction	Paramètres	Description et retours
is_first_run()	sys_argv : (liste) arguments de sys.argv.	Renvoie bool Détermine si une action est exécutée de manière asynchrone pour la première fois. Utilisé pour gérer l'état dans les actions d'interrogation.
is_test_run()	sys_argv : (liste) arguments de sys.argv.	Renvoie bool Indique si le script s'exécute en mode "Test" dans l'IDE. Utilisez-le pour contourner les appels d'API réels pendant le développement.
is_overflowed()	siemplify : (SiemplifyConnectorExecution) alert_info : (AlertInfo) is_test_run : (bool)	Renvoie bool Vérifie si une alerte répond aux critères de dépassement de la plate-forme. Essentiel pour les connecteurs afin d'éviter l'ingestion d'alertes redondantes.
is_python_37()	Aucun	Renvoie bool Vérifie si la version actuelle de Python est au moins la version 3.7. utile pour basculer entre les fonctionnalités de langage anciennes et modernes.
platform_supports_1p_api()	Aucun	Renvoie bool Vérifie si l'instance est compatible avec les API unifiées First-Party (1P). Active la logique de remplacement dynamique pour la compatibilité multiplate-forme.
platform_supports_db()	siemplify : objet SDK (Chronicle SOAR).	Renvoie bool Détermine si l'environnement est compatible avec les DataStreams. Si la valeur est False, l'intégration doit revenir à l'état basé sur les fichiers.

Validation et filtrage des données

Utilitaires permettant d'assurer l'intégrité des données, d'effectuer des opérations sur les ensembles et de récupérer des valeurs à partir de structures JSON complexes.

Fonction	Paramètres	Description et retours
escape_odata_literal()	value : (Any) Valeur brute de la requête.	Renvoie Any Double les guillemets simples dans une chaîne pour la conformité OData. Important : Cela permet d'éviter l'injection de requêtes et les erreurs de syntaxe dans les expressions $filter.
get_unique_items_by_difference()	item_pool : (itérable) éléments sources. items_to_remove : (itérable) liste d'exclusion.	Renvoie list Calcule la différence d'ensemble (Pool - Remove) et renvoie les éléments uniques sous forme de liste. Utile pour filtrer les alertes traitées.
get_value_from_json()	data : (dict) données JSON à rechercher. *keys : (str) Clés de secours ordonnées. default : valeur de remplacement (toute).	Renvoie Any Récupère les valeurs d'un JSON imbriqué à l'aide d'une "cascade" de clés. Renvoie default si aucune des clés n'existe.
is_empty_string_or_none()	data : (str) chaîne à vérifier.	Renvoie bool Renvoie True si l'entrée est None ou ne contient qu'une chaîne vide "". Essentiel pour les vérifications de sécurité sur les réponses de l'API.
is_valid_email()	email_addr : (str) chaîne à vérifier.	Renvoie bool Valide le format d'une adresse e-mail à l'aide d'une expression régulière standard. Utile pour prévalider les paramètres avant les appels d'API externes.
is_valid_uuid()	string : (str) chaîne à vérifier.	Renvoie bool Garantit qu'une chaîne est un UUID version 4 valide. Empêche les erreurs 400 lors de la transmission d'ID aux points de terminaison de la plate-forme.

Utilitaires système et de fichiers

Helpers permettant d'interagir avec le système d'exploitation, de gérer les fichiers temporaires et de traiter les métadonnées des entités.

Fonction	Paramètres	Description et retours
create_and_write_to_tempfile()	content : (str | bytes) Données à écrire.	Renvoie Path Écrit le contenu dans un fichier temporaire sécurisé. Utile pour les actions qui nécessitent de transmettre des données aux outils de ligne de commande.
get_entity_original_identifier()	entity : (entité) objet d'entité cible.	Renvoie str Récupère l'identifiant d'origine d'une entité, ce qui permet de mapper précisément les alertes à leur source.
get_function_arg_names()	func : fonction cible (appelable).	Renvoie list Utilise la réflexion pour récupérer tous les noms d'arguments définis dans une fonction. Essentiel pour créer des wrappers dynamiques.
get_sdk_api_uri()	chronicle_soar : instance SDK (Chronicle SOAR).	Renvoie str Récupère l'URI de l'API de base pour l'environnement actuel. Indispensable pour construire des appels REST personnalisés en dehors des wrappers standards.
safe_json_for_204()	response : (Response) objet de réponse HTTP. default_for_204 : valeur de remplacement (toute).	Renvoie list | dict | Any Gère les réponses 204 (Aucun contenu) de manière sécurisée. Renvoie une liste vide ou la valeur default_for_204 au lieu de planter lors de l'analyse JSON.
temporarily_remove_header()	header_name : (str) En-tête à supprimer.	Renvoie callable Décorateur : supprime temporairement un en-tête (comme 'Prefer') d'une session pour la durée d'un seul appel.