在 Dataform 中安装软件包

本文档介绍了如何在 Dataform 代码库中安装 JavaScript 软件包，并将其导入 JavaScript 文件和 SQLX 文件，以使用该软件包在 Dataform 中开发 SQL 工作流。

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

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

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

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

  • 在 package.json 中明确指定软件包版本，例如 3.0.0。不要使用 package.json 的其他 dependencies 选项，例如 >version。

  • 在非生产环境中测试新的软件包版本。如需详细了解如何配置不同的代码生命周期环境，请参阅管理代码生命周期。

准备工作

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

    转到 Dataform 页面

  2. 选择或创建代码库。

  3. 选择或创建开发工作区。

  4. 可选：如需安装专用软件包，请对专用软件包进行身份验证。

所需的角色

如需获取导入软件包所需的权限，请让管理员向您授予工作区的 Dataform Editor (roles/dataform.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

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

在 Dataform 代码库中安装软件包

如需在 Dataform 代码库中安装软件包，您需要将其作为依赖项添加到 package.json 文件中。package.json 文件中依赖项定义的格式取决于软件包的类型。如果您没有 package.json 文件（因为 workflow_settings.yaml 文件指定了 dataformCoreVersion），请从 workflow_settings.yaml 中移除 dataformCoreVersion，然后创建一个 package.json 文件并添加 @dataform/core 作为依赖项。

如需在 Dataform 代码库中安装软件包，请按以下步骤操作：

  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. 提交并push您的更改。

以下代码示例展示了添加到 .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. 提交并push您的更改。

以下代码示例显示了导入并在 JavaScript 文件中使用的 postoffice 软件包中的 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. 提交并push您的更改。

以下代码示例展示了在 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. 提交并push您的更改。

以下代码示例显示了在 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. 在工作区的 Files 窗格中，选择要使用该软件包的 .sqlx 文件。

  2. 在该文件中，按以下格式导入软件包：

    js {
  const CONSTANT-NAME = require("PACKAGE-NAME");
}
    1. 将 CONSTANT-NAME 替换为常量的名称。
    2. 将 PACKAGE-NAME 替换为您要使用的软件包的名称。

  3. 提交并push您的更改。

以下代码示例显示了在 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

后续步骤