使用 JavaScript 套件

本文將說明如何執行下列操作：

事前準備

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 執行下列任一操作或同時完成兩者：

    1. 如要在存放區中安裝套件，或驗證私人 NPM 套件以啟用安裝，請按照下列步驟操作：
      1. 選取或建立存放區。
      2. 選取或建立開發工作區。
      3. 選用：如要安裝私人套件，請驗證私人套件。
      4. 如果存放區不含 package.json 檔案，請建立 package.json 並移動 Dataform 核心套件。
    2. 如要建立套件，請按照下列步驟操作：
      1. 建立專用於套件的 Dataform 存放區。將存放區名稱與套件名稱相符。
      2. 將存放區連結至第三方 Git 存放區，該存放區將代管您的套件。
      3. 在 Dataform 存放區中建立並初始化工作區。

  3. 請確認您具備必要權限，可以完成本文中的工作。

必要的角色

如要取得完成本文工作所需的權限，請要求管理員授予下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

安裝套件

本節說明如何安裝 JavaScript 套件，並將其匯入 JavaScript 檔案和 SQLX 檔案，以便在 Dataform 中使用該套件開發工作流程。

如要在 Dataform 中使用套件，您必須在存放區中安裝套件。

您可以在 Dataform 中安裝下列類型的套件：

接著，如要在 JavaScript 或 SQLX 檔案中使用套件，您需要將套件的所選內容匯入檔案。您也可以將整個套件匯入 JavaScript 或 SQLX 檔案，不必只匯入所選內容。

為避免在實際工作環境中安裝套件時發生問題，建議您採取下列做法：

  • 在 package.json 中明確指定套件版本，例如 3.0.0。請勿使用其他 dependencies 選項，例如 package.json 中的 >version。

  • 在非正式環境中測試新版套件。如要進一步瞭解如何設定不同的工作流程生命週期環境，請參閱「工作流程生命週期的最佳做法」。

將套件新增為依附元件

如要在 Dataform 存放區中安裝套件，您需要在 package.json 檔案中將套件新增為依附元件：

  1. 在工作區的「檔案」窗格中，選取 package.json。

  2. 將套件新增至 dependencies 區塊：

    1. 新增已發布的公開 NPM 套件，格式如下：

      "PACKAGE-NAME": "PACKAGE-VERSION"

      更改下列內容：

      • PACKAGE-NAME 替換為套件名稱。
      • PACKAGE-VERSION，並使用已發布的最新版公開 NPM 套件。為避免套件安裝問題，請明確指定版本，例如 3.0.0。

    2. 新增未發布的公開 NPM 套件，格式如下：

      "PACKAGE-NAME": "PACKAGE-URL"

      更改下列內容：

      • PACKAGE-NAME 替換為套件名稱。
      • PACKAGE-URL，並將 tar.gz 設為第三方套件存放區的網址，例如 https://github.com/user/sample-package-repository/archive/master.tar.gz。

    3. 以以下格式新增經過驗證的私人 NPM 套件：

      "REGISTRY-SCOPE/PACKAGE-NAME": "PACKAGE-URL"

      更改下列內容：

      • REGISTRY-SCOPE 替換為套件名稱。 REGISTRY-SCOPE 必須與存放區 .nmprc 檔案中定義的登錄範圍相符。
      • PACKAGE-NAME 替換為套件名稱。
      • PACKAGE-URL，其中 tar.gz 是套件存放區的網址，例如 https://github.com/user/sample-package-repository/archive/master.tar.gz。

  3. 按一下「安裝套件」。

  4. 修訂並推送變更。

下列程式碼範例顯示新增至 .package.json 檔案的公開開放原始碼 Slowly changing dimensions 套件：

 ```json
 {
   "name": "repository-name",
   "dependencies": {
     "@dataform/core": "2.0.3",
     "dataform-scd": "https://github.com/dataform-co/dataform-scd/archive/0.3.tar.gz"
   }
 }
 ```

將套件函式或常數匯入 Dataform 的 JavaScript 檔案

如要在 Dataform 的 JavaScript 檔案中使用套件中的函式或常數，請先將其匯入檔案。

