使用 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. 在工作区内的 Files 窗格中，选择要使用该软件包的 .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 Secret，专用于在 Dataform 代码库中存储专用 NPM 软件包的身份验证令牌。

    1. 将从 NPM 注册库中获取的软件包身份验证令牌添加到 Secret。

    您需要将私有 NPM 软件包的所有身份验证令牌存储在代码库中的单个 Secret 中。您需要为每个 Dataform 代码库创建一个专用密钥。Secret 必须采用 JSON 格式。

  2. 将 Secret 上传到 Dataform 代码库。

  3. 创建 .npmrc 文件，并将软件包的身份验证令牌添加到该文件中。

    .npmrc 文件中的身份验证令牌必须与上传的 Secret 中的身份验证令牌一致。

对私有 NPM 软件包进行身份验证后，您可以在 Dataform 代码库中安装该软件包。

创建用于对私有软件包进行身份验证的 Secret

如需对 Dataform 代码库中的私有 NPM 软件包进行身份验证，您需要创建一个 Secret Manager Secret，并在该 Secret 中为您要安装在 Dataform 代码库中的所有私有软件包定义身份验证令牌。为每个私有 NPM 软件包定义一个身份验证令牌，并将所有身份验证令牌存储在每个代码库的单个 Secret 中。Secret 必须采用 JSON 格式。

如需为私有 NPM 软件包创建包含身份验证令牌的 Secret，请按以下步骤操作：

  1. 在 Secret Manager 中，创建 Secret。

    1. 在 Secret 值字段中，按以下格式输入一个或多个身份验证令牌：
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    替换以下内容：

    • AUTHENTICATION_TOKEN_NAME：令牌的唯一名称，用于标识其要对其进行身份验证的软件包。
    • TOKEN_VALUE：从 NPM 注册表获取的身份验证令牌的值。

  2. 向您的 Dataform 服务账号授予对 Secret 的访问权限。

    您的 Dataform 服务账号采用以下格式：

    service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com
    1. 授予访问权限时，请务必向您的 Dataform 服务账号授予 roles/secretmanager.secretAccessor 角色。

将用于对私有软件包进行身份验证的密钥上传到 Dataform 代码库

在首次在 Dataform 代码库中安装专用 NPM 软件包之前，请将包含软件包身份验证令牌的密钥上传到代码库。

如需将包含专用 NPM 软件包身份验证令牌的密钥上传到 Dataform 代码库，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，进入 Dataform 页面。

    前往 Dataform

  2. 选择要安装私有 NPM 软件包的代码库。

  3. 在代码库页面上，依次点击设置 > 配置私有 NPM 软件包。

  4. 在添加 NPM 软件包 Secret 令牌窗格中的 Secret 菜单中，选择包含专用 NPM 软件包身份验证令牌的 Secret。

  5. 点击保存。

创建 .npmrc 文件以对私有软件包进行身份验证

如需对 Dataform 代码库中的专用 NPM 软件包进行身份验证，您需要在代码库中创建顶级 .npmrc 文件。您需要在 .npmrc 文件内的代码库中存储要安装在代码库中的所有专用 NPM 软件包的身份验证令牌。.npmrc 文件中的身份验证令牌必须与上传到代码库的 Secret 中的身份验证令牌一致。如需详细了解 .npmrc 文件，请参阅 npmrc 文档。

如需在代码库中创建顶级 .npmrc 文件，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，进入 Dataform 页面。

    前往 Dataform

  2. 选择要安装私有 NPM 软件包的代码库，然后选择一个工作区。

  3. 在文件窗格中，点击 更多，然后点击创建文件。

  4. 在创建新文件窗格中，执行以下操作：

    1. 在添加文件路径字段中，输入 .npmrc。

    2. 点击创建文件。

将身份验证令牌添加到 Dataform 代码库中的 .npmrc 文件

如需在已包含包含软件包身份验证令牌的密钥和 .npmrc 文件的 Dataform 代码库中对专用 NPM 软件包进行身份验证，您需要将专用软件包的身份验证令牌添加到代码库中的 .npmrc 文件。

在 .npmrc 文件中，您需要定义 NPM 注册库的范围，并为在该范围内访问的专用软件包添加身份验证令牌。如需详细了解 .npmrc 文件，请参阅 npmrc 文档。

.npmrc 文件中的身份验证令牌必须与上传到代码库的 Secret 中的身份验证令牌一致。

如需向 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 文件中的身份验证令牌必须与上传的 Secret 中的身份验证令牌一致。身份验证令牌在 .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 中，列出 Secret，然后选择用于存储代码库私有 NPM 软件包的身份验证令牌的 Secret。

  2. 向 Secret 添加新版本。

    默认情况下，Dataform 会使用最新版本的 Secret。

    1. 将私密软件包的身份验证令牌添加到 Secret 值，格式如下：
    {
  "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 }

后续步骤