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é.

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 Structure de sous-dossiers typique
config/ Configuration du déploiement Cortex (obligatoire)
La création d'espaces de noms nécessite leur configuration dans config.yaml. 
config/config.yaml
src/data_modules/custom_namespace_path/data_foundation/ Modules de base de données (facultatif)
Transformations des ensembles de données brutes en ensembles de données de base. 
-
src/data_modules/custom_namespace_path/data_product/ Définitions des produits de données (facultatif)
Contient la logique métier et les modèles analytiques. Chaque produit est séparé dans un sous-répertoire (par exemple, your_product_name) 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.
  • annotations/ : descriptions au niveau des colonnes et des champs.
  • definitions/ : fichiers source Dataform SQLX ou JS.
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ Helpers JavaScript (facultatif)
Tous les fichiers JavaScript placés ici sont automatiquement regroupé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_path/common/ Outils partagés de l'espace de noms (facultatif)
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_path/  # <-- 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_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"

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_path/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_path/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 physiques. Google Cloud Cortex Framework compile les modules à l'aide d'une séquence de résolution de compilateur à trois niveaux flexible :

Séquence de résolution des créateurs d&#39;extensibilité Google Cloud Cortex Framework

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 standards de création de produits de données SAP pour votre produit personnalisé, référencez sap_product dans votre 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

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_path/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...
  1. 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_path/data_product/data_product_id/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...
  1. Le compilateur importera et exécutera automatiquement cette classe de manière dynamique, sans nécessiter d'enregistrement ni de décorateurs.

Exemple d'espace de noms personnalisé

Dans le fichier config/config.yaml, ajoutez le bloc suivant sous 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/'

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.