如要將函式或常數從套件匯入 JavaScript 檔案，請按照下列步驟操作：

  1. 在工作區的「檔案」窗格中，選取要使用套件的 .js 檔案。

  2. 在檔案中，以以下格式匯入函式或常數：

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    1. 將 EXPORT-NAME 替換為您要使用的函式或常數名稱，該名稱已在套件 index.js 檔案的 module.exports 中宣告。
    2. 將 PACKAGE-NAME 替換為您要使用的套件名稱。

  3. 修訂並推送變更。

下列程式碼範例顯示從 postoffice 套件匯入的 getDomain 函式，並在 JavaScript 檔案中使用：

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const { getDomain } = require("postoffice");
getDomain();

將整個套件匯入 Dataform 的 JavaScript 檔案

如要將整個套件匯入 JavaScript 檔案，而不是將所選函式或常數匯入 JavaScript 檔案，請按照下列步驟操作：

  1. 在工作區的「檔案」窗格中，選取要使用套件的 .js 檔案。

  2. 在檔案中，以以下格式匯入套件：

    const CONSTANT-NAME = require("PACKAGE-NAME");
    1. 將 CONSTANT-NAME 替換為常數的名稱。
    2. 將 PACKAGE-NAME 替換為您要使用的套件名稱。

  3. 修訂並推送變更。

下列程式碼範例顯示 JavaScript 檔案中使用的 postoffice 套件匯入 getDomain 函式：

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

const postoffice = require("postoffice");
postoffice.getDomain();

將套件函式或常數匯入 Dataform 的 SQLX 檔案

如要在 SQLX 檔案中使用套件中的函式或常數，請先將其匯入檔案。

如要將函式或常數從套件匯入 SQLX 檔案，請按照下列步驟操作：

  1. 在工作區的「檔案」窗格中，選取要使用套件的 .sqlx 檔案。

  2. 在檔案中輸入下列 js 區塊：

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. 將 EXPORT-NAME 替換為您要使用的函式或常數名稱，並在套件 index.js 檔案的 module.exports 中宣告。
    2. 將 PACKAGE-NAME 替換為您要使用的套件名稱。

  3. 修訂並推送變更。

下列程式碼範例顯示在 js 區塊中匯入的 postoffice 套件中的 getDomain 函式，以及在 SQLX 檔案的 SELECT 陳述式中使用的函式：

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const { getDomain } = require("postoffice");
}

SELECT ${getDomain("email")} as test

將整個套件匯入 Dataform 的 SQLX 檔案

如要將整個套件匯入 SQLX 檔案，而不是將選取的函式或常數匯入 JavaScript 檔案，請按照下列步驟操作：

  1. 在工作區的「檔案」窗格中，選取要使用套件的 .sqlx 檔案。

  2. 在檔案中，以以下格式匯入套件：

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. 將 CONSTANT-NAME 替換為常數的名稱。
    2. 將 PACKAGE-NAME 替換為您要使用的套件名稱。

  3. 修訂並推送變更。

下列程式碼範例顯示在 js 區塊中匯入的 postoffice 套件，以及在 SQLX 檔案的 SELECT 陳述式中使用的 getDomain 函式：

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

驗證私人套件

本節說明如何在 Dataform 中驗證私人 NPM 套件，以便在 Dataform 存放區中安裝該套件。

如要在 Dataform 存放區中安裝私人 NPM 套件，並使用該套件開發工作流程，請先在 Dataform 中驗證套件。存放區中的第一個私人套件和後續私人套件的驗證程序不同。

在 Dataform 存放區中驗證第一個私人套件

如要在 Dataform 中驗證私人 npm 套件，請先在 Dataform 存放區中安裝第一個私人 npm 套件，然後執行下列操作：

  1. 建立 Secret Manager 密鑰，專門用於在 Dataform 存放區中儲存私人 NPM 套件的驗證權杖。

    1. 將從 NPM 登錄檔取得的套件驗證權杖新增至密鑰。

    您必須將私人 NPM 套件的所有驗證權杖儲存在存放區的單一密鑰中。您需要為每個 Dataform 存放區建立一個專屬密鑰。密鑰必須採用 JSON 格式。

  2. 將密鑰上傳至 Dataform 存放區。

  3. 建立 .npmrc 檔案，並將套件的驗證權杖新增至檔案。

    .npmrc 檔案中的驗證權杖必須與上傳的密鑰中的驗證權杖相符。

驗證私人 NPM 套件後，您就可以在 Dataform 存放區中安裝套件。

建立私密套件驗證的密鑰

