使用 Dataform API 配置编译替换

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

Dataform API 编译替换简介

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

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

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

如需创建包含编译替换的编译结果，您需要发出 Dataform API compilationResults.create 请求。在该请求中，您需要指定来源（工作区或 Git Commitish），以便 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 请求，您需要指定编译结果的来源。

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

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

  • 在 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 工作区的名称。

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

{
"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。

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

{
  "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，请按以下格式将 defaultDatabase 属性设置为 CodeCompilationConfig 对象中的所选 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"
}

后续步骤