Looker CI/CD 使用和工作流

注意： Looker 的新持续集成功能（现已推出预览版）将使此方法过时。

本页面介绍了如何在安装和配置 CI/CD 工作流后在 Looker 中使用该工作流。

这些说明使用包含开发、质量检查和生产的三层系统。不过，您也可以将这些原则应用于双层或四层系统。

这些说明还假设您使用 GitHub 作为 Git 提供方。您可以使用其他 Git 提供商来创建 CI/CD 工作流；不过，您必须具备相关专业知识，才能根据您的提供商修改这些说明。

工作流概览

LookML 开发者首先在其开发分支（通常命名为 dev-my-user-ydnv 之类）中编写代码，然后使用 Spectacles 测试其更改，并提交其代码。最后，他们打开拉取请求，以将其代码与 main 分支合并。

当拉取请求打开时，系统会将开发者带到 GitHub。开发者应使用常规提交样式编写有意义的 PR 标题，并向说明中添加将包含在更改日志中的注释。Spectacles 测试的结果应作为注释添加到 PR 中。

接下来，开发者应在 GitHub 中选择审核者。审核者会收到通知，并可向 PR 添加其审核意见。如果审核人员批准了相应更改，则 PR 会与 main 分支合并。系统会调用 WebHook，开发环境现在会看到相应更改。

Release Please 自动化流程将自动运行，并打开第二个 PR 以创建新的带标记的版本。或者，如果已经有为此目的而打开的 PR，Release Please 会更新该 PR。发布 PR 具有关联的版本号，以及包含所含变更的标题和说明的更改日志。

当 Release Please 生成的 PR 获得批准并合并后，系统会生成新的版本标记，并将更改日志与 main 分支合并。Looker 的 QA 实例和生产实例可以使用高级部署模式选择此版本。

有关版本编号和提交命名方面的最佳实践

您可以根据自己的环境，以任何有意义的方式命名和编号版本及其关联的标记。不过，此处使用的是语义版本控制，强烈建议您也使用此方法，因为它可与 Release Please 插件完美搭配。

在语义版本控制中，版本由三个以英文句点分隔的数字组成：MAJOR.MINOR.PATCH

• 每次发布版本修复 bug 时，PATCH 都会递增
• 每次发布在保持向后兼容性的同时添加或改进功能时，MINOR 都会递增，而 PATCH 会重置为零
• 当添加不向后兼容的功能时，MAJOR 会递增，而 MINOR 和 PATCH 都会设置为零

常规提交是一种根据提交对最终用户的影响来命名提交的系统。虽然不是必需的，但使用常规提交命名对于 Release Please 插件也很有用。

在常规提交命名中，每个提交消息前面都会附加一个指示更改范围的标识符：

• bug 修复以 fix: 表示，例如 fix: set proper currency symbol on sale_amt format
• 新功能会用 feat: 表示，例如 feat: added explore for sales by territory
• 具有重大变更的功能用 feat!: 表示，例如 feat!: rewrote sales explore to use the new calendar view
• 如果文档已更新，但 LookML 未更改，提交消息以 doc: 开头

如果常规提交得到了一致使用，那么确定接下来要使用的语义版本号通常很简单。如果提交日志仅包含 fix: 和 doc: 提交，则应递增 PATCH。如果存在 feat: 提交，则应递增 MINOR。如果存在 feat!:，则应递增 MAJOR。Release Please 插件甚至可以自动生成 CHANGELOG 文件并标记发布版本。

使用高级部署模式

在开发实例上提交 PR 并做出更改后，Release Please 插件将使用版本标记（例如 v1.2.3）标记这些更改。然后，Looker 的高级部署模式会在 Looker 界面中为 QA 和生产实例提供这些版本。

如需部署更改，请从 Looker IDE 中选择 Deployment Manager：

点击 Deployment Manager 右上角的 Select Commit（选择提交）链接。接下来，选择与要部署的代码相关联的三点状菜单，然后选择部署到环境：

您无需再次标记部署，因此请选择部署但不标记，然后按部署到环境按钮：

最后，使用 Deployment Manager 推送到生产环境。

使用 Spectacles

每位开发者都可以使用 Spectacles 来验证其在开发分支中所做的更改。Spectacles 提供了四种不同的验证器：

• SQL
• LookML
• 内容
• Assert

开发者提交拉取请求时，最好运行这些测试并将结果复制到拉取请求中的注释中。

SQL 验证器

SQL 验证器会测试每个探索，以验证 LookML 视图中定义的所有字段是否与数据库中的实际 SQL 列或有效的 SQL 表达式相对应。系统会按如下所示调用 SQL 验证器：

$ spectacles sql --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

例如：

$ spectacles sql --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0

=================== Testing 1/1 explores [concurrency = 10] ===================

✓ thelook_cicd.users passed

Completed SQL validation in 1 minute and 7 seconds.

LookML 验证器

LookML 验证器会验证 LookML 更改是否有效且没有语法错误。调用方式如下所示：

$ spectacles lookml --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --branch DEV_BRANCH_NAME

例如：

$ spectacles lookml --config-file config-dev.yaml \
    --project thelook_cicd \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0

============= Validating LookML in project thelook_cicd [warning] ==============

✗ thelook_cicd/business_pulse.dashboard.lookml failed
✗ thelook_cicd/thelook_cicd.model.lkml failed

================ thelook_cicd/business_pulse.dashboard.lookml:28 ===============

