配置合集

本文档介绍了如何在 Dataform 中执行以下操作：

准备工作

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

    前往 Dataform

  2. 选择或创建代码库。

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

  4. 可选：如需替换发布配置中的默认 Google Cloud 项目，请在您计划使用的项目中授予自定义服务账号访问权限。

所需的角色

如需获得完成本文档中的任务所需的权限，请让您的管理员为您授予以下 IAM 角色：

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

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

如需增强调度安全性，请参阅实现增强的调度权限。

如需能够更新 Dataform 代码库的发布配置的发布版本，您必须向 Dataform 服务代理授予对使用此发布配置的工作流配置中每个自定义服务账号的 iam.serviceAccounts.actAs 权限。此权限在 Service Account User 角色 (roles/iam.serviceAccountUser) 中提供。如需了解详情，请参阅授予所需的 IAM 角色。

Dataform 中的工作流生命周期简介

本部分介绍了 Dataform 中的工作流生命周期，以及在 Dataform 中配置编译和执行的方法。

Dataform 工作流生命周期包含以下阶段：

开发
您在 Dataform 工作区中开发工作流。
编译

Dataform 会实时将工作区中的工作流代码编译为 SQL，从而创建可在 BigQuery 中运行的工作区的编译结果。Dataform 使用您在工作流设置文件中定义的设置来创建编译结果。

Dataform 编译是封闭的，以确保编译一致性，这意味着相同的代码每次都会编译为相同的 SQL 编译结果。Dataform 会在无法访问互联网的沙盒环境中编译代码。在编译期间，无法执行其他操作，例如调用外部 API。

执行

在工作流调用中，Dataform 会在 BigQuery 中运行工作区编译结果。

如需根据您的需求定制 Dataform 工作流生命周期，您可以配置编译结果，以影响 Dataform 运行工作流的位置和方式。然后，您可以手动触发或安排执行，以影响 Dataform 何时运行整个工作流或其所选元素。

配置 Dataform 编译的方式

默认情况下，Dataform 使用工作流设置文件中的设置来创建编译结果。您可以使用编译替换项来替换默认设置，以创建自定义编译结果。然后，您可以手动触发自定义编译结果的执行，或安排执行。

Dataform 提供了以下用于配置编译结果的选项：

工作区编译替换
您可以配置适用于代码库中所有工作区的编译替换。您可以使用工作区编译替换来创建隔离的开发环境。
版本配置
您可以创建发布配置，以配置用于创建 Dataform 代码库编译结果的模板。然后，您可以创建工作流配置，以安排在所选发布配置中创建的编译结果的执行。
Dataform API 编译替换
您可以在终端中传递 Dataform API 请求，以创建和运行具有编译替换项的单个编译结果。

配置工作区编译替换

借助工作区编译替换，您可以为 Dataform 代码库中的所有工作区创建编译替换。您可以为每个代码库创建一个工作区编译替换配置。

当您在具有工作区编译替换的代码库中手动触发工作区中的执行时，Dataform 会将这些替换应用于工作区的编译结果。

您可以配置以下工作区编译替换：

  • Google Cloud Dataform 在其中运行工作区内容的
  • 表前缀
  • 架构后缀

您可以使用工作区编译替换，通过动态编译替换在 BigQuery 中隔离工作区编译结果，从而创建隔离的开发环境。动态表前缀和架构后缀编译替换包含 ${workspaceName} 变量。当您在工作区中触发执行时，Dataform 会将 ${workspaceName} 变量替换为当前工作区的名称，从而创建工作区独有的编译替换。

请注意，您无法安排执行使用工作区编译替换创建的编译结果。

创建发布配置

借助发布配置，您可以配置设置模板，以创建代码库的编译结果。

在发布配置中，您可以配置工作流设置的编译替换、编译变量以及创建整个代码库的编译结果的频率。

在发布配置中，您可以配置以下编译替换：

  • Google Cloud 项目
  • 表前缀
  • 架构后缀
  • 编译变量的值

您可以在 Dataform 代码库中创建多个发布配置，每个发布配置对应开发生命周期的每个阶段，从而创建隔离的代码库编译结果。

然后，您可以创建工作流配置，以安排在所选版本配置中创建的编译结果的执行。

