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) מילון עם מפתחות מחרוזת נומריים.	החזרות: dict יוצר מילון חדש שבו כל המפתחות מומרים למספרים שלמים. משמש לעיתים קרובות כשמעבדים נתוני JSON שמייצגים מזהים כמחרוזות.
clean_result()	‫value: (str) מחרוזת היעד.	החזרות: str מסירה רווחים לבנים בתחילת הטקסט ובסופו. כלי svital לניקוי קלט של משתמשים מפרמטרים של שילוב.
none_to_default_value()	‫value_to_check: (כל) ערך קלט. ‫value_to_return_if_none: (Any) Fallback.	החזרות: 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: (רשימה) ארגומנטים מ-sys.argv.	החזרות: bool הפונקציה קובעת אם פעולה מבוצעת באופן אסינכרוני בפעם הראשונה. משמש לניהול מצב בפעולות של שליחת בקשות.
is_test_run()	‫sys_argv: (רשימה) ארגומנטים מ-sys.argv.	החזרות: bool הפונקציה מזהה אם הסקריפט פועל במצב Test (בדיקה) בסביבת הפיתוח המשולבת (IDE). אפשר להשתמש בזה כדי לעקוף קריאות אמיתיות ל-API במהלך הפיתוח.
is_overflowed()	‫siemplify: (SiemplifyConnectorExecution) alert_info: (AlertInfo) ‫is_test_run: (bool)	החזרות: bool הפונקציה בודקת אם התראה עומדת בקריטריונים של הפלטפורמה לגבי חריגה. חיוני למחברים כדי למנוע קליטה מיותרת של התראות.
is_python_37()	ללא	החזרות: bool הפונקציה בודקת אם גרסת Python הנוכחית היא לפחות 3.7. היא שימושית למעבר בין תכונות שפה מדור קודם לתכונות שפה מודרניות.
platform_supports_1p_api()	ללא	החזרות: bool בודקת אם המופע תומך בממשקי API מאוחדים של צד ראשון (1P). ההגדרה הזו מאפשרת לוגיקה דינמית של גיבוי לתמיכה בכמה פלטפורמות.
platform_supports_db()	‫siemplify: אובייקט SDK ‏(ChronicleSOAR).	החזרות: bool הפונקציה קובעת אם הסביבה תומכת ב-DataStreams. אם False, השילוב צריך לחזור למצב מבוסס-קובץ.

אימות וסינון נתונים

כלי עזר להבטחת תקינות הנתונים, לביצוע פעולות על קבוצות ולאחזור ערכים ממבני JSON מורכבים.

תפקיד	פרמטרים	תיאור והחזרות
escape_odata_literal()	‫value: (Any) הערך הגולמי של השאילתה.	החזרות: Any מכפילה גרשיים בודדים במחרוזת לצורך תאימות ל-OData. חשוב: הפעולה הזו מונעת הזרקת שאילתות ושגיאות תחביר בביטויי $filter.
get_unique_items_by_difference()	‫item_pool: (Iterable) פריטי המקור. ‫items_to_remove: (Iterable) רשימת החרגה.	החזרות: list מחשבת את ההפרש בין שתי קבוצות (Pool - Remove) ומחזירה פריטים ייחודיים כרשימה. האפשרות הזו שימושית לסינון התראות שעברו עיבוד.
get_value_from_json()	‫data: (dict) נתוני JSON לחיפוש. ‫*keys: (str) מפתחות חלופיים מסודרים. default: (Any) ערך ברירת מחדל.	החזרות: Any שולף ערכים מ-JSON מוטמע באמצעות 'מפל' של מפתחות. הפונקציה מחזירה את הערך default אם אף אחד מהמפתחות לא קיים.
is_empty_string_or_none()	‫data: (str) המחרוזת שרוצים לבדוק.	החזרות: bool הפונקציה מחזירה True אם הקלט הוא None או אם הוא מכיל רק מחרוזת ריקה "". חיוני לבדיקות בטיחות בתגובות של API.
is_valid_email()	‫email_addr: (str) מחרוזת לבדיקה.	החזרות: bool מאמת את הפורמט של כתובת אימייל באמצעות ביטוי רגולרי רגיל. שימושי לאימות מראש של פרמטרים לפני קריאות ל-API חיצוני.
is_valid_uuid()	‫string: (str) המחרוזת שרוצים לבדוק.	החזרות: bool הפונקציה מוודאת שמחרוזת היא UUID תקין בגרסה 4. מונע שגיאות 400 כשמעבירים מזהים לנקודות קצה של פלטפורמות.

כלי מערכת וקבצים

עוזרים ליצירת אינטראקציה עם מערכת ההפעלה, לניהול קבצים זמניים ולטיפול במטא-נתונים של ישויות.

תפקיד	פרמטרים	תיאור והחזרות
create_and_write_to_tempfile()	‫content: (str | bytes) הנתונים לכתיבה.	החזרות: Path כותב תוכן לקובץ זמני מאובטח. שימושי לפעולות שנדרש בהן העברת נתונים לכלי שורת פקודה.
get_entity_original_identifier()	‫entity: (ישות) אובייקט של ישות יעד.	החזרות: str הפונקציה מאחזרת את המזהה המקורי של ישות, כדי להבטיח מיפוי מדויק בחזרה להתראות המקוריות.
get_function_arg_names()	‫func: (Callable) פונקציית היעד.	החזרות: list הפונקציה משתמשת ברפלקציה כדי לאחזר את כל שמות הארגומנטים שמוגדרים בפונקציה. חיוני ליצירת עטיפות דינמיות.
get_sdk_api_uri()	‫chronicle_soar: מופע SDK ‏(ChronicleSOAR).	החזרות: str מחזירה את ה-URI הבסיסי של ה-API עבור הסביבה הנוכחית. חיוני לבניית קריאות API מותאמות אישית ל-REST מחוץ לעטיפות סטנדרטיות.
safe_json_for_204()	‫response: (תגובה) אובייקט תגובת HTTP. default_for_204: (Any) ערך ברירת מחדל.	החזרות: list | dict | Any מטפל בבטחה בתשובות עם קוד 204 (אין תוכן). מחזירה רשימה ריקה או את הערך default_for_204 במקום לקרוס במהלך ניתוח JSON.
temporarily_remove_header()	‫header_name: (str) הכותרת להשבתה.	החזרות: callable Decorator: מסיר באופן זמני כותרת (כמו 'Prefer') מסשן למשך שיחה אחת.