使用 Dataform API 配置编译替换项

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

Dataform API 编译替换项简介

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

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

通过在终端中传递 Dataform API 请求，您可以使用编译替换项创建和执行单个编译结果。您可以创建工作区或所选 Git 提交的编译结果。

如需创建包含编译替换项的编译结果，您需要发出 Dataform API compilationResults.create 请求。在请求中，您需要指定来源（工作区或 Git 提交内容），以便 Dataform 编译为编译结果。在 compilationResults.create 请求的 CodeCompilationConfig 对象中，您可以配置编译替换项。

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

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

Google Cloud项目：Dataform 执行编译结果的 Google Cloud 项目，在 workflow_settings.yaml 中设置为 defaultProject，或在 dataform.json 中设置为 defaultDatabase。

表前缀
向编译结果中的所有表名称添加了自定义前缀。
架构后缀
附加到 workflow_settings.yaml 中的 defaultDataset、dataform.json 中的 defaultSchema 或表的 config 代码块中的 schema 参数中定义的表的架构的自定义后缀。

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

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

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

准备工作

  1. 在 Google Cloud 控制台中，进入 Dataform 页面。

    前往 Dataform

  2. 选择或创建代码库。

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

设置编译结果来源

如需发出 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 提交内容设置为编译结果源

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

    {
  "gitCommitish": "GIT_COMMITISH"
}

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

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

{
  "gitCommitish": "staging"
}

替换默认 Google Cloud 项目

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

在 compilationResults.create 请求中传递单独的默认项目 ID 会覆盖工作流设置文件中配置的默认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。例如，如果 workflow_settings.yaml 中的 defaultDataset 设置为 dataform，Dataform 将在 dataform_staging 架构中创建表。

附加架构后缀

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

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

将 SUFFIX 替换为您要附加的后缀，例如 _staging。例如，如果 workflow_settings.yaml 中的 defaultDataset 设置为 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"
}

后续步骤