הגדרה של מרחב שמות בהתאמה אישית

מרחבי שמות בהתאמה אישית משמשים כסביבות לוגיות לאריזה ולבידוד של מודולים של בסיס הנתונים ושל מוצרי נתונים אנליטיים. ההרצה בתוך מרחב שמות ייעודי בהתאמה אישית מאפשרת לכם לנהל את אפשרויות ההגדרה והפריסה באופן עצמאי, ומספקת בידוד לסביבה שלכם. אחד היתרונות העיקריים של ההפרדה הזו הוא שאתם יכולים לשלוף בצורה חלקה עדכונים ושיפורים עתידיים ממרחב השמות cortex ב-Google Cloud Cortex Framework בלי הסיכון להחלפה או להשחתה של המודולים בהתאמה אישית. מומלץ מאוד ליצור את המודולים המותאמים אישית במרחב שמות ייעודי.

מבנה תיקיות של מרחב שמות בהתאמה אישית

התיקיות במרחב השמות של Cortex Framework משמשות לאריזה ולבידוד של ארטיפקטים של מודולים בהתאמה אישית. מבנה התיקיות של מרחב שמות מותאם אישית מוגדר בטבלה:

נתיב הספרייה מטרה ותיאור מבנה אופייני של תיקיות משנה
config/ הגדרת הפריסה של Cortex (חובה)
כדי ליצור מרחבי שמות חדשים, צריך להגדיר אותם ב-config.yaml. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ מודולים של שכבת הבסיס לנתונים (אופציונלי)
טרנספורמציות של מערכי נתונים מנתונים גולמיים לשכבת הבסיס. 
-
src/data_modules/custom_namespace_path/data_product/ הגדרות של מוצרי נתונים (אופציונלי)
כולל לוגיקה עסקית ומודלים אנליטיים. כל מוצר מופרד בספריית משנה (לדוגמה, your_product_name) ומורכב מהרכיבים הבאים:
  • ‫Readme: תיעוד של המודול
  • ‫manifest.yaml: מגדיר את סוג ה-builder, התלויות וההגדרה.
  • ‫annotations/: תיאורים ברמת העמודה והשדה.
  • ‫definitions/: קובצי מקור של Dataform SQLX או JS.
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ JavaScript helpers (אופציונלי)
כל קובצי ה-JavaScript שמוצבים כאן נארזים אוטומטית וזמינים למודלים של Dataform במהלך ההידור (compilation) בנתיב של מרחב השמות (לדוגמה, includes/custom_namespace/). 
-
src/data_modules/custom_namespace_path/common/ כלים משותפים במרחב שמות (אופציונלי)
כלים מותאמים אישית לבנייה, לפריסה ולמטרות אחרות, שמוגבלים למרחב השמות. 
-

הגדרת מרחב שמות בהתאמה אישית

מרחב שמות חדש: custom_namespace אפשר להגדיר אותו על ידי הרחבת הקטע המתאים בקובץ config.yaml, יצירת ספרייה חדשה ב-src/data_modules/ והוספת נכסי קוד המודול החדש.

כדי שהקומפיילר של Google Cloud Cortex Framework יזהה את מרחב השמות והמודולים המותאמים אישית שלכם, אתם צריכים לרשום אותם בקובץ ההגדרות הגלובלי (לדוגמה, config/config.yaml).

שלב א': רישום מרחב השמות

בקטע data.namespaces block, מוסיפים את המטא-נתונים של מרחב השמות:

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name:  custom_namespace    # <-- Name of custom namespace
      path:  custom_namespace_path/  # <-- Folder name that is used for custom namespace, points to subdirectory of 'src/data_modules/'

שלב ב': הגדרת מודולים בהתאמה אישית

רושמים את המודולים המותאמים אישית בקטע data.modules.foundation או data.modules.product. בשדה type צריך להשתמש בפורמט custom_namespace.module_type עם נקודות בין המספרים:

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_foundation_module_id
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        tableSettings: "config/custom_namespace_path/data_foundation/sap/table_settings.yaml"

    product:
      - moduleId: custom_namespace_data_product_id
        type: custom_namespace.data_product_id  # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: erp_ecc            # References an existing foundation moduleId
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_id/table_settings.yaml"