您还可以手动在所选发布配置中触发编译结果的执行。

使用 Dataform API 编译替换项配置单个编译结果

通过在终端中传递 Dataform API 请求，您可以为单个编译结果配置编译替换。

在 compilationResults.create 请求中，您可以创建 Dataform 工作区或指定 Git commitish（可以是分支、标记或提交 SHA）的单个编译结果。

在 compilationResults.create 请求的 CodeCompilationConfig 对象中，您可以为编译请求配置编译替换。

您可以配置以下 Dataform API 编译替换：

  • Google Cloud 项目
  • 表前缀
  • 架构后缀
  • 编译变量的值

请注意，Dataform API 编译替换项适用于单个编译结果和单次执行。您无法使用它们来安排 Dataform 执行。

您可以在 workflowInvocations.create 请求中运行编译结果。

配置 Dataform 执行的方式

Dataform 提供了以下用于配置执行的选项：

在工作区中手动执行
您可以在 Dataform 工作区中手动触发工作流的即时执行，而不受任何时间表的限制。您可以运行工作流中的选定操作。
工作流配置
您可以安排在所选发布配置中创建的编译结果的执行。您可以选择要运行的工作流操作，并设置执行频率和时区。

在工作区中触发即时执行

在 Dataform 工作区中，您可以手动触发工作区中工作流的即时执行，而不受任何时间表的限制。

您可以在工作区中手动运行工作流的以下元素：

如果您的代码库包含工作区编译替换，您可以查看 Dataform 将应用于工作区编译结果的编译替换。

创建工作流配置

借助工作流配置，您可以安排从所选发布配置执行编译结果。您可以在 Dataform 代码库中创建多个工作流配置。

在工作流配置中，您可以配置以下执行设置：

  • 已应用编译版本配置。
  • 选择要运行的工作流操作。
  • 执行的时间表和时区。

您可以选择要运行的以下工作流操作：

  • 所有操作
  • 所选操作
  • 对所选标签执行的操作

然后，在工作流配置的预定执行期间，Dataform 会将您从应用编译结果中选择的操作部署到 BigQuery。

借助 Dataform 版本配置和工作流配置，您可以在 Dataform 中配置编译和安排执行，而无需依赖其他服务。

生命周期资源到期

Dataform 会在特定时间段内存储编译结果和工作流调用。

工作流调用过期

工作流调用会在 90 天后或您手动删除时过期。

在工作流配置中，您可以查看由该配置创建的最新工作流调用列表。当由工作流配置创建的工作流调用过期时，Dataform 会从最近调用列表中移除该工作流调用。

编译结果过期

编译结果的过期时间取决于它们是在开发工作区中、在发布配置中还是通过工作流调用创建的。

当您在 Dataform 工作区中开发工作流时，Dataform 会实时将代码编译为编译结果，以提供查询验证。以这种方式创建的编译结果会在 24 小时后过期。

在发布配置中，最新的编译结果会成为实时编译结果。新的编译结果会替换当前的实时编译结果。Dataform 会保留实时编译结果，直到其被新的编译结果替换。被替换的编译结果最多会在 24 小时后过期。

Dataform 会从发布配置的详细信息页面上的过去编译结果列表中移除过期的编译结果。

Dataform 会在工作流调用的整个生命周期内保留由工作流调用创建的编译结果，最长保留至工作流调用过期或删除后 24 小时。

创建工作区编译替换

本部分介绍了如何创建工作区编译替换，以隔离在 BigQuery 中通过 Dataform 工作区创建的表和视图。您可以使用工作区编译替换来创建隔离的 Dataform 开发环境。

当您在 Dataform 工作区中开发工作流代码时，Dataform 会实时编译工作区中的代码，以创建工作区的编译结果。Dataform 使用工作流设置文件中定义的设置来创建工作区编译结果。然后，当您在工作区中触发执行时，Dataform 会在 BigQuery 中运行工作区编译结果。

如需替换代码库中所有工作区的工作流设置中设置的默认设置，您可以创建工作区编译替换。

借助工作区编译替换，您可以替换代码库中所有工作区的以下设置：

项目