[Error] Unknown field "users.state" in explore "users" for field_filter.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=28

================ thelook_cicd/business_pulse.dashboard.lookml:36 ===============

[Warning] Unknown field "users.state" (for explore "orders" in model
"thelook_cicd") referenced in dashboard element.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/business_pulse.dashboard.lookml?line=36

[Additional errors snipped]

Completed validation in 6 seconds.

内容验证器

内容验证器会测试在做出更改后，所有已保存的内容（例如 Look 和用户定义的信息中心 [UDD]）是否仍能正常运行。为了加快作业运行速度并提供易于管理的结果，系统只会针对基于您指定的探索的内容进行验证。内容验证器的调用方式如下：

$ spectacles content --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

例如：

$ spectacles content --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv

==================== Validating content based on 5 explores ====================

✗ thelook_cicd.users failed

================= test dashboard for spectacles [TheLook_CICD] =================

Tile 'test dashboard for spectacles' failed validation.

Error in thelook_cicd/users: Unknown field "users.state".

Dashboard: https://gcpl2318.cloud.looker.com/dashboards/223

========================= Business Pulse [TheLook_CICD] ========================

Filter 'State / Region' failed validation.

Error in thelook_cicd/users: Unknown field "users.state".

Dashboard: https://gcpl2318.cloud.looker.com/dashboards/190

Completed content validation in 27 seconds.

断言验证

断言验证测试会验证您添加到 LookML 中的数据断言，以确认数据是否正在被正确读取。例如，LookML 中的数据测试可能如下所示：

test: historic_revenue_is_accurate {
  explore_source: orders {
    column: total_revenue { field: orders.total_revenue }
    filters: [orders.created_date: "2019"]
  }
  assert: revenue_is_expected_value {
    expression: ${orders.total_revenue} = 626000 ;;
  }
}

断言验证按如下所示的方式调用：

$ spectacles assert --config-file config-dev.yaml \
    --project PROJECT_NAME \
    --explores MODEL_NAME/EXPLORE_NAME \
    --branch DEV_BRANCH_NAME

例如：

$ spectacles assert --config-file config-dev.yaml \
    --project thelook_cicd \
    --explores thelook_cicd/users \
    --branch dev-my-user-ydnv

Connected to Looker version 23.18.60 using Looker API 4.0
Building LookML project hierarchy for project 'thelook_cicd' @ dev-my-user-ydnv

==================== Running data tests based on 1 explore =====================

✗ thelook_cicd.users failed

================ thelook_cicd/users/california_users_is_accurate ===============

Unknown filter field "users.state" in lookml test "california_users_is_accurate"
declaration.

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

================ thelook_cicd/users/california_users_is_accurate ===============

Invalid filter: users.state

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

================ thelook_cicd/users/california_users_is_accurate ===============

Assertion "count_is_expected_value" failed: expression evaluated to "No".

LookML: https://gcpl2318.cloud.looker.com/projects/thelook_cicd/files/thelook_cicd.model.lkml?line=55

Completed data test validation in 14 seconds.

Look 和信息中心的链接稳定性

默认情况下，Look 和信息中心会获得升序数字 ID，这些 ID 会在 Look 或信息中心的网址中使用。不过，无法在不同系统之间保持这些数据的同步。因此，开发环境中的特定信息中心网址不会指向质量检查或生产环境中的同一信息中心。

对于 UDD，可以选择使用别名而不是 ID 作为网址的一部分。slug 是一组半随机的字符，而不是数字。Slug 可在导入时设置，这样一来，相似的网址便可指向开发、QA 和生产环境中的同一 UDD。使用别名而非 ID 是一种最佳实践，尤其是在从 Look 或另一个 UDD“点击进入”UDD 时。

您可以通过检查 gzr dashboard cat 的输出内容来找到 slug。Slug 可在信息中心网址中代替数字 ID 使用。

使用 Gazer 迁移用户内容

在开发环境、QA 环境和生产环境之间复制 Look 和信息中心等内容通常很有用。您可能需要制作展示新 LookML 添加项的内容，或者验证保存的内容在 LookML 更改后是否仍能正常运行。在这些情况下，可以使用 Gazer 在实例之间复制内容。

LookML 信息中心

在常规 LookML CI/CD 工作流期间，LookML 信息中心会在实例之间同步。不过，如果有任何 UDD 与 LookML 信息中心同步，则可以使用以下命令通过 Gazer 更新这些 UDD：

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

用户定义的信息中心

通过引用信息中心的 ID 和 UDD 所在的 Looker 实例的网址，可以使用 Gazer 迁移用户定义的信息中心 (UDD)。Gazer 会将信息中心配置保存到 JSON 文件，然后将该文件导入到目标 Looker 实例。

用于提取 UDD 配置的命令如下所示：

gzr dashboard cat DASHBOARD_ID --host TARGET_SYSTEM_URL --dir .

这将生成一个名为 Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json 的文件，其中包含信息中心的配置。

可以使用以下命令将 UDD 导入到目标系统：

gzr dashboard import Dashboard_DASHBOARD_ID_DASHBOARD_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL

Look

Look 迁移的工作方式与 UDD 迁移非常相似。首先，使用 Gazer 将 Look 配置保存到 JSON 文件：

gzr look cat LOOK_ID --host SOURCE_SYSTEM_URL --dir .

然后，将 Look 导入到目标实例中：

gzr look import Look_LOOK_ID_LOOK_NAME.json FOLDER_ID \
    --host TARGET_SYSTEM_URL