TIPCommon.utils

Il modulo TIPCommon.utils funge da toolkit di base per gli sviluppatori di integrazioni. Fornisce helper essenziali per la manipolazione delle stringhe, il casting sicuro dei tipi, la costruzione di query OData e controlli specifici dell'ambiente per garantire che le integrazioni funzionino senza problemi su diverse versioni della piattaforma e stati di esecuzione.

Pulizia dei dati e conversione del tipo

Queste funzioni gestiscono il "pre-processing" dei dati, assicurando che le variabili siano nel formato corretto prima di essere utilizzate nella logica o inviate ad API esterne.

Funzione	Parametri	Descrizione e resi
camel_to_snake_case()	string: (str) Stringa camelCase di destinazione.	Resi: str Converte le stringhe camelCase o PascalCase in snake_case. Essenziale per normalizzare le risposte dell'API in base alle convenzioni di denominazione Pythonic.
cast_keys_to_int()	data: (dict) Dizionario con chiavi stringa numeriche.	Resi: dict Crea un nuovo dizionario in cui tutte le chiavi vengono convertite in numeri interi. Spesso utilizzato quando si elaborano dati JSON che rappresentano ID come stringhe.
clean_result()	value: (str) Stringa di destinazione.	Resi: str Rimuove gli spazi vuoti iniziali e finali. Un'utilità essenziale per la pulizia dell'input utente dai parametri di integrazione.
none_to_default_value()	value_to_check: (qualsiasi) valore di input. value_to_return_if_none: (qualsiasi) fallback.	Resi: Any Controlla se un valore è None. In caso affermativo, restituisce il fallback predefinito; in caso contrario, restituisce il valore originale.
safe_cast_bool_value_from_str()	default_value: (qualsiasi) il valore da valutare.	Resi: bool | Any Converte i valori booleani delle stringhe (ad esempio "true") in valori booleani effettivi. Restituisce default_value se la trasmissione non va a buon fine.
safe_cast_int_value_from_str()	default_value: (qualsiasi) il valore da valutare.	Resi: int | Any Tenta di eseguire il cast di un valore in un numero intero. Restituisce default_value se il cast non va a buon fine.

Ambiente e logica di esecuzione

Queste utilità consentono agli script di identificare il contesto di runtime, ad esempio se vengono eseguiti come test, come azione asincrona o su una versione specifica della piattaforma.

Funzione	Parametri	Descrizione e resi
is_first_run()	sys_argv: (elenco) Argomenti di sys.argv.	Resi: bool Determina se un'azione viene eseguita in modo asincrono per la prima volta. Utilizzato per gestire lo stato nelle azioni di polling.
is_test_run()	sys_argv: (elenco) Argomenti di sys.argv.	Resi: bool Identifica se lo script è in esecuzione in modalità "Test" all'interno dell'IDE. Utilizza questo per ignorare le chiamate API reali durante lo sviluppo.
is_overflowed()	siemplify: (SiemplifyConnectorExecution) alert_info: (AlertInfo) is_test_run: (booleano)	Resi: bool Controlla se un avviso soddisfa i criteri di overflow della piattaforma. Essenziale per i connettori per evitare l'importazione di avvisi ridondanti.
is_python_37()	Nessuno	Resi: bool Controlla se la versione attuale di Python è almeno la 3.7. Utile per alternare le funzionalità di linguaggio legacy e moderne.
platform_supports_1p_api()	Nessuno	Resi: bool Verifica se l'istanza supporta le API unificate proprietarie (1P). Consente una logica di fallback dinamica per il supporto multipiattaforma.
platform_supports_db()	siemplify: oggetto SDK (ChronicleSOAR).	Resi: bool Determina se l'ambiente supporta DataStreams. Se False, l'integrazione deve tornare allo stato basato su file.

Convalida e filtro dei dati

Utilità per garantire l'integrità dei dati, eseguire operazioni sugli insiemi e recuperare valori da strutture JSON complesse.

Funzione	Parametri	Descrizione e resi
escape_odata_literal()	value: (Qualsiasi) Il valore della query non elaborata.	Resi: Any Raddoppia le virgolette singole in una stringa per la conformità a OData. Importante:in questo modo si impediscono l'inserimento di query e gli errori di sintassi nelle espressioni $filter.
get_unique_items_by_difference()	item_pool: (Iterable) Gli elementi di origine. items_to_remove: (Iterable) Elenco di esclusione.	Resi: list Calcola la differenza tra gli insiemi (Pool - Remove) e restituisce gli elementi unici come un elenco. Utile per filtrare gli avvisi elaborati.
get_value_from_json()	data: (dict) dati JSON da cercare. *keys: (str) Chiavi di riserva ordinate. default: (Qualsiasi) Valore di riserva.	Resi: Any Recupera i valori dal JSON nidificato utilizzando una "cascata" di chiavi. Restituisce default se nessuna delle chiavi esiste.
is_empty_string_or_none()	data: (str) Stringa da controllare.	Resi: bool Restituisce True se l'input è None o contiene solo una stringa vuota "". Essenziale per i controlli di sicurezza sulle risposte API.
is_valid_email()	email_addr: (str) Stringa da controllare.	Resi: bool Convalida un formato di indirizzo email utilizzando l'espressione regolare standard. Utile per la pre-validazione dei parametri prima delle chiamate API esterne.
is_valid_uuid()	string: (str) Stringa da controllare.	Resi: bool Garantisce che una stringa sia un UUID versione 4 valido. Evita errori 400 quando passi ID agli endpoint della piattaforma.

Utilità di sistema e file

Helper per interagire con il sistema operativo, gestire i file temporanei e gestire i metadati delle entità.

Funzione	Parametri	Descrizione e resi
create_and_write_to_tempfile()	content: (str | bytes) Dati da scrivere.	Resi: Path Scrive i contenuti in un file temporaneo sicuro. Utile per le azioni che richiedono il trasferimento di dati agli strumenti a riga di comando.
get_entity_original_identifier()	entity: (entità) oggetto entità di destinazione.	Resi: str Recupera l'identificatore originale per un'entità, garantendo una mappatura accurata degli avvisi di origine.
get_function_arg_names()	func: (richiamabile) Funzione di destinazione.	Resi: list Utilizza la reflection per recuperare tutti i nomi degli argomenti definiti in una funzione. Essenziale per la creazione di wrapper dinamici.
get_sdk_api_uri()	chronicle_soar: istanza dell'SDK (ChronicleSOAR).	Resi: str Recupera l'URI di base dell'API per l'ambiente corrente. Fondamentale per creare chiamate REST personalizzate al di fuori dei wrapper standard.
safe_json_for_204()	response: (Response) Oggetto risposta HTTP. default_for_204: (Qualsiasi) Valore di riserva.	Resi: list | dict | Any Gestisce in modo sicuro le risposte 204 (nessun contenuto). Restituisce un elenco vuoto o il valore default_for_204 anziché arrestarsi in modo anomalo durante l'analisi JSON.
temporarily_remove_header()	header_name: (str) Intestazione da eliminare.	Resi: callable Decoratore:rimuove temporaneamente un'intestazione (ad esempio 'Prefer') da una sessione per la durata di una singola chiamata.