使用 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 與第三方套件存放區的 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. 在工作區的「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. 在工作區的「檔案」窗格中，選取要使用套件的 .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. 在工作區的「Files」窗格中，選取要使用套件的 .sqlx 檔案。

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

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

  3. 修訂並推送變更。

下列程式碼範例顯示 postoffice 套件中的 getDomain 函式，已在 js 區塊中匯入，並用於 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 套件的所有驗證權杖儲存在存放區中的單一密鑰中。您需要為每個 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. 在存放區頁面中，依序按一下「Settings」>「Configure private NPM packages」。

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

  5. 按一下 [儲存]。

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

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

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

  1. 在 Google Cloud 控制台中，前往「Dataform」頁面。

    前往 Dataform

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

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

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

    1. 在「新增檔案路徑」欄位中輸入 .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 檔案，請按照下列步驟操作：

  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 存放區中安裝套件，並使用套件中的可匯出內容 (例如常數和函式) 來開發工作流程。

除了建立套件之外，您也可以在單一 Dataform 存放區中使用包含項目，重複使用 JavaScript 函式和常數。詳情請參閱「在 Dataform 中重複使用變數和函式，並加入相關項目」。

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

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

  2. 點選「建立檔案」。

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

    2. 在「新增檔案路徑」欄位中輸入 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. 修訂並推送變更。

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

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

後續步驟