קוד משותף של מרחב שמות בהתאמה אישית

מרחב השמות המותאם אישית תומך בשיתוף ארטיפקטים של קוד בין המודולים שלו. סוגי הארטיפקטים הנתמכים הם:

  • ‫includes – מכיל עזרים של JavaScript שיהיו זמינים לארטיפקטים של Dataform. אפשר למקם אותם בתיקייה: src/data_modules/custom_namespace_path/includes/.
  • ‫builders – כל מחלקות הגנרטורים בהתאמה אישית שיכולות לקמפל את קוד המקור של המודול לארטיפקטים של Dataform. אפשר למקם אותם בsrc/data_modules/custom_namespace_path/common/.

הסבר על כלים ליצירת אפליקציות ואיך משתמשים בהם

קלאסים של גנרטורים ב-Python שמהדרים את קובצי המקור של המודול לפלט פיזי של Dataform. ‫Google Cloud Cortex Framework קומפל מודולים באמצעות רצף גמיש של פתרונות לבנייה בשלוש שכבות:

רצף הפעולות של כלי הבנייה להרחבת Google Cloud Cortex Framework

איור 1. רצף הפתרון של כלי בנייה להרחבת Cortex Framework.

רמה 1: builders גלובליים לגיבוי

המסגרת כוללת כלי בנייה חזקים מאוד שנמצאים ב-src/common/builders/. ה-Builders האלה רשומים באופן גלובלי ואפשר להשתמש בהם בכל מרחב שמות מותאם אישית.

לדוגמה, כדי להשתמש בכלי הסטנדרטיים של SAP ליצירת מוצרי נתונים עבור המוצר המותאם אישית שלכם, צריך להפנות אל sap_product ב-manifest.yaml:

# src/data_modules/custom_namespace_path/data_product/data_product_id/manifest.yaml
type: data_product_id
builder: sap_product     # Automatically resolves to the global SapProductBuilder fallback
dependencies:
  sapModule:
    type: sap
    supportedVersions:
      - ecc
      - s4

רמה 2: כלי בנייה בהיקף של מרחב שמות

אם מודולים במרחב השמות המותאם אישית שלכם דורשים קומפיילר מיוחד, אתם יכולים לרשום builder מותאם אישית למרחב השמות הזה.

  1. יוצרים קובץ builder בתיקייה src/data_modules/custom_namespace_path/common/builders/my_builder.py.

  2. מקשטים את מחלקת ה-builder באמצעות @builder_registry.register("my_builder") :

   from common.builders.base import ProductBuilder
   from common.registry import builder_registry

   @builder_registry.register("my_builder")
   class MyCustomProductBuilder(ProductBuilder):
       # Implement build logic here...
  1. אפשר להפנות אליו בmanifest.yaml המוצר באמצעות builder: my_builder.

רמה 3: יוצרים ברמת המוצר הבודד

בצינורות ייחודיים מאוד, אפשר להגדיר בונה שמוגבל לשימוש בלעדי במוצר נתונים יחיד.

  1. פשוט יוצרים קובץ בשם builder.py ישירות בתוך תיקיית מוצר הנתונים (למשל, src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py).

  2. מגדירים מחלקת משנה של BaseBuilder או ProductBuilder בתוך המחלקה:

   from common.builders.base import ProductBuilder

   class UniqueSalesPerformanceBuilder(ProductBuilder):
       # Implement unique build logic here...
  1. הקומפיילר ייבא ויבצע את המחלקה הזו באופן דינמי באופן אוטומטי, בלי שיידרש רישום או שימוש בדקורטורים.

דוגמה למרחב שמות בהתאמה אישית

בקובץ config/config.yaml, מוסיפים את הבלוק הזה מתחת ל-data.namespaces:

data:
  namespaces:
    - name: cortex
      path: cortex/
    - name: sap_bookingdatamodel # <-- Name of custom namespace: sap_bookingdatamodel
      path: sap_bookingdatamodel/  # <-- Folder name that is used for custom namespace:sap_bookingdatamodel, points to subdirectory of 'src/data_modules/'

בשלבים הבאים: יצירת מודול של שכבת בסיס נתונים ויצירת מודול של מוצר נתונים, נסביר איך להוסיף מודולים של נתונים למרחב השמות.