本頁面由 Cloud Translation API 翻譯而成。

Looker CI/CD 用途和工作流程

本頁說明如何安裝及設定 CI/CD 工作流程後，在 Looker 中使用該工作流程。

這些操作說明使用三層式系統，包含開發、QA 和實際工作環境。不過，您也可以將相同原則套用至兩層或四層系統。

這些操作說明也假設您使用 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

每次發布版本修正錯誤時，PATCH 就會遞增
每當發布版本新增或改善功能，同時維持回溯相容性時，MINOR 就會遞增，而 PATCH 則會重設為零
新增不回溯相容的功能時，MAJOR 會遞增，且 MINOR 和 PATCH 都會設為零

傳統提交是根據提交對使用者的影響來命名提交的系統。雖然不是必要條件，但使用傳統的提交命名方式，對 Release Please 外掛程式也很有幫助。

在傳統的提交命名方式中，每個提交訊息都會加上變更範圍的指標：

錯誤修正會以 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 的進階部署模式會將這些版本提供給 QA 和正式環境例項的 Looker UI。

如要部署變更，請從 Looker IDE 選擇 Deployment Manager：

IDE 中的 Looker Deployment Manager 位置。

按一下 Deployment Manager 右上方的「Select Commit」連結。接著，選取要部署的代碼相關聯的三點選單，然後選擇「部署至環境」：

Looker Deployment Manager 使用者介面，用於部署至環境。

您不需要再次標記部署作業，因此請選擇「Deploy without tagging」(部署但不標記)，然後按下「Deploy to Environment」(部署至環境) 按鈕：

Looker Deployment Manager UI，用於不加上標記而直接部署。

最後，使用 Deployment Manager 推送至正式環境。

使用 Spectacles

開發人員可以使用 Spectacles 驗證變更，即使變更仍在開發分支中也沒問題。Spectacles 提供四種不同的驗證器：

SQL
LookML
內容
Assert

開發人員提交提取要求時，建議執行這些測試，並將結果複製到提取要求中的註解。

SQL Validator

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 Validator

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.

Content Validator

內容驗證器會測試儲存的內容 (例如 Look 和使用者定義的資訊主頁 (UDD)) 在變更後是否仍可正常運作。為加快作業執行速度並提供可管理的結果，系統只會驗證您指定探索內容的相關內容。Content Validator 的呼叫方式如下：

$ 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.

Assert Validation

Assert 驗證測試會驗證您新增至 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，用於 Look 或資訊主頁的網址。不過，這些資料無法在不同系統之間保持同步。因此，開發環境中特定資訊主頁的網址，不會指向 QA 或實際工作環境中的相同資訊主頁。

對於 UDD，您可以選擇使用 Slug，而非 ID 做為網址的一部分。Slug 是半隨機的字元組合，而非數字。您可以在匯入時設定代碼，這樣類似的網址就能在開發、品質保證和正式環境中指向同一個 UDD。使用代碼而非 ID 是最佳做法，特別是從 Look 或其他 UDD「按一下」前往 UDD 時。

檢查 gzr dashboard cat 的輸出內容，即可找到 slug。您可以在資訊主頁網址中使用代碼，取代數字 ID。

使用 Gazer 遷移使用者內容

在開發、QA 和正式環境之間複製 Look 和資訊主頁等內容，通常很有用。您可能想製作內容來展示新增的 LookML，或是驗證儲存的內容在 LookML 變更後是否仍正常運作。在這種情況下，您可以使用 Gazer 在執行個體之間複製內容。

LookML 資訊主頁

在一般的 LookML CI/CD 工作流程中，系統會在執行個體之間同步處理 LookML 資訊主頁。不過，如果任何 UDD 與 LookML 資訊主頁同步，可以使用下列指令透過 Gazer 更新：

gzr dashboard sync_lookml DASHBOARD_ID --host TARGET_SYSTEM_URL

使用者定義的資訊主頁

您可以透過 Gazer 遷移使用者定義的資訊主頁 (UDD)，方法是參照資訊主頁的 ID，以及 UDD 所在的 Looker 執行個體網址。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 圖表

目標對象遷移的運作方式與使用者定義資料遷移非常相似。首先，使用 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