使用 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。請勿使用 package.json 的其他 dependencies 選項，例如 >version。

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

將套件新增為依附元件

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

  1. 在工作區的「Files」(檔案) 窗格中，選取 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：第三方 Package Repository 的 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 必須與存放區中 .npmrc 檔案定義的登錄檔範圍相符。
      • PACKAGE-NAME：套件名稱。
      • PACKAGE-URL：Package Repository 的 tar.gz 網址，例如 https://github.com/user/sample-package-repository/archive/master.tar.gz。

  3. 按一下「Install packages」。

  4. 修訂並推送變更。

下列程式碼範例顯示新增至 .package.json 檔案的公開開放原始碼緩慢變動維度套件：

 ```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. 在工作區的「Files」(檔案) 窗格中，選取要使用套件的 .js 檔案。

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

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

  3. 修訂並推送變更。

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

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

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

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

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

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

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

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

  3. 修訂並推送變更。

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

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

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

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

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

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

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

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

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

  3. 修訂並推送變更。

下列程式碼範例顯示從 postoffice 套件匯入 js 區塊的 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. 在工作區的「Files」窗格中，選取要使用套件的 .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 套件的所有驗證權杖，儲存在單一 Secret 中。您必須為每個 Dataform 存放區建立一個專屬密鑰。密鑰必須採用 JSON 格式。

  2. 將 Secret 上傳至 Dataform 存放區。

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

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

驗證私人 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. 將 Secret 存取權授予 Dataform 服務代理。

    Dataform 服務代理 ID 的格式如下：

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

如果您使用短期驗證權杖 (例如 Artifact Registry 的 OAuth 存取權杖)，則必須在權杖到期前，定期以新的密鑰版本更新密鑰。Dataform 預設會使用最新版本的 Secret。如要瞭解如何自動更新密鑰，請參閱「輪替密鑰」。

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

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

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

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

    前往 Dataform

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

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

  4. 在「Add NPM package secret token」(新增 NPM 套件密鑰權杖) 窗格中，選取「Secret」選單，然後選取含有私人 NPM 套件驗證權杖的密鑰。

  5. 按一下 [儲存]。

建立 .npmrc 檔案，用於驗證私人套件

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

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

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

    前往 Dataform

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

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

  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 檔案中，因此請務必加上開頭 ${ 和結尾 } 括號。

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

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

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

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

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

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

  2. 在密鑰中新增版本。

    Dataform 預設會使用最新版的 Secret。

    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 重複使用變數和函式」。

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

  1. 在「Files」(檔案) 窗格中，點按 「更多」。

  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 }

後續步驟