使用 JavaScript 软件包

本页面介绍如何完成以下任务：

• 在 Dataform 代码库中安装 JavaScript 软件包。
• 对私有 NPM 软件包进行身份验证，以便在代码库中安装该软件包。
• 创建可用于开发工作流的自定义 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 角色：

• 工作区和代码库的 Dataform Editor (roles/dataform.editor)
• 针对代码库的 Dataform Admin (roles/dataform.admin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

安装软件包

本部分介绍如何安装 JavaScript 软件包并将其导入 JavaScript 文件和 SQLX 文件，以便您可以使用该软件包在 Dataform 中开发工作流。

如需在 Dataform 中使用软件包，您需要在代码库中安装该软件包。

您可以在 Dataform 中安装以下类型的软件包：

• 已发布的公开 NPM 软件包
• 未发布的公开 NPM 软件包
• 经过身份验证的专用 npm 软件包

然后，如需在 JavaScript 或 SQLX 文件中使用该软件包，您需要将该软件包的所选内容导入到该文件中。您还可以将整个软件包导入 JavaScript 或 SQLX 文件，而不是导入其所选内容。

为防止生产环境中出现软件包安装问题，我们建议您执行以下操作：

• 在 package.json 中明确指定软件包版本，例如 3.0.0。请勿使用 package.json 的其他 dependencies 选项，例如 >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 替换为第三方 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 替换为软件包仓库的 tar.gz 网址，例如 https://github.com/user/sample-package-repository/archive/master.tar.gz。

3. 点击安装软件包。

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. 在工作区的文件窗格中，选择要在其中使用软件包的 .js 文件。

2. 在文件中，按以下格式导入函数或常量：

   const { EXPORT-NAME } = require("PACKAGE-NAME");
   

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

3. 提交并推送更改。

以下代码示例展示了在 JavaScript 文件中导入和使用的 postoffice 软件包中的 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 替换为您要使用的函数或常量的名称，该函数或常量在软件包 index.js 文件中的 module.exports 中声明。
   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 块中导入的 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 服务代理共享的 Secret（例如私有 NPM 注册表令牌）可能会被可在代码库中修改代码或触发编译结果的用户访问。如需了解详情，请参阅软件包安装期间的 Secret 访问权限。

本部分介绍了如何在 Dataform 中对私有 NPM 软件包进行身份验证，以便在 Dataform 代码库中安装该软件包。

如需在 Dataform 代码库中安装专用 NPM 软件包并使用该软件包开发工作流，您需要先在 Dataform 中对该软件包进行身份验证。代码库中的第一个私有软件包和代码库中的后续私有软件包的身份验证过程不同。

对 Dataform 代码库中的第一个私有软件包进行身份验证

如需在 Dataform 中对专用 NPM 软件包进行身份验证，您需要在 Dataform 代码库中安装第一个专用 NPM 软件包之前执行以下操作：

1. 创建 Secret Manager 密钥，专门用于在 Dataform 代码库中存储私有 NPM 软件包的身份验证令牌。

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

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

2. 将密钥上传到 Dataform 代码库。

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

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

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

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

如需在 Dataform 代码库中对专用 NPM 软件包进行身份验证，您需要创建一个 Secret Manager 密钥，并为要在密钥内的 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 采用以下格式：

   [e-mail]
   

   1. 授予访问权限时，请务必向 Dataform 服务代理授予 roles/secretmanager.secretAccessor 角色。

如果您使用短期有效的身份验证令牌（例如 Artifact Registry 的 OAuth 访问令牌），则必须在令牌过期之前定期使用新的 Secret 版本更新 Secret。默认情况下，Dataform 会使用最新版本的 Secret。如需了解如何自动更新 Secret，请参阅轮替 Secret。

将用于对私有软件包进行身份验证的 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 文件。您需要将要安装在代码库中的所有专用 NPM 软件包的身份验证令牌存储在 .npmrc 文件中。.npmrc 文件中的身份验证令牌必须与上传到代码库的 Secret 中的身份验证令牌一致。如需详细了解 .npmrc 文件，请参阅 npmrc 文档。

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

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

   前往 Dataform

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

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

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

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

   2. 点击创建文件。

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

如需在已包含具有软件包身份验证令牌的 Secret 和 .npmrc 文件的 Dataform 代码库中对专用 npm 软件包进行身份验证，您需要将专用软件包的身份验证令牌添加到代码库中的 .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 文件中的身份验证令牌必须与上传的密钥中的身份验证令牌一致。身份验证令牌在 .npmrc 文件中作为环境变量提供，因此请务必添加左括号 ${ 和右括号 }。

   您可以输入多个身份验证令牌。

以下代码示例展示了添加到 Dataform 代码库中的 .npmrc 文件的私有 NPM 软件包的身份验证令牌：

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

对 Dataform 代码库中的后续私有软件包进行身份验证

如需在已包含具有软件包身份验证令牌的 Secret 和 .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 代码库中安装该软件包。

创建软件包

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

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

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

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

除了创建软件包之外，您还可以通过包含在单个 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. 提交并推送更改。

以下软件包代码示例展示了 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 }

后续步骤

• 如需了解如何管理所需的 Dataform 核心软件包，请参阅管理 Dataform 核心软件包。
• 如需详细了解 Dataform 中的软件包，请参阅使用软件包在多个代码库中重复使用代码。
• 如需了解如何编写可在 Dataform 中重复使用的 JavaScript 变量和函数，请参阅在 Dataform 中通过包含项重复使用变量和函数。