使用 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 必须与仓库中 .npmrc 文件中定义的注册表范围 一致。
      • 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 替换为您要使用的函数或 常量的名称，该名称在 module.exports 中声明，位于 软件包 index.js 文件中。
    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. 在工作区的文件 窗格中，选择您要在其中使用软件包的 .sqlx 文件。

  2. 在该文件中，输入以下 js 代码块：

    js {
  const { EXPORT-NAME } = require("PACKAGE-NAME");
}
    1. 将 EXPORT-NAME 替换为您要使用的函数 或常量的名称，该名称在 module.exports 软件包 index.js 文件中声明。
    2. 将 PACKAGE-NAME 替换为您要使用的软件包的名称 。

  3. 提交并 推送更改。

以下代码示例展示了在 js 代码块中导入并在 SQLX 文件中的 SELECT 语句中使用的 postoffice 软件包中的 getDomain 函数：

/*
 * 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 代码块中导入并在 SQLX 文件中的 SELECT 语句中使用的 postoffice 软件包及其 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。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. 在密钥值 字段中，按以下格式输入一个或多个身份验证令牌：
    {
  "AUTHENTICATION_TOKEN_NAME": "TOKEN_VALUE"
}

    替换以下内容：

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

  2. 向 Dataform 服务代理授予对 Secret 的访问权限。

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

    service-PROJECT_NUMBER@gcp-sa-dataform.
    1. 授予访问权限时，请务必向 Dataform 服务代理授予 roles/secretmanager.secretAccessor 角色。

将用于对专用软件包进行身份验证的 Secret 上传到 Dataform 仓库

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

如需将包含专用 NPM 软件包身份验证令牌的 Secret 上传到 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 文件

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

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

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

如需将身份验证令牌添加到 Dataform 仓库中的 .npmrc 文件，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，前往 Dataform 页面。

    前往 Dataform

  2. 选择要在其中安装专用 NPM 软件包的仓库，然后选择一个工作区。

  3. 在文件 窗格中，选择 .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 仓库中的后续专用软件包进行身份验证

如需在 Dataform 仓库中对专用 NPM 软件包进行身份验证，该仓库已包含一个包含软件包身份验证令牌的 Secret 和一个 .npmrc 文件，请按以下步骤操作：

  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 仓库中安装该软件包。

创建软件包

本部分介绍如何创建可用于在 Dataform 中开���工作流的自定义 JavaScript 软件包。

如需创建可在多个 Dataform 仓库中重复使用的软件包，您需要创建一个专用于该软件包的 Dataform 仓库，并将其连接到第三方 Git 仓库，以使其可供其他 Dataform 仓库使用。

然后，您需要创建一个顶层 index.js 文件，并将可导出的软件包内容（例如函数和常量）添加到该文件中。如需查看在 Dataform 中创建的软件包的示例，请参阅 GitHub 上的 dataform-package-base 。

创建软件包后，您可以 在其他 Dataform 仓库中安装该软件包 并使用该软件包中的可导出内容（例如常量和函数） 来开发工作流。

除了创建软件包之外，您还可以通过 include 在单个 Dataform 仓库中重复使用 JavaScript 函数和常量。 如需了解详情，请参阅 在 Dataform 中使用 include 重复使用变量和函数。

如需使用可在 Dataform 中重复使用的 JavaScript 代码创建自己的软件包，请在工作区中按以下步骤操作：

  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 }

后续步骤