Configurazione di uno spazio dei nomi personalizzato

Gli spazi dei nomi personalizzati fungono da ambienti logici per raggruppare e isolare i moduli di base dei dati e dei prodotti di dati analitici. L'esecuzione all'interno di uno spazio dei nomi personalizzato dedicato consente di gestire le opzioni di configurazione e deployment in modo indipendente, fornendo l'isolamento per l'ambiente. Un vantaggio fondamentale di questa separazione è che puoi estrarre senza problemi aggiornamenti e miglioramenti futuri dallo spazio dei nomi cortex in Google Cloud Cortex Framework senza il rischio di sovrascrivere o danneggiare i tuoi moduli personalizzati. Ti consigliamo vivamente di creare i moduli personalizzati all'interno di uno spazio dei nomi dedicato.

Struttura delle cartelle dello spazio dei nomi personalizzato

Le cartelle dello spazio dei nomi di Cortex Framework vengono utilizzate per creare pacchetti e isolare gli artefatti dei moduli personalizzati. La struttura delle cartelle di uno spazio dei nomi personalizzato è definita nella tabella:

Percorso directory Scopo e descrizione Struttura tipica delle sottocartelle
config/ Configurazione del deployment di Cortex (obbligatorio)
La creazione di nuovi spazi dei nomi richiede la loro configurazione in config.yaml. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ Moduli di base dei dati (facoltativo)
Trasformazioni dei set di dati da grezzi a di base. 
-
src/data_modules/custom_namespace_path/data_product/ Definizioni dei prodotti di dati (facoltativo)
Contiene la logica di business e i modelli analitici. Ogni prodotto è separato in una sottodirectory (ad esempio your_product_name) ed è composto da:
  • Readme: Documentazione del modulo
  • manifest.yaml: dichiara il tipo di builder, le dipendenze e la configurazione.
  • annotations/: Descrizioni a livello di colonna e campo.
  • definitions/: file sorgente SQLX o JS di Dataform.
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ Helper JavaScript (facoltativo)
Tutti i file JavaScript inseriti qui vengono automaticamente inclusi nel pacchetto e resi disponibili per i modelli Dataform durante la compilazione nel percorso dello spazio dei nomi (ad esempio, includes/custom_namespace/). 
-
src/data_modules/custom_namespace_path/common/ Strumenti condivisi dello spazio dei nomi (facoltativo)
Builder, deployer e altri strumenti personalizzati con ambito a livello di spazio dei nomi. 
-

Configurazione personalizzata dello spazio dei nomi

Un nuovo spazio dei nomi: custom_namespace può essere definito estendendo la sezione corrispondente del file config.yaml, creando una nuova directory in src/data_modules/ e aggiungendo i nuovi asset di codice del modulo.

Per rendere il compilatore Google Cloud Cortex Framework consapevole del tuo spazio dei nomi e dei tuoi moduli personalizzati, devi registrarli nel file di configurazione globale (ad es. config/config.yaml).

Passaggio A: registra lo spazio dei nomi

Nel blocco data.namespaces, aggiungi i metadati dello spazio dei nomi:

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/'

Passaggio B: configura i moduli personalizzati

Registra i tuoi moduli personalizzati in data.modules.foundation o data.modules.product. Utilizza il formato separato da punti custom_namespace.module_type per il campo 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"

Codice condiviso dello spazio dei nomi personalizzato

Lo spazio dei nomi personalizzato supporta la condivisione di artefatti di codice tra i suoi moduli. I tipi di artefatto supportati sono:

  • includes: contiene tutti gli helper JavaScript che verranno resi disponibili per gli artefatti Dataform. Possono essere inseriti nella cartella: src/data_modules/custom_namespace_path/includes/.
  • builder: qualsiasi classe di generatori personalizzati che può compilare il codice sorgente del modulo in artefatti Dataform. Possono essere inseriti in src/data_modules/custom_namespace_path/common/.

Comprendere e fare riferimento ai builder

I builder sono classi generatore Python che compilano i file di origine del modulo in output Dataform fisici. Google Cloud Cortex Framework compila i moduli utilizzando una sequenza di risoluzione del builder a tre livelli flessibile:

Sequenza di risoluzione dei builder di estensibilità di Google Cloud Cortex Framework

Figura 1. Sequenza di risoluzione dei builder di estensibilità di Cortex Framework.

Livello 1: costruttori di fallback globali

Il framework include generatori molto robusti che si trovano in src/common/builders/. Questi generatori sono registrati a livello globale e possono essere utilizzati da qualsiasi spazio dei nomi personalizzato.

Ad esempio, per utilizzare i generatori di prodotti di dati SAP standard per il tuo prodotto personalizzato, fai riferimento a sap_product in 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

Livello 2: builder con ambito a livello di spazio dei nomi

Se i moduli all'interno dello spazio dei nomi personalizzato richiedono un compilatore specializzato, puoi registrare un builder personalizzato per lo spazio dei nomi.

  1. Crea un file builder in src/data_modules/custom_namespace_path/common/builders/my_builder.py.

  2. Decora la tua classe di builder con @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. Fai riferimento a questo elemento nella manifest.yaml del tuo prodotto utilizzando builder: my_builder.

Livello 3: builder a livello di singolo prodotto

Per le pipeline altamente uniche, puoi definire un builder con ambito esclusivo per un singolo prodotto di dati.

  1. Basta creare un file denominato builder.py direttamente all'interno della cartella del prodotto di dati (ad es. src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py).

  2. Definisci una sottoclasse di BaseBuilder o ProductBuilder al suo interno:

   from common.builders.base import ProductBuilder

   class UniqueSalesPerformanceBuilder(ProductBuilder):
       # Implement unique build logic here...
  1. Il compilatore importerà ed eseguirà automaticamente questa classe in modo dinamico senza richiedere alcuna registrazione o decoratore.

Esempio di spazio dei nomi personalizzato

Nel file config/config.yaml, aggiungi questo blocco sotto 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/'

Nei passaggi successivi, Creazione del modulo della base di dati e Creazione del modulo del prodotto di dati, imparerai ad aggiungere moduli di dati allo spazio dei nomi.