設定自訂命名空間

自訂命名空間可做為邏輯環境，用來封裝及隔離資料基礎和分析資料產品模組。在專屬的自訂命名空間中執行，可讓您獨立管理設定和部署選項，為環境提供隔離功能。這種分離式設計的一大優點是，您可以從 Google Cloud Cortex Framework 的 cortex 命名空間無縫提取未來的更新和強化功能，不必擔心覆寫或損毀自訂模組。強烈建議您在專屬命名空間中建立自訂模組。

自訂命名空間資料夾結構

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：宣告建構工具類型、依附元件和設定。
  • annotations/：欄位和欄位層級的說明。
  • definitions/：Dataform SQLX 或 JS 來源檔案。
 
data_product/
└── your_product_name/
    ├── README.md
    ├── manifest.yaml
    ├── annotations/
    └── definitions/
src/data_modules/custom_namespace_path/includes/ JavaScript 輔助程式 (選用)
放置於此的任何 JavaScript 檔案都會自動封裝，並在編譯期間透過命名空間路徑 (例如 includes/custom_namespace/) 提供給 Dataform 模型。 
-
src/data_modules/custom_namespace_path/common/ 命名空間共用工具 (選用)
命名空間範圍內的自訂建構工具、部署工具和其他工具。 
-

自訂命名空間設定

新的命名空間：您可以擴充 config.yaml 檔案的對應部分，在 src/data_modules/ 下建立新目錄，並新增模組程式碼資產，藉此定義 custom_namespace。

如要讓 Google Cloud Cortex Framework 編譯器瞭解您的自訂命名空間和模組，您必須在全域設定檔 (例如 config/config.yaml) 中註冊這些項目。

步驟 A：註冊命名空間

在 data.namespaces 區塊下方新增命名空間中繼資料：

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

步驟 B：設定自訂模組

在 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 - 包含可供 Dataform 構件使用的 JavaScript 輔助程式。這些檔案可以放在「src/data_modules/custom_namespace_path/includes/」資料夾中。
  • 建構工具 - 任何可將模組原始碼編譯為 Dataform 構件的自訂產生器類別。可放置在 src/data_modules/custom_namespace_path/common/ 中。

瞭解及參照建構工具

建構工具是 Python 產生器類別，可將模組來源檔案編譯為實際的 Dataform 輸出內容。Google Cloud Cortex Framework 會使用彈性的三層建構工具解析順序編譯模組：

Google Cloud Cortex Framework 擴充性建構工具解決順序

圖 1：Cortex Framework 可擴充性建構工具的解析順序。

第 1 層：全球備援建構工具

這個架構包含 src/common/builders/ 中非常強大的建構工具。這些建構函式會在全域註冊，且可供任何自訂命名空間使用。

舉例來說，如要為自訂產品使用標準 SAP 資料產品建構工具，請在 manifest.yaml中參照 sap_product：

# 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 層：命名空間範圍內的建構函式

如果自訂命名空間內的模組需要專用編譯器，您可以為該命名空間註冊自訂建構工具。

  1. 在 src/data_modules/custom_namespace_path/common/builders/my_builder.py 下建立建構工具檔案。

  2. 使用 @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. 只要在資料產品資料夾 (例如 src/data_modules/custom_namespace_path/data_product/data_product_id/builder.py) 內建立名為 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/'

在接下來的步驟中，您將瞭解如何將資料模組新增至命名空間：建立資料基礎模組和建立資料產品模組。