Configurer un espace de noms personnalisé

Les espaces de noms personnalisés servent d'environnements logiques pour empaqueter et isoler votre base de données et vos modules 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 de manière transparente 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 dossiers d'un espace de noms personnalisé

Les dossiers d'espace de noms de Cortex Framework sont utilisés pour empaqueter 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 de Cortex (obligatoire)
La création d'espaces de noms nécessite leur configuration dans config.yaml.
src/data_modules/custom_namespace_path/data_foundation/data_foundation_module_type Modules de base de données
Transformations des ensembles de données bruts en base de données. 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_path/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 sources Dataform SQLX ou JS.
src/data_modules/custom_namespace_path/includes/ Assistants 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_path/common/ Outils partagés de l'espace de noms
Compilateurs, déployeurs et autres outils personnalisés au niveau de l'espace de noms.

Configuration d'un espace de noms personnalisé

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 éléments 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 séparé par des points custom_namespace.module_type pour le champ type :

data:
  modules:
    foundation:
      - moduleId:  custom_namespace_foundation_module
        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_module
        type: custom_namespace.data_product_module_type # Format: <namespace>.<module_type>
        dependsOn:
          sapModule: custom_namespace_foundation_module # References an existing foundation moduleId 
        dataTargetId: product_target
        tableSettings: "config/custom_namespace_path/data_product/data_product_module_type/table_settings.yaml"

Code partagé d'un espace de noms personnalisé

L'espace de noms personnalisé permet de partager des artefacts de code entre ses modules. Les types d'artefacts compatibles sont les suivants :

  • includes : contient tous les assistants 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 : toutes les classes de générateur personnalisées qui peuvent compiler le code source de votre module en artefacts Dataform. Elles peuvent être placées dans src/data_modules/custom_namespace_path/common/.

Comprendre et référencer les compilateurs

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 :

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

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

Niveau 1 : Compilateurs de secours globaux

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

Par exemple, pour utiliser les compilateurs 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_path/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 : Compilateurs au niveau 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...

  3. Référencez-la dans le manifest.yaml de votre produit à l'aide de builder: my_builder.

Niveau 3 : Compilateurs au niveau des produits individuels

Pour les pipelines très spécifiques, vous pouvez définir un compilateur limité exclusivement à 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_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 importe et exécute 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.