如要在 Dataform 存放區中驗證私人 NPM 套件，您需要建立 Secret Manager 密鑰，並在密鑰中為要安裝在 Dataform 存放區中的所有私人套件定義驗證權杖。為每個私人 NPM 套件定義一個驗證權杖，並將所有驗證權杖儲存在每個存放區的單一密碼中。密鑰必須採用 JSON 格式。

如要建立含有私人 NPM 套件驗證權杖的密鑰，請按照下列步驟操作：

  1. 在 Secret Manager 中建立密鑰。

    1. 在「Secret value」(密鑰值) 欄位中，輸入一或多個驗證權杖，格式如下：
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    更改下列內容：

    • AUTHENTICATION_TOKEN_NAME：權杖的專屬名稱，用於識別驗證的套件。
    • TOKEN_VALUE：驗證權杖的值，可從 NPM 登錄檔取得。

  2. 將密鑰存取權授予 Dataform 服務帳戶。

    Dataform 服務帳戶的格式如下：

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. 授予存取權時，請務必將 roles/secretmanager.secretAccessor 角色授予 Dataform 服務帳戶。

將私人套件的驗證密鑰上傳至 Dataform 存放區

首次在 Dataform 存放區中安裝私人 NPM 套件前，請先將含有套件驗證權杖的密鑰上傳至存放區。

如要將含有私人 NPM 套件驗證權杖的密鑰上傳至 Dataform 存放區，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取要安裝私人 NPM 套件的存放區。

  3. 在存放區頁面中，依序點選「設定」>「設定私有 NPM 套件」。

  4. 在「新增 npm 套件密鑰權杖」窗格的「密鑰」選單中，選取含有私人 npm 套件驗證權杖的密鑰。

  5. 按一下 [儲存]。

建立 .npmrc 檔案，驗證私有套件

如要在 Dataform 存放區中驗證私人 NPM 套件，您需要在存放區中建立頂層 .npmrc 檔案。您需要在 .npmrc 檔案中，儲存要在存放區中安裝的所有私人 NPM 套件的驗證權杖。.npmrc 檔案中的驗證權杖必須與上傳至存放區的密鑰中的驗證權杖相符。如要進一步瞭解 .npmrc 檔案，請參閱 npmrc 說明文件。

如要在存放區中建立頂層 .npmrc 檔案，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取要安裝私有 NPM 套件的存放區，然後選取工作區。

  3. 在「Files」(檔案) 窗格中，依序點選 「More」(更多) 和「Create file」(建立檔案)。

  4. 在「建立新檔案」窗格中，執行下列步驟：

    1. 在「Add a file path」(新增檔案路徑) 欄位中，輸入 .npmrc。

    2. 點選「建立檔案」。

在 Dataform 存放區的 .npmrc 檔案中新增驗證權杖

如要在 Dataform 存放區中驗證私人 NPM 套件，該存放區必須已包含含有套件驗證權杖的密鑰和 .npmrc 檔案，您需要在存放區的 .npmrc 檔案中新增私人套件的驗證權杖。

在 .npmrc 檔案中，您需要定義 NPM 登錄檔的範圍，並新增該範圍內存取私人套件的驗證權杖。如要進一步瞭解 .npmrc 檔案，請參閱 npmrc 說明文件。

.npmrc 檔案中的驗證權杖必須與上傳至存放區的密鑰中的驗證權杖相符。

如要在 Dataform 存放區的 .npmrc 檔案中新增驗證權杖，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取要安裝私有 NPM 套件的存放區，然後選取工作區。

  3. 在「Files」窗格中，選取 .npmrc 檔案。

  4. 在 .npmrc 檔案中，以以下格式定義 NPM 登錄範圍和私有套件的驗證權杖：

    @REGISTRY-SCOPE:registry=NPM-REGISTRY-URL
NPM-REGISTRY-URL:_authToken=$AUTHENTICATION-TOKEN

    更改下列內容：

    • REGISTRY-SCOPE：要套用驗證權杖的 NPM 登錄範圍。
    • NPM-REGISTRY-URL：NPM 登錄檔的網址，例如 https://npm.pkg.github.com。
    • AUTHENTICATION-TOKEN：私有 NPM 套件的驗證權杖。.npmrc 檔案中的驗證權杖必須與上傳的密鑰中的驗證權杖相符。驗證權杖會以環境變數的形式提供於 .npmrc 檔案中，因此請務必加入開頭的 ${ 和結尾的 } 括號。

    您可以輸入多個驗證權杖。

