在 Dataform 中安装软件包

本文档介绍了如何在 Dataform 存储库,将其导入到 JavaScript 文件中,然后 一个 SQLX 文件,以便使用该软件包在 Dataform 中开发 SQL 工作流。

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

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

然后,要在 JavaScript 或 SQLX 文件中使用 软件包,您需要 将软件包的选定内容添加到文件中您还可以将完整的 而不是将其选中的内容转换为 JavaScript 或 SQLX 文件。

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

  • 在以下位置明确指定软件包版本: package.json,例如 3.0.0。不使用 dependencies 个选项package.json,例如 >version

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

准备工作

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

    转到 Dataform 页面

  2. 选择或创建代码库

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

  4. 如果您的代码库不包含 package.json 文件, 创建 package.json 并移动 Dataform 核心软件包

  5. 可选:如需安装专用软件包,请执行以下操作: 对私有软件包进行身份验证

所需的角色

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

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

安装软件包

如需在 Dataform 仓库中安装软件包,您需要: 将其作为依赖项添加到 package.json 文件中。

如需将软件包作为依赖项添加到 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 文件中:

 ```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 文件

要在 JavaScript 文件中使用软件包中的函数或常量,请 Dataform 中,您需要先将其导入到文件中。

如需将函数或常量从软件包导入到 JavaScript 文件中,请按以下步骤操作: 请按以下步骤操作:

  1. 在您的工作区的 Files 窗格中,选择一个 .js 文件,其中 您要使用该软件包
  2. 在该文件中,按以下格式导入函数或常量:

    const { EXPORT-NAME } = require("PACKAGE-NAME");
    
    1. EXPORT-NAME 替换为函数名称,或 module.exports 中声明的 软件包 index.js 文件。
    2. PACKAGE-NAME 替换为 您要使用的软件包。
  3. 提交推送您的更改。

以下代码示例显示了getDomain 导入并在 JavaScript 文件中使用了 postoffice 软件包:

/*
 * 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. 提交推送您的更改。

以下代码示例显示了getDomain 导入了 JavaScript 文件中使用的 postoffice 软件包:

/*
 * 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 替换为函数名称 或常量(在 module.exports 中声明) 位于软件包 index.js 文件中。
    2. PACKAGE-NAME 替换为软件包的名称 资源。
  3. 提交推送您的更改。

以下代码示例显示了getDomain postoffice 软件包导入 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. 提交推送您的更改。

以下代码示例显示了从 Cloud SQL 中导入的 postoffice 软件包, js 代码块及其 getDomain 函数, 使用 SQLX 文件中的 SELECT 语句:

/*
 * Contents of postoffice index.js:
 * module.exports = { getDomain };
 */

config {
    type: "table",
}

js {
  const postoffice = require("postoffice");
}

SELECT ${postoffice.getDomain("email")} as test

后续步骤