Configurer un espace de noms personnalisé

Les espaces de noms personnalisés servent d'environnements logiques pour regrouper et isoler vos modules de base de données et de produits de données analytiques. L'exécution dans un espace de noms personnalisé dédié vous permet de gérer les options de configuration et de déploiement de manière indépendante, ce qui isole votre environnement. L'un des principaux avantages de cette séparation est que vous pouvez extraire facilement les futures mises à jour et améliorations de l'espace de noms cortex dans Google Cloud Cortex Framework sans risquer de remplacer ou de corrompre vos modules personnalisés. Nous vous recommandons vivement de créer vos modules personnalisés dans un espace de noms dédié.

Remarque : Un espace de noms peut contenir plusieurs modules de data foundation et de data product.

Structure de dossier d'espace de noms personnalisé

Les dossiers d'espace de noms du Cortex Framework sont utilisés pour regrouper et isoler les artefacts de modules personnalisés. La structure de dossiers d'un espace de noms personnalisé est définie dans le tableau suivant :

Chemin d'accès au répertoire	Objectif et description
config/	Configuration du déploiement Cortex (obligatoire) La création d'espaces de noms nécessite leur configuration dans config.yaml.
src/data_modules/custom_namespace/data_foundation/data_foundation_module_type	Modules de base de données Transformations des ensembles de données bruts en ensembles de données de base. Chaque base de données est séparée dans un sous-répertoire et se compose des éléments suivants : annotations/ : descriptions au niveau des colonnes et des champs. table_settings.default.yaml : configuration des paramètres de table
src/data_modules/custom_namespace/data_product/data_product_module_type	Définitions des produits de données Contient la logique métier et les modèles analytiques. Chaque produit est séparé dans un sous-répertoire et se compose des éléments suivants : Readme : documentation du module manifest.yaml : déclare le type de compilateur, les dépendances et la configuration. table_settings.default.yaml : configuration des paramètres de table annotations/ : descriptions au niveau des colonnes et des champs. definitions/ : fichiers source Dataform SQLX ou JS.
src/data_modules/custom_namespace/includes/	Helpers JavaScript Tous les fichiers JavaScript placés ici sont automatiquement empaquetés et mis à la disposition de vos modèles Dataform lors de la compilation sous le chemin d'accès de l'espace de noms (par exemple, includes/custom_namespace/).
src/data_modules/custom_namespace/common/	Outils partagés dans l'espace de noms Builders, déployeurs et autres outils personnalisés à l'échelle de l'espace de noms.

Configuration personnalisée de l'espace de noms

Un nouvel espace de noms : custom_namespace peut être défini en étendant la section correspondante du fichier config.yaml, en créant un répertoire sous src/data_modules/ et en ajoutant les nouveaux composants de code du module.

Pour que le compilateur Google Cloud Cortex Framework reconnaisse votre espace de noms et vos modules personnalisés, vous devez les enregistrer dans votre fichier de configuration global (par exemple, config/config.yaml).

Étape A : Enregistrer l'espace de noms

Sous le bloc data.namespaces, ajoutez les métadonnées de votre espace de noms :

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

Étape B : Configurer des modules personnalisés

Enregistrez vos modules personnalisés sous data.modules.foundation ou data.modules.product. Utilisez le format custom_namespace.module_type avec des points de séparation pour le champ type :

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_data_foundation_module_type
        type: custom_namespace.sap   # Format: <namespace>.<module_type>
        dataSourceId: sap_raw_s4
        dataTargetId: data_foundation_sap_custom_namespace
        moduleSettings:
          sapVersion: s4
          mandt: "100"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/table_settings.default.yaml"
        # Custom table settings file, relative to 'config/' directory
        tableSettings: "custom_namespace/data_foundation/data_foundation_module_type/table_settings.yaml"
        
    product:
      - moduleId: custom_namespace_data_product_module_type
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_data_foundation_module_type # References an existing foundation moduleId 
        dataTargetId: product_target
        # Custom table settings file, relative to 'config/' directory
        # tableSettings: "custom_namespace/data_product/data_product_module_type/table_settings.yaml"
        # Default table settings file, relative to configuration file directory
        # tableSettings: "../src/data_modules/custom_namespace/data_product/data_product_module_type/table_settings.default.yaml"

Remarque : data_foundation_module_type et data_product_module_type sont techniquement des chaînes nettoyées du nom du module (en minuscules, avec les caractères spéciaux et les espaces remplacés par des traits de soulignement). Doit correspondre à l'attribut type: dans le fichier src/data_modules/custom_namespace/data_foundation/data_foundation_module_type/manifest.yaml ou src/data_modules/custom_namespace/data_product/data_product_module_type/manifest.yaml.

Code partagé de l'espace de noms personnalisé

L'espace de noms personnalisé permet de partager des artefacts de code entre ses modules. Voici les types d'artefacts acceptés :

• includes : contient tous les helpers JavaScript qui seront mis à la disposition de vos artefacts Dataform. Ils peuvent être placés dans le dossier : src/data_modules/custom_namespace/includes/.
• Builders : classes de générateur personnalisées qui peuvent compiler le code source de votre module en artefacts Dataform. Ils peuvent être placés dans src/data_modules/custom_namespace/common/.

Comprendre les créateurs et les référencer

Les compilateurs sont des classes de générateur Python qui compilent les fichiers sources de votre module en sorties Dataform. Google Cloud Cortex Framework compile les modules à l'aide d'une séquence de résolution de compilateur à trois niveaux flexible :

Figure 1. Séquence de résolution des créateurs d'extensibilité Cortex Framework.

Niveau 1 : Générateurs de remplacement global

Le framework inclut des compilateurs très robustes situés dans src/common/builders/. Ces générateurs sont enregistrés globalement et peuvent être utilisés par n'importe quel espace de noms personnalisé.

Par exemple, pour utiliser les outils de création de produits de données SAP standards pour votre produit de données personnalisé, référencez sap_product dans votre manifest.yaml :

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

Niveau 2 : Générateurs à l'échelle de l'espace de noms

Si les modules de votre espace de noms personnalisé nécessitent un compilateur spécialisé, vous pouvez enregistrer un compilateur personnalisé pour cet espace de noms.

1. Créez un fichier de compilateur sous src/data_modules/custom_namespace/common/builders/my_builder.py.

2. Décorez votre classe de compilateur avec @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...
   

3. Faites-y référence dans le fichier manifest.yaml de votre produit à l'aide de builder: my_builder.

Niveau 3 : Outils de création au niveau des produits individuels

Pour les pipelines très spécifiques, vous pouvez définir un compilateur exclusivement pour un seul produit de données.

1. Il vous suffit de créer un fichier nommé builder.py directement dans le dossier de votre produit de données (par exemple, src/data_modules/custom_namespace/data_product/data_product_module_type/builder.py).

2. Définissez une sous-classe de BaseBuilder ou ProductBuilder à l'intérieur :

    from common.builders.base import ProductBuilder
   
    class UniqueSalesPerformanceBuilder(ProductBuilder):
        # Implement unique build logic here...
   

3. Le compilateur importera et exécutera automatiquement cette classe de manière dynamique, sans nécessiter d'enregistrement ni de décorateurs.

Dans les étapes suivantes, Créer un module de base de données et Créer un module de produit de données, vous apprendrez à ajouter des modules de données à l'espace de noms.

---

• Étape suivante : Créer un module de base de données
• Retour à Présentation