使用 Dataform API 配置编译替换

本文档介绍了如何使用 Dataform API 创建和执行具有编译替换的编译结果。

Dataform API 编译替换简介

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

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

通过在终端中传递 Dataform API 请求，您可以创建和执行具有编译替换的单个编译结果。您可以创建工作区或所选 Git 委员会的编译结果。

如需创建具有编译替换的编译结果，您需要提交 Dataform API compilationResults.create 请求。在请求中，您需要指定来源、工作区或 Git 承诺，以便 Dataform 编译到编译结果中。在 compilationResults.create 请求的 CodeCompilationConfig 对象中，您可以配置编译替换。

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

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

Google Cloud 项目
Dataform 执行编译结果的 Google Cloud 项目，在 dataform.json 中设置为 defaultDatabase。
表前缀
添加到编译结果中所有表名称的自定义前缀。
架构后缀
自定义后缀，附加到 dataform.json 的 defaultSchema 中的表架构，或表的 config 块的 schema 参数中定义的表架构。
编译变量的值
要在编译结果中使用的编译变量的值。您可以使用编译变量有条件地执行表。

作为只能用于一个编译结果的 Dataform API 编译替换的替代方案，您可以在 Google Cloud 控制台中配置工作区编译替换。

准备工作

  1. 在 Google Cloud 控制台中，转到 Dataform 页面。

    转到 Dataform

  2. 选择或创建代码库。

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

设置编译结果来源

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

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

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

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

请替换以下内容：

  • 将 PROJECT_NAME 替换为您的 Google Cloud 项目的名称。
  • 将 LOCATION 替换为 Dataform 代码库的位置，在 dataform.json 中设置。
  • 将 REPOSITORY_NAME 替换为 Dataform 代码库的名称。
  • 将 WORKSPACE_NAME 替换为 Dataform 工作区的名称。

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

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

将 Git 提交设置为编译结果来源

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

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

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

{
  "gitCommitish": "staging"
}

替换默认的 Google Cloud 项目

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

在 compilationResults.create 请求中传递单独的默认项目 ID 会替换 dataform.json 文件中配置的默认 Google Cloud 项目 ID，但不会替换各个表中配置的 Google Cloud 项目 ID。

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

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

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

添加表前缀

为了轻松从编译结果中识别表，您可以向编译结果中的所有表名称添加前缀
，方法是在 Dataform API compilationResults.create 请求的 CodeCompilationConfig 对象中传递表前缀。

  • 如需添加表前缀，请按以下格式在 CodeCompilationConfig 对象中设置 tablePrefix 属性：
{
  "codeCompilationConfig": {
    "tablePrefix": "PREFIX",
  }
}

将 PREFIX 替换为您要附加的后缀，例如 _staging。例如，如果 dataform.json 中的 defaultSchema 设置为 dataform，Dataform 将在 dataform_staging 架构中创建表。

附加架构后缀

为了分隔开发、预演和生产数据，您可以在编译结果中向架构附加后缀，方法是在 Dataform API compilationResults.create 请求的 CodeCompilationConfig 对象中传递架构后缀。

  • 如需附加架构后缀，请按以下格式在 CodeCompilationConfig 对象中设置 schemaSuffix 属性：
{
  "codeCompilationConfig": {
    "schemaSuffix": "SUFFIX",
  }
}

将 SUFFIX 替换为您要附加的后缀，例如 _staging。例如，如果 dataform.json 中的 defaultSchema 设置为 dataform，Dataform 将在 dataform_staging 架构中创建表。

注意：CodeCompilationConfig schemaSuffix 参数会替换在具体文件的 config 块中配置的架构。

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

若要仅在特定执行设置中执行所选表，您可以为执行设置创建编译变量，然后在 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"
}

后续步骤