Dataform 在其中运行工作区编译结果的 Google Cloud 项目，在 workflow_settings.yaml 中设置为 defaultProject，或在 dataform.json 中设置为 defaultDatabase。

表前缀

添加到代码库中所有工作区内所有表名称的自定义前缀。

架构后缀

附加到表架构的自定义后缀。在 workflow_settings.yaml 中设置为 defaultDataset，在 dataform.json 中设置为 defaultSchema，或在表的 config 块中的 schema 参数中设置。

如需创建隔离的开发环境，您可以使用唯一的编译替换来隔离工作区。您可以使用 ${workspaceName} 变量动态修改表前缀和架构后缀编译替换。

当您在工作区中手动触发执行时，${workspaceName} 变量会将工作区的名称注入工作区编译替换。

将 ${workspaceName} 设置为表前缀时，Dataform 会将工作区的名称添加到工作区中所有表的名称中。执行后，您可以在 BigQuery 中确定表源自哪个工作区。

当您将 ${workspaceName} 设置为架构后缀时，Dataform 会将工作区的名称附加到 defaultSchema，从而创建专用于该工作区的自定义架构。执行后，您可以在 BigQuery 中找到从专用架构中的特定工作区运行的所有表。

动态工作区编译替换示例

以下示例展示了应用于代码库的动态工作区编译替换，该代码库包含以处理该代码库的开发者命名的工作区：Sasha 和 Kai。

此示例中工作区编译替换的目标是为 Sasha 和 Kai 创建隔离的开发环境。

workflow_settings.yaml 中设置了以下默认设置：

  • defaultProject:analytics
  • defaultDataset：dataform

以下工作区编译替换会为代码库中的每个工作区创建动态表前缀和架构后缀：

  • Google Cloud 项目 ID：analytics_dev
  • 表前缀：${workspaceName}
  • 架构后缀：${workspaceName}

当 Sasha 在 Sasha 工作区中手动触发执行时，Dataform 会使用以下设置运行其内容：

  • Google Cloud project: analytics_dev
  • 架构：dataform_sasha
  • 表名称：sasha_name，例如 sasha_orders

当 Kai 在 Kai 工作区中手动触发执行时，Dataform 会使用以下设置运行其内容：

  • Google Cloud project: analytics_dev
  • 架构：dataform_kai
  • 表名称：kai_name，例如 kai_orders

创建工作区编译替换

如需创建 Dataform 工作区编译替换，请按以下步骤操作：

  1. 在代码库中，前往设置。
  2. 点击修改。
  3. 在工作区编译替换窗格的 Google Cloud 项目 ID 字段中，输入项目的 ID。
  4. 在表前缀字段中，输入所有表名称的前缀。
    1. 可选：如需创建对每个工作区都唯一的动态表前缀，请输入 ${workspaceName} 作为表前缀。
  5. 在架构后缀字段中，输入要附加到所创建表或视图的架构的后缀。
    1. 可选：如需创建对每个工作区都唯一的动态架构后缀，请输入 ${workspaceName} 作为表后缀。
  6. 点击保存。

Dataform 会将工作区编译替换应用于您代码库中的所有工作区。

修改工作区编译替换

如需修改 Dataform 工作区编译替换，请按以下步骤操作：

  1. 在代码库中，前往设置。
  2. 点击修改。
  3. 修改工作区编译替换，然后点击保存。

删除工作区编译替换

如需删除 Dataform 工作区编译替换，请按以下步骤操作：

  1. 在代码库中，前往设置。
  2. 点击修改。
  3. 在工作区编译替换窗格中，点击全部清除，然后点击保存。

使用 Dataform API 配置编译替换

本部分介绍了如何使用 Dataform API 创建和运行具有编译替换项的编译结果。

Dataform API 编译替换项简介

为了运行工作流，Dataform 会将代码编译为 SQL，以创建编译结果。然后，在工作流调用期间，Dataform 会在 BigQuery 中运行编译结果。

默认情况下，Dataform 会使用工作流设置文件中的设置来创建编译结果。如需隔离在开发生命周期的不同阶段运行的数据，您可以使用编译替换来替换默认设置。

通过在终端中传递 Dataform API 请求，您可以创建和运行具有编译替换项的单个编译结果。您可以创建工作区或所选 Git 提交（例如分支、标记或提交 SHA）的编译结果。