以下程式碼範例顯示新增至 Dataform 存放區 .npmrc 檔案的私有 NPM 套件驗證權杖：

@company:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${AUTHENTICATION_TOKEN}

在 Dataform 存放區中驗證後續的私人套件

如要在已包含套件驗證權杖和 .npmrc 檔案的 Dataform 存放區中驗證私人 NPM 套件，請按照下列步驟操作：

  1. 在 Secret Manager 中列出密碼，然後選取儲存存放區私有 NPM 套件驗證權杖的密碼。

  2. 為密鑰新增版本。

    Dataform 預設會使用最新版本的密鑰。

    1. 以以下格式將私有套件的驗證權杖新增至密鑰值：
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    更改下列內容：

    • AUTHENTICATION_TOKEN_NAME：權杖的專屬名稱，用於識別驗證的套件。
    • TOKEN_VALUE：驗證權杖的值，可從 NPM 登錄檔取得。

    您可以一次新增多個驗證權杖。

  3. 在 Dataform 中，將驗證權杖新增至存放區的 .npmrc 檔案。

驗證私人 NPM 套件後，即可在 Dataform 存放區中安裝套件。

建立套件

本節說明如何建立自訂 JavaScript 套件，以便在 Dataform 中開發工作流程。

如要建立可在多個 Dataform 存放區中重複使用的套件，您必須建立專用於套件的 Dataform 存放區，並將其連線至第三方 Git 存放區，以便其他 Dataform 存放區使用。

接著，您需要建立頂層 index.js 檔案，並將可匯出的套件內容 (例如函式和常數) 新增至該檔案。如需在 Dataform 中建立套件的範例，請參閱 GitHub 上的 dataform-package-base。

建立套件後，您可以在其他 Dataform 存放區中安裝套件，並使用套件中可匯出的內容 (例如常數和函式) 開發工作流程。

除了建立套件，您也可以透過 include，在單一 Dataform 存放區中重複使用 JavaScript 函式和常數。詳情請參閱「在 Dataform 中使用 include 重複使用變數和函式」。

如要使用 JavaScript 程式碼建立自己的套件，以便在 Dataform 中重複使用，請在工作區中按照下列步驟操作：

  1. 在「檔案」窗格中，按一下 「更多」。

  2. 點選「建立檔案」。

    1. 在「建立新檔案」窗格中，執行下列步驟：

    2. 在「Add a file path」(新增檔案路徑) 欄位中，輸入 index.js。

    3. 點選「建立檔案」。

  3. 在 index.js 檔案中，輸入要匯出套件的 JavaScript 程式碼。

    1. 請按照下列格式建立常數：

      const CONSTANT_NAME = CONSTANT_VALUE;
module.exports = { CONSTANT_NAME };

      更改下列內容：

      • CONSTANT_NAME：常數名稱
      • CONSTANT_VALUE：常數的值

    2. 建立函式時請採用下列格式：

      function FUNCTION_NAME(PARAMETERS) { FUNCTION_BODY }

module.exports = { FUNCTION_NAME }

      更改下列內容：

      • FUNCTION_NAME：函式名稱。
      • PARAMETERS：函式的參數。
      • FUNCTION_BODY：函式要執行的程式碼。

  4. 選用：按一下「格式」。

  5. 選用：在 definitions 目錄中，新增不會匯出的套件程式碼。

  6. 修訂並推送變更。

下列套件程式碼範例顯示 postoffice 套件的 index.js 檔案，其中匯出 getDomain 函式：

// filename index.js
// package name postoffice

const GENERIC_DOMAINS = "('samplemail.com','samplemail.co.uk','examplemailbox.com'";

function getDomain(email) {
  let cleanEmail = `trim(${email})`
  const domain = `substr(${cleanEmail}, strpos(${cleanEmail}, '@') + 1)`;
  return `case
            when ${domain} in ${common.GENERIC_DOMAINS} then ${cleanEmail}
            when ${domain} = "othermailbox.com" then "other.com"
            when ${domain} = "mailbox.com" then "mailbox.global"
            when ${domain} = "support.postman.com" then "postman.com"
            else ${domain}
          end`;
}

module.exports = { getDomain }

後續步驟