如需创建具有编译替换项的编译结果，您需要发出 Dataform API compilationResults.create 请求。在请求中，您需要指定一个来源（应为工作区或 Git commitish），以便 Dataform 编译到编译结果中。在 compilationResults.create 请求的 CodeCompilationConfig 对象中，您可以配置编译替换。

然后，您可以在 Dataform API workflowInvocations.create 请求中运行创建的编译结果。

您可以配置以下 Dataform API 编译替换：

Google Cloud 项目

Dataform 在其中运行编译结果的项目，在 workflow_settings.yaml 文件中设置为 defaultProject 属性，或在 dataform.json 文件中设置为 defaultDatabase 属性。

表前缀

添加到编译结果中所有表名称的自定义前缀。

架构后缀

附加到 workflow_settings.yaml 文件中的 defaultDataset 属性、dataform.json 文件中的 defaultSchema 属性或表的 config 块中的 schema 参数中定义的表架构的自定义后缀。

编译变量的值

要在编译结果中使用的编译变量的值。您可以使用编译变量有条件地运行表。

除了只能用于一个编译结果的 Dataform API 编译替换之外，您还可以在 Google Cloud 控制台中配置工作区编译替换。

如需了解在 Dataform 中配置编译替换的其他方法，请参阅 Dataform 中的工作流生命周期简介。

设置编译结果来源

如需发出 Dataform API compilationResults.create 请求，您需要为编译结果指定来源。

您可以在 compilationResults.create 请求中将 Dataform 工作区或 Git 分支、Git 标记或 Git 提交 SHA 设置为来源。

将工作区设置为编译结果来源

  • 在 compilationResults.create 请求中，使用所选 Dataform 工作区的路径填充 workspace 属性，格式如下：

    {
"workspace": "projects/PROJECT_NAME/locations/LOCATION/repositories/REPOSITORY_NAME/workspaces/WORKSPACE_NAME"
}

    替换以下内容：

    • PROJECT_NAME：您的 Google Cloud 项目的名称。
    • LOCATION：Dataform 代码库的位置，在工作流设置中设置。
    • REPOSITORY_NAME：Dataform 代码库的名称。
    • WORKSPACE_NAME：Dataform 工作区的名称。

以下代码示例展示了 compilationResults.create 请求中的 workspace 属性，该属性设置为名为 "sales-test" 的工作区：

{
"workspace": "projects/analytics/locations/europe-west4/repositories/sales/workspaces/sales-test"
}

将 Git commitish 设置为编译结果来源

  • 在 compilationResults.create 请求中，使用所选 Git 分支、标记或提交 SHA 按以下格式填充 gitCommitish 属性：

    {
  "gitCommitish": "GIT_COMMITISH"
}

    将 GIT_COMMITISH 替换为所选 Git 分支、Git 标记或编译结果的 Git 提交 SHA。

以下代码示例展示了 compilationResults.create 请求中的 gitCommitish 属性设置为 "staging"：

{
  "gitCommitish": "staging"
}

替换默认项目

如需在与开发项目不同的 Google Cloud 项目中创建预演表或生产表，您可以在 Dataform API compilationResults.create 请求中的 CodeCompilationConfig 对象中传递其他项目 ID。

在 compilationResults.create 请求中传递单独的默认项目 ID 会覆盖工作流设置文件中配置的默认项目 ID，但不会覆盖在各个表中配置的项目 ID。

  • 如需替换默认项目 ID，请在 CodeCompilationConfig 对象中将 defaultDatabase 属性设置为所选项目 ID，格式如下：

    {
  "codeCompilationConfig": {
    "defaultDatabase": "PROJECT_NAME"
  }
}

    将 PROJECT_NAME 替换为您要为编译结果设置的项目 ID。

添加表前缀

如需快速识别编译结果中的表，您可以在 Dataform API compilationResults.create 请求中将表前缀传递到 CodeCompilationConfig 对象，从而为编译结果中的所有表名称添加前缀。

  • 如需添加表前缀，请按以下格式在 CodeCompilationConfig 对象中设置 tablePrefix 属性：

    {
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

    将 PREFIX 替换为您要附加的前缀，例如 staging。

    例如，如果您的表名称为 table_name，则 Dataform 会创建名称为 staging_table_name 的表。

附加架构后缀

如需分离开发、预演和生产数据，您可以在 Dataform API compilationResults.create 请求的 CodeCompilationConfig 对象中传递架构后缀，从而为编译结果中的架构附加后缀。

  • 如需附加架构后缀，请按以下格式在 CodeCompilationConfig 对象中设置 schemaSuffix 属性：

    {
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

    将 SUFFIX 替换为您要附加的后缀，例如 _staging。

    例如，如果 workflow_settings.yaml 文件中的 defaultDataset 属性设置为 dataform，则 Dataform 会在 dataform_staging 架构中创建表。

使用编译变量有条件地运行所选文件

如需仅在特定执行设置中运行所选表，您可以为执行设置创建编译变量，然后在 Dataform API compilationResults.create 请求的 CodeCompilationConfig 对象中传递其值。

如需使用 Dataform API 在特定执行设置中有条件地运行表，请按以下步骤操作：

  1. 创建编译变量并将其添加到所选表中。

  2. 在 Dataform API 编译请求的 codeCompilationConfig 块中，按以下格式设置 YOUR_VARIABLE 和 VALUE 键值对：

    {
  "codeCompilationConfig": {
    "vars": {
      "YOUR_VARIABLE": "VALUE"
    }
  }
}

  3. 将 YOUR_VARIABLE 替换为变量的名称，例如 executionSetting。

  4. 将 VALUE 替换为此编译结果的变量值，该值满足在所选表中设置的 when 条件。

以下代码示例展示了传递给 Dataform API 编译请求的 executionSetting 变量：

{
  "gitCommitish": "staging",
  "codeCompilationConfig": {
    "vars": {
      "executionSetting": "staging"
    }
  }
}

使用编译替换项运行编译结果

以下代码示例展示了在 workflowInvocations.create 请求中传递的编译结果 ID：

{
  "compilationResult": "projects/my-project-name/locations/europe-west4/repositories/my-repository-name/compilationResults/7646b4ed-ac8e-447f-93cf-63c43249ff11"
}

创建版本配置

本部分介绍如何在 Dataform 中创建发布配置，以配置编译设置模板，您可以按时间表运行这些模板。您可以使用版本配置来配置执行环境，例如预演环境和生产环境。

为了在 BigQuery 中运行工作流，Dataform 会将 SQL 工作流代码编译为编译结果。当您在 Dataform 工作区中开发工作流时，此过程会自动发生。

借助版本配置，您可以自定义编译结果。您可以使用它们来创建执行环境，例如预演。

版本配置设置

在版本配置中，您可以配置工作流设置的编译替换、设置编译变量，以及设置创建编译结果的频率。

Dataform 版本配置包含以下编译设置：

发布版本设置
发布配置的 ID、编译结果的 Git commitish（例如分支、标记或提交 SHA），以及创建编译结果的频率。频率是一项可选设置。如果设置，则最低频率为 1 小时。
编译替换
覆盖工作流设置中定义的Google Cloud 项目、表前缀、架构后缀和编译变量。

版本配置的工作原理

Dataform 会按照指定的频率或在您触发编译时，根据版本配置创建编译结果。频率是一项可选设置，创建发布配置时并非必须设置。如果设置，则最小频率为 1 小时。您可以在版本配置详情页面上手动触发编译，也可以使用 Dataform API releaseConfigs 方法触发编译。

在编译期间，Dataform 会从代码库的指定 Git commitish 中拉取代码。然后，Dataform 会使用应用的编译替换项（如果有）编译代码，并创建编译结果。为发布配置创建的最新编译结果是实时编译结果。

您可以在工作流配置中安排从版本配置执行编译结果。您还可以在任何时间表之外运行所选发布配置。在工作流配置执行期间，Dataform 会运行所选版本配置中的实时编译结果。

创建版本配置

如需创建 Dataform 版本配置，请按照以下步骤操作：

  1. 在代码库中，前往版本和时间安排。
  2. 在版本配置部分中，点击创建。

  3. 在创建发布配置窗格中，配置发布设置。

    1. 在发行 ID 字段中，输入发行配置的唯一 ID。

      ID 只能包含数字、字母、连字符和下划线。

    2. 在 Git 提交字段中，输入分支（例如 main）、标记或版本的提交 SHA。

      在未连接到远程代码库的 Dataform 代码库中，该值始终为 main。

    3. 可选：在频率字段中，选择创建编译结果的频率。

      如果设置，则最低频率为 1 小时。

      如需停用自动发布，请将频率字段留空。

  4. 可选：在编译替换部分中，配置编译设置。

    1. 在 Google Cloud 项目 ID 字段中，输入要在其中存储编译结果的Google Cloud 项目的 ID。
    2. 在架构后缀字段中，输入要附加到工作流设置中配置的架构的后缀。
    3. 在表前缀字段中，输入所有表名称的前缀。

  5. 可选：在编译变量部分中，设置编译变量。

    1. 点击添加变量。
    2. 在键字段中，输入编译变量。
    3. 在值字段中，输入编译变量的值。
    4. 如需添加其他编译变量，请点击添加变量。

  6. 点击创建。

如果您替换默认项目，请确保您的自定义服务账号有权访问发布配置中设置的项目。

例如，以下发布配置每小时从 main 分支创建 production 编译结果，没有任何编译替换：

  • 发行 ID：production
  • Git commitish：main
  • 频率：每小时
  • 没有编译替换

查看发布配置的详细信息

您可以查看发布配置的以下详细信息：

  • 发布版本设置
    • Git Commitish
    • 最新编译结果时间戳
    • Cron 时间表
    • 编译替换
    • 编译变量
  • 实时编译结果
    • 创建时间戳
    • Git Commitish
    • 提交 SHA
  • 过往编译结果

如需查看发布配置的详细信息，请按以下步骤操作：

  1. 在代码库中，前往版本和时间安排。
  2. 选择发布配置。
  3. 在版本配置详细信息页面上，检查版本配置的详细信息。

已安排的编译结果表会显示由版本配置自动创建的过往编译结果。

手动/API 编译结果表显示代码库中最近 1,000 个编译结果中手动创建或通过调用 Dataform API 创建的编译结果。

手动触发编译

如需通过所选发布配置手动创建编译结果，请按照以下步骤操作：

  1. 在代码库中，前往版本和时间安排。
  2. 选择发布配置。
  3. 在版本配置详情页面上，点击新建编译。

如果您使用的是界面，新编译的结果会自动在您的版本配置中生效。如果您使用的是 API，则必须通过发布配置创建新的编译结果，然后更新发布配置，以使用此新值设置 releaseCompilationResult 字段。

手动编译结果会显示在发布配置详细信息页面上的手动/API 编译结果表中。

触发版本配置的执行

如需触发在所选发布配置中执行实时编译结果到 BigQuery，请按照以下步骤操作：

  1. 在代码库中，前往版本和时间安排。
  2. 在版本配置部分中，点击开始执行。
  3. 在执行手动工作流窗格的版本配置列表中，选择一个版本配置。
  4. 选择要运行的工作流操作：
    1. 如需运行整个工作流，请点击所有操作。
    2. 如需在工作流中运行所选操作，请点击选择操作，然后选择操作。
    3. 如需使用所选标记运行操作，请点击选择标记，然后选择标记。
  5. 可选：如需运行所选操作或标记及其依赖项，请选择包含依赖项选项。
  6. 可选：如需运行所选操作或标记及其依赖项，请选择包含依赖项选项。

  7. 可选：如需从头开始重新构建所有表，请选择运行并完全刷新选项。

    如果不使用此选项，Dataform 会更新增量表，而不会从头开始重新构建。

  8. 点击开始执行。

修改版本配置

如需修改发布配置，请按以下步骤操作：

  1. 在代码库中，前往版本和时间安排。
  2. 在要修改的版本配置旁边，点击 更多菜单，然后点击修改。
  3. 在修改发布配置窗格中，修改发布配置设置，然后点击保存。

删除发布配置

如需删除发布配置，请按照以下步骤操作：

  1. 在代码库中，前往版本和时间安排。
  2. 在要删除的版本配置旁边，点击 更多菜单，然后点击删除。
  3. 在删除版本配置对话框中，点击删除。

后续步骤