設定彙整內容

本文說明如何在 Dataform 執行下列操作:

事前準備

  1. 前往 Google Cloud 控制台的「Dataform」頁面。

    前往 Dataform

  2. 選取或建立存放區。

  3. 選取或建立開發工作區。

  4. 選用:如要覆寫版本設定中的預設 Google Cloud 專案,請在您要使用的專案中,授予自訂服務帳戶存取權。

必要的角色

如要取得完成本文件工作所需的權限,請要求管理員授予您下列 IAM 角色:

如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

如要提高排程安全性,請參閱「實作強化排程權限」。

如要更新 Dataform 存放區版本設定的發布版本,您必須為使用這項版本設定的工作流程設定,將 iam.serviceAccounts.actAs 權限授予 Dataform 服務代理,用於每個自訂服務帳戶。服務帳戶使用者角色 (roles/iam.serviceAccountUser) 具備這項權限。詳情請參閱「授予必要的 IAM 角色」。

Dataform 工作流程生命週期簡介

本節說明 Dataform 的工作流程生命週期,以及在 Dataform 設定編譯和執行作業的方法。

Dataform 工作流程生命週期包含下列階段:

開發
您可以在 Dataform 工作區中開發工作流程。
編譯

Dataform 會即時將工作區中的工作流程程式碼編譯為 SQL,建立工作區的編譯結果,您可以在 BigQuery 中執行。Dataform 會使用您在工作流程設定檔中定義的設定,建立編譯結果。

Dataform 編譯作業是封閉式的,可確保編譯一致性,也就是說,相同的程式碼每次都會編譯成相同的 SQL 編譯結果。Dataform 會在沒有網路連線能力的沙箱環境中編譯程式碼。編譯期間無法執行其他動作,例如呼叫外部 API。

執行作業

在工作流程叫用中,Dataform 會在 BigQuery 執行工作區編譯結果。

您可以設定編譯結果,影響 Dataform 執行工作流程的位置和方式,根據需求調整 Dataform 工作流程生命週期。接著,您可以手動觸發或排定執行作業,影響 Dataform 執行整個工作流程或所選元素的時間。

比較編譯、驗證和執行

在 Dataform 中,編譯、查詢驗證和工作流程執行會分階段進行,並執行不同的檢查。

下表摘要說明 Dataform 如何處理各個階段:

階段 環境 Dataform 檢查項目 Dataform 不會檢查的項目
合輯 獨立 V8 沙箱,無法存取網際網路或 BigQuery
  • JavaScript 和 SQLX 語法
  • ref() 和 resolve() 解析度
  • 缺少或循環相依
  • 重複的動作目標
  • 編譯資源限制
  • GoogleSQL 語法或語意
  • BigQuery 中是否存在資料集或資料表
  • 資料欄結構定義或資料類型
  • BigQuery 的 IAM 權限
查詢驗證 (模擬測試) BigQuery 模擬測試工作
  • GoogleSQL 語法和語意
  • 參照的資料集、資料表、檢視表和資料欄是否存在
  • IAM 權限
  • 預估處理的位元組數
  • 資料品質斷言
  • 執行階段資料值
  • 尚未在 BigQuery 中建立的上游動作
工作流程執行作業 BigQuery 查詢工作
  • 依依附元件順序完整執行 GoogleSQL 查詢
  • 建立或更新資料集和資料表
  • IAM 權限
  • 自訂 SQL 作業
  • 資料品質斷言
不適用

編譯期間會發生的情況

編譯期間,Dataform 會在獨立的 V8 沙箱中評估 SQLX 和 JavaScript 檔案,不會連線至 BigQuery。Dataform 會產生已編譯的 GoogleSQL 陳述式,並在編譯結果中建構動作的依附元件圖。

編譯期間,Dataform 只會驗證存放區層級的程式碼和依附元件結構:

  • 評估 JavaScript 程式碼、SQLX config 區塊和內嵌範本運算式。
  • 解析存放區中各檔案的動作參照,例如 ref() 和 resolve()。
  • 檢查每個參照的依附元件目標是否已在編譯圖表中宣告。
  • 偵測重複的動作目標和衝突的動作設定屬性。
  • 偵測工作流程圖中動作之間的循環相依。

編譯作業不會連線至 BigQuery,也不會執行下列檢查:

  • GoogleSQL 語法和語意正確性:編譯作業會在評估 JavaScript 運算式後,將 SQL 查詢主體視為文字,不會剖析或驗證 GoogleSQL 陳述式、函式或資料類型。
  • 資源存在:編譯不會檢查目標或參照的專案、資料集、資料表、檢視表或資料欄是否存在於 BigQuery。
  • IAM 權限:編譯作業不會驗證您的使用者帳戶或自訂服務帳戶,是否具備在 BigQuery 執行工作或存取資源的權限。

由於編譯作業不會查詢 BigQuery,因此即使編譯後的查詢包含無效的 SQL 或參照缺少的資料表,編譯作業仍可在工作區、版本設定、「Compiled graph」(編譯圖表) 分頁、compilationResults.create 方法或 dataform compile CLI 指令中成功執行。

查詢驗證和工作流程執行期間會發生的情況

Dataform 只有在查詢驗證或工作流程執行期間,將編譯後的查詢傳送至 BigQuery 時,才會驗證 SQL 查詢和 BigQuery 資源:

  • 查詢驗證 (模擬測試):在開發工作區的「Compiled queries」(已編譯的查詢) 窗格中,或在 Dataform CLI 中執行 dataform run --dry-run 時,Dataform 會在編譯成功後,將每個已編譯的查詢傳送至 BigQuery 進行模擬測試。模擬測試會檢查 GoogleSQL 語法和語意、確認 BigQuery 中是否存在參照的資料表和資料欄、檢查 IAM 權限,並預估處理的位元組數,而不會執行查詢。如果查詢參照工作流程中尚未在 BigQuery 建立的上游資料表,模擬測試會回報驗證錯誤,直到您執行上游動作為止。
  • 工作流程執行:當您觸發工作流程執行作業、執行排定的工作流程設定、呼叫 workflowInvocations.create,或在 Dataform CLI 中執行 dataform run 時,Dataform 會按照依附元件順序在 BigQuery 中執行已編譯的 SQL 動作。BigQuery 會驗證 SQL 語法和語意、檢查資料集、資料表和資料欄是否存在、強制執行 IAM 權限、建立或更新目標資產,以及執行資料品質斷言。

設定 Dataform 編譯的方式

根據預設,Dataform 會使用工作流程設定檔中的設定建立編譯結果。您可以使用編譯覆寫功能覆寫預設設定,建立自訂編譯結果。接著,您可以手動觸發自訂編譯結果的執行作業,或排定執行作業。

Dataform 提供下列選項,可用於設定編譯結果:

工作區編譯覆寫設定
您可以建立編譯覆寫設定,套用至存放區中的所有工作區。您可以使用工作區編譯覆寫功能,建立獨立的開發環境。
版本設定
您可以建立版本設定,設定用於建立 Dataform 存放區編譯結果的範本。接著,您可以建立工作流程設定,排定執行在所選版本設定中建立的編譯結果。
Dataform API 編譯覆寫
您可以在終端機中傳遞 Dataform API 要求,建立並執行單一編譯結果,並覆寫編譯設定。

建立工作區編譯覆寫設定

您可以使用工作區編譯覆寫設定,為 Dataform 存放區中的所有工作區建立編譯覆寫設定。您可以為每個存放區建立一項工作區編譯覆寫設定。

在存放區中手動觸發工作區執行作業時,如果工作區編譯覆寫設定已啟用,Dataform 會將這些覆寫設定套用至工作區的編譯結果。

您可以設定下列工作區編譯覆寫設定:

  • Dataform 執行工作區內容的Google Cloud 專案
  • 資料表前置字串
  • 結構定義後置字串

您可以使用工作區編譯覆寫功能,透過動態編譯覆寫功能,在 BigQuery 中隔離工作區編譯結果,建立獨立的開發環境。動態資料表前置字串和結構定義後置字串編譯覆寫設定包含 ${workspaceName} 變數。在工作區中觸發執行作業時,Dataform 會將 ${workspaceName} 變數替換為目前工作區的名稱,建立工作區專屬的編譯覆寫。

請注意,您無法排定使用工作區編譯覆寫設定建立的編譯結果執行作業。

建立版本設定

您可以使用版本設定,設定建立存放區編譯結果的範本。

在版本設定中,您可以設定工作流程設定、編譯變數,以及建立整個存放區編譯結果的頻率。

在版本設定中,您可以設定下列編譯覆寫:

  • Google Cloud 專案
  • 資料表前置字串
  • 結構定義後置字串
  • 編譯變數的值

您可以在 Dataform 存放區中建立多個版本設定,每個開發生命週期階段各一個,建立獨立的存放區編譯結果。

接著,您可以建立工作流程設定,安排執行所選版本設定中建立的編譯結果。

您也可以手動觸發所選版本設定中的編譯結果執行作業。

使用 Dataform API 編譯覆寫設定單一編譯結果

在終端機中傳遞 Dataform API 要求,即可為單一編譯結果設定編譯覆寫。

在 compilationResults.create 要求中,您可以為 Dataform 工作區或指定的 Git commitish (可以是分支版本、標記或修訂版本 SHA) 建立單一編譯結果。

在 compilationResults.create 要求的 CodeCompilationConfig 物件中,您可以為編譯要求設定編譯覆寫。

您可以設定下列 Dataform API 編譯覆寫:

  • Google Cloud 專案
  • 資料表前置字串
  • 結構定義後置字串
  • 編譯變數的值

請注意,Dataform API 編譯覆寫設定會套用至單一編譯結果和單一執行作業。無法用於排定 Dataform 執行作業。

您可以在 workflowInvocations.create 要求中執行編譯結果。

設定 Dataform 執行作業的方式

Dataform 提供下列執行作業設定選項:

在工作區中手動執行
您可以在 Dataform 工作區中,手動觸發工作流程的即時執行作業,不受任何排程限制。您可以在工作流程中執行所選動作。
工作流程設定
您可以排定執行在所選版本設定中建立的編譯結果。您可以選取要執行的工作流程動作,並設定執行頻率和時區。

在工作區中觸發即時執行

在 Dataform 工作區中,您可以手動觸發工作流程,立即在工作區中執行,不受任何排程限制。

您可以在工作區中手動執行下列工作流程元素:

如果存放區包含工作區編譯覆寫設定,您可以查看 Dataform 會將哪些編譯覆寫設定套用至工作區編譯結果。

建立工作流程設定

您可以透過工作流程設定,排定所選版本設定的編譯結果執行時程。您可以在 Dataform 存放區中建立多個工作流程設定。

在工作流程設定中,您可以設定下列執行設定:

  • 已套用編譯版本設定。
  • 選取要執行的工作流程動作。
  • 執行作業的時間表和時區。

您可以選取要執行的工作流程動作:

  • 所有動作
  • 所選動作
  • 對所選標記執行的動作

接著,在排定執行工作流程設定時,Dataform 會將您從套用的編譯結果中選取的動作部署至 BigQuery。

您可以使用 Dataform 版本設定和工作流程設定,在 Dataform 中設定編譯及排定執行作業,不必依賴額外服務。

生命週期資源到期

Dataform 會將編譯結果和工作流程叫用儲存一段時間。

工作流程叫用作業到期

工作流程叫用會在 90 天後或手動刪除時過期。

在工作流程設定中,您可以查看該設定建立的最新工作流程叫用清單。工作流程設定建立的工作流程叫用作業到期後,Dataform 會從近期叫用作業清單中移除該作業。

編譯結果到期

編譯結果的到期時間,取決於結果是在開發工作區、版本設定,還是由工作流程叫用建立。

在 Dataform 工作區開發工作流程時,Dataform 會即時將程式碼編譯成編譯結果,方便您檢查編譯後的 SQL 查詢,並在 BigQuery 進行模擬測試來驗證。在工作區中建立的編譯結果會在 24 小時後過期。

在版本設定中,最新的編譯結果會成為正式編譯結果。新的編譯結果會取代目前的即時編譯結果。Dataform 會保留即時編譯結果,直到新的編譯結果取代為止。遭取代的編譯結果最多會在 24 小時後失效。

Dataform 會從版本設定的「Details」(詳細資料) 頁面中,移除過期的編譯結果。

Dataform 會保留工作流程叫用建立的編譯結果,直到工作流程叫用過期或刪除後 24 小時。

建立工作區編譯覆寫設定

本節說明如何建立工作區編譯覆寫設定,在 BigQuery 中隔離 Dataform 工作區建立的資料表和檢視表。您可以使用工作區編譯覆寫功能,建立獨立的 Dataform 開發環境。

在 Dataform 工作區開發工作流程程式碼時,Dataform 會即時編譯工作區中的程式碼,建立工作區的編譯結果。Dataform 會使用工作流程設定檔中定義的設定,建立工作區編譯結果。接著,當您在工作區中觸發執行作業時,Dataform 會在 BigQuery 中執行工作區編譯結果。

如要覆寫存放區中所有工作區的工作流程設定預設值,可以建立工作區編譯覆寫設定。

您可以使用工作區編譯覆寫設定,覆寫存放區中所有工作區的下列設定:

專案

Dataform 執行工作區編譯結果的 Google Cloud 專案,在 workflow_settings.yaml 中設為 defaultProject,或在 dataform.json 中設為 defaultDatabase。

資料表前置字串

自訂前置字串,會新增至存放區中所有工作區的所有資料表名稱。

結構定義後置字串

附加至資料表結構定義的自訂後置字串。在 workflow_settings.yaml 中設為 defaultDataset,在 dataform.json 中設為 defaultSchema,或在資料表的 config 區塊中設為 schema 參數。

如要建立獨立的開發環境,您可以使用不重複的編譯覆寫設定來隔離工作區。您可以使用 ${workspaceName} 變數,動態修改資料表前置字串和結構定義後置字串的編譯覆寫設定。

在工作區中手動觸發執行作業時,${workspaceName} 變數會將工作區名稱插入工作區編譯覆寫。

將 ${workspaceName} 設為資料表前置字串時,Dataform 會將工作區名稱新增至工作區中所有資料表的名稱。執行後,您可以在 BigQuery 中找出資料表的來源工作區。

將 ${workspaceName} 設為結構定義後置字串時,Dataform 會將工作區名稱附加至 defaultSchema,建立工作區專屬的自訂結構定義。執行後,您可以在 BigQuery 的專屬結構定義中,找到從特定工作區執行的所有資料表。

動態工作區編譯覆寫設定範例

以下範例顯示動態工作區編譯覆寫設定,套用至包含工作區的存放區,工作區以處理存放區的開發人員命名:Sasha 和 Kai。

本例中,工作區編譯覆寫設定的目標是為 Sasha 和 Kai 建立獨立的開發環境。

workflow_settings.yaml 中設定了下列預設設定:

  • defaultProject:analytics
  • defaultDataset:dataform

下列工作區編譯覆寫設定會為存放區中的每個工作區建立動態資料表前置字串和結構定義後置字串:

  • Google Cloud 專案 ID:analytics_dev
  • 資料表前置字串:${workspaceName}
  • 結構定義後置字串:${workspaceName}

當 Sasha 在 Sasha 工作區中手動觸發執行作業時,Dataform 會使用下列設定執行內容:

  • Google Cloud 專案:analytics_dev
  • 結構定義:dataform_sasha
  • 資料表名稱:sasha_name,例如 sasha_orders

當 Kai 在 Kai 工作區中手動觸發執行作業時,Dataform 會使用下列設定執行內容:

  • Google Cloud 專案:analytics_dev
  • 結構定義:dataform_kai
  • 資料表名稱:kai_name,例如 kai_orders

建立工作區編譯覆寫設定

如要建立 Dataform 工作區編譯覆寫設定,請按照下列步驟操作:

  1. 在存放區中,前往「Settings」。
  2. 按一下 [編輯]。
  3. 在「Workspace compilation overrides」(工作區編譯覆寫設定) 窗格的「Google Cloud Project ID」(Google Cloud 雲端專案 ID) 欄位中,輸入專案 ID。
  4. 在「Table prefix」(資料表前置字元) 欄位中,輸入所有資料表名稱的前置字元。
    1. 選用:如要為每個工作區建立專屬的動態資料表前置字串,請輸入 ${workspaceName} 做為資料表前置字串。
  5. 在「Schema suffix」(結構定義後置字串) 欄位中,輸入要附加至所建立資料表或檢視表結構定義的後置字串。
    1. 選用:如要建立各工作區專屬的動態結構定義後置字串,請輸入 ${workspaceName} 做為資料表後置字串。
  6. 按一下「儲存」。

Dataform 會將工作區編譯覆寫設定套用到存放區中的所有工作區。

編輯工作區編譯覆寫設定

如要編輯 Dataform 工作區編譯覆寫設定,請按照下列步驟操作:

  1. 在存放區中,前往「Settings」。
  2. 按一下 [編輯]。
  3. 編輯工作區編譯覆寫設定,然後按一下「儲存」。

刪除工作區編譯覆寫設定

如要刪除 Dataform 工作區編譯覆寫設定,請按照下列步驟操作:

  1. 在存放區中,前往「Settings」。
  2. 按一下 [編輯]。
  3. 在「Workspace compilation overrides」(工作區編譯覆寫設定) 窗格中,按一下「Clear all」(全部清除),然後點選「Save」(儲存)。

使用 Dataform API 設定編譯覆寫

本節說明如何使用 Dataform API,建立及執行含有編譯覆寫值的編譯結果。

關於 Dataform API 編譯覆寫

為執行工作流程,Dataform 會將程式碼編譯為 SQL,建立編譯結果。接著,在工作流程叫用期間,Dataform 會在 BigQuery 中執行編譯結果。

根據預設,Dataform 會使用工作流程設定檔中的設定建立編譯結果。如要隔離在開發生命週期不同階段執行的資料,可以使用編譯覆寫功能覆寫預設設定。

在終端機中傳遞 Dataform API 要求,即可建立及執行單一編譯結果,並覆寫編譯設定。您可以建立工作區或所選 Git commitish (例如分支版本、標記或修訂版本 SHA) 的編譯結果。

如要建立含有編譯覆寫值的編譯結果,您必須提出 Dataform API compilationResults.create 要求。在要求中,您必須指定來源 (應為工作區或 Git commitish),Dataform 才能編譯成編譯結果。在 compilationResults.create 要求的 CodeCompilationConfig 物件中,您可以設定編譯覆寫。

接著,您可以在 Dataform API workflowInvocations.create 要求中執行建立的編譯結果。

您可以設定下列 Dataform API 編譯覆寫:

Google Cloud 專案

Dataform 執行編譯結果的專案,在 workflow_settings.yaml 檔案中設為 defaultProject 屬性,或在 dataform.json 檔案中設為 defaultDatabase 屬性。

資料表前置字串

編譯結果中所有資料表名稱新增的自訂前置字串。

結構定義後置字串

自訂後置字串,附加至 workflow_settings.yaml 檔案中 defaultDataset 屬性、dataform.json 檔案中 defaultSchema 屬性,或資料表 config 區塊中 schema 參數定義的資料表結構定義。

編譯變數的值

編譯結果中使用的編譯變數值。您可以使用編譯變數,依條件執行資料表。

Dataform API 編譯覆寫設定只能用於一個編譯結果,您也可以在 Google Cloud 控制台設定工作區編譯覆寫設定。

如要瞭解在 Dataform 中設定編譯覆寫的其他方式,請參閱「Dataform 工作流程生命週期簡介」。

設定編譯結果來源

如要提出 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 commitish 設為編譯結果來源

  • 在 compilationResults.create 要求中,使用所選 Git 分支版本、標記或修訂版本 SHA,以下列格式填入 gitCommitish 屬性:

    {
      "gitCommitish": "GIT_COMMITISH"
    }
    

    將 GIT_COMMITISH 替換為所選 Git 分支版本、Git 標記或編譯結果的 Git 修訂版本 SHA。

下列程式碼範例顯示 compilationResults.create 要求中的 gitCommitish 屬性設為 "staging":

{
  "gitCommitish": "staging"
}

覆寫預設專案

如要在與開發專案不同的 Google Cloud 專案中建立測試或正式環境資料表,您可以在 Dataform API compilationResults.create 要求的 CodeCompilationConfig 物件中傳遞不同的專案 ID。

在 compilationResults.create 要求中傳遞獨立的預設專案 ID,會覆寫工作流程設定檔中設定的預設專案 ID,但不會覆寫個別資料表中設定的專案 ID。

  • 如要覆寫預設專案 ID,請在 CodeCompilationConfig 物件中,將 defaultDatabase 屬性設為所選專案 ID,格式如下:

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

    將 PROJECT_NAME 替換為要為編譯結果設定的專案 ID。

新增資料表前置字串

如要快速識別編譯結果中的資料表,您可以在 Dataform API compilationResults.create 要求中,將資料表前置字串傳遞至 CodeCompilationConfig 物件,為編譯結果中的所有資料表名稱加上前置字串。

  • 如要新增資料表前置字串,請在 CodeCompilationConfig 物件中,以下列格式設定 tablePrefix 屬性:

    {
      "codeCompilationConfig": {
        "tablePrefix": "PREFIX",
      }
    }
    

    將 PREFIX 替換為要附加的前置字串,例如 staging。

    舉例來說,如果資料表名稱為 table_name,Dataform 會建立名稱為 staging_table_name 的資料表。

附加結構定義後置字串

如要區隔開發、測試和正式環境資料,您可以在 Dataform API compilationResults.create 要求中,將結構定義後置字串傳遞至 CodeCompilationConfig 物件,藉此在編譯結果中為結構定義附加後置字串。

  • 如要附加結構定義後置字串,請在 CodeCompilationConfig 物件中,以下列格式設定 schemaSuffix 屬性:

    {
      "codeCompilationConfig": {
        "schemaSuffix": "SUFFIX",
      }
    }
    

    將 SUFFIX 替換為要附加的後置字串,例如 _staging。

    舉例來說,如果 workflow_settings.yaml 檔案中的 defaultDataset 屬性設為 dataform,Dataform 就會在 dataform_staging 結構定義中建立資料表。

使用編譯變數,依條件執行所選檔案

如要只在特定執行設定中執行所選資料表,您可以為執行設定建立編譯變數,然後在 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"
}

建立版本設定

本節說明如何在 Dataform 中建立發布設定,以便設定編譯設定範本,並按照排程執行。您可以使用版本設定來設定執行環境,例如測試和正式環境。

如要在 BigQuery 執行工作流程,Dataform 會將 SQL 工作流程程式碼編譯成編譯結果。在 Dataform 工作區開發工作流程時,系統會自動執行這項程序。

您可以透過版本設定自訂編譯結果。您可以使用這些設定建立執行環境,例如測試環境。

版本設定

在版本設定中,您可以設定工作流程設定的編譯覆寫設定、設定編譯變數,以及設定建立編譯結果的頻率。

Dataform 版本設定包含下列編譯設定:

版本設定
版本 ID、編譯結果的 Git 修訂版本 (例如分支版本、標記或修訂版本 SHA),以及建立編譯結果的頻率。頻率為選用設定。如果設定,頻率下限為 1 小時。
編譯覆寫設定
覆寫Google Cloud 專案、資料表前置字串、結構定義後置字串,以及工作流程設定中定義的編譯變數。

發布版本設定的運作方式

Dataform 會按照指定頻率,或在您觸發編譯時,根據版本設定建立編譯結果。頻率為選用設定,不一定要設定才能建立版本設定。如果設定,則頻率下限為 1 小時。您可以在「Release configuration details」(發布設定詳細資料) 頁面手動觸發編譯,或使用 Dataform API releaseConfigs 方法觸發編譯。

編譯期間,Dataform 會從存放區的指定 Git commitish 提取程式碼。接著,Dataform 會使用套用的編譯覆寫設定 (如有) 編譯程式碼,並建立編譯結果。為版本設定建立的最新編譯結果,就是即時編譯結果。

您可以在工作流程設定中,排定版本設定的編譯結果執行作業。您也可以在任何排程之外執行所選發布設定。執行工作流程設定時,Dataform 會執行所選版本設定的即時編譯結果。

建立版本設定

如要建立 Dataform 發布設定,請按照下列步驟操作:

  1. 在存放區中,前往「發布與排程」。
  2. 在「Release configurations」(版本設定) 部分,按一下「Create」(建立)。
  3. 在「Create release configuration」(建立版本設定) 窗格中,進行版本設定。

    1. 在「Release ID」(發行品 ID) 欄位中,輸入發行品設定的專屬 ID。

      ID 只能使用數字、英文字母、連字號和底線。

    2. 在「Git commitish」(Git 修訂版本) 欄位中,輸入分支版本 (例如 main)、標記或修訂版本 SHA。

      如果 Dataform 存放區未連結至遠端存放區,這個值一律為 main。

    3. 選用:在「Frequency」(頻率) 欄位中,選取建立編譯結果的頻率。

      如果設定,頻率下限為 1 小時。

      如要停用自動發布功能,請將「Frequency」(頻率) 欄位留空。

  4. 選用:在「Compilation overrides」(編譯覆寫) 部分,調整編譯設定。

    1. 在「Google Cloud Project ID」(Google Cloud 專案 ID) 欄位中,輸入要儲存編譯結果的Google Cloud 雲端專案 ID。
    2. 在「Schema suffix」(結構定義後置字串) 欄位中,輸入要附加至工作流程設定中結構定義的後置字串。
    3. 在「Table prefix」(資料表前置字串) 欄位中,輸入所有資料表名稱的前置字串。
  5. 選用:在「Compilation variables」(編譯變數) 區段中,設定編譯變數。

    1. 按一下「新增變數」。
    2. 在「Key」(鍵) 欄位中,輸入編譯變數。
    3. 在「Value」(值) 欄位中,輸入編譯變數的值。
    4. 如要新增其他編譯變數,請按一下「Add variable」(新增變數)。
  6. 點選「建立」。

如果覆寫預設專案,請確認自訂服務帳戶有權存取版本設定中指定的專案。

舉例來說,下列版本設定會每小時從 main 分支版本建立 production 編譯結果,不含任何編譯覆寫:

  • 發行品 ID:production
  • Git commitish:main
  • 頻率:每小時
  • 未建立任何編譯覆寫設定

查看版本設定詳細資料

您可以查看版本設定的下列詳細資料:

  • 版本設定
    • Git 修訂版本
    • 最新編譯結果時間戳記
    • Cron 排程
    • 編譯覆寫設定
    • 編譯變數
  • 即時編譯結果
    • 建立時間戳記
    • Git 修訂版本
    • 修訂版本 SHA
  • 過往編譯結果

如要查看版本設定的詳細資料,請按照下列步驟操作:

  1. 在存放區中,前往「發布與排程」。
  2. 選取發布版本設定。
  3. 在「Release configuration details」(版本設定詳細資料) 頁面中,檢查版本設定的詳細資料。

「Scheduled compilation results」(排定的編譯結果) 表格會顯示版本設定自動建立的過往編譯結果。

「Manual/API compilation results」(手動/API 編譯結果) 表格會顯示手動建立或透過呼叫 Dataform API 建立的編譯結果,這些結果來自存放區中最新的 1,000 筆編譯結果。

手動觸發編譯

如要從所選版本設定手動建立編譯結果,請按照下列步驟操作:

  1. 在存放區中,前往「發布與排程」。
  2. 選取發布版本設定。
  3. 在「Release configuration details」(版本設定詳細資料) 頁面,點選「New compilation」(新增編譯)。

如果您使用使用者介面,新編譯的結果會自動在版本設定中生效。如果您使用 API,則必須依據發布設定建立新的編譯結果,然後更新發布設定,將 releaseCompilationResult 欄位設為這個新值。

手動編譯結果會顯示在「Release configuration details」(版本設定詳細資料) 頁面的「Manual/API compilation results」(手動/API 編譯結果) 表格中。

觸發版本設定執行作業

如要觸發所選版本設定中的即時編譯結果,並執行至 BigQuery,請按照下列步驟操作:

  1. 在存放區中,前往「發布與排程」。
  2. 在「Release configurations」(版本設定) 部分,按一下「Start execution」(開始執行)。
  3. 在「Execute manual workflow」(執行手動工作流程) 窗格的「Release configuration」(版本設定) 清單中,選取版本設定。
  4. 選取要執行的工作流程動作:
    1. 如要執行整個工作流程,請按一下「All actions」(所有動作)。
    2. 如要執行工作流程中的選定動作,請按一下「Selection of actions」(選取動作),然後選取動作。
    3. 如要對所選標記執行動作,請按一下「Selection of tags」(選取標記),然後選取標記。
  5. 選用:如要執行所選動作或標記及其依附元件,請選取「Include dependencies」(納入依附元件) 選項。
  6. 選用:如要執行所選動作或標記及其依附元件,請選取「Include dependents」(包含依附元件) 選項。
  7. 選用:如要從頭重新建構所有資料表,請選取「Run with full refresh」(執行並完整重新整理) 選項。

    如果沒有這個選項,Dataform 會更新累加資料表,而不會從頭重新建構。

  8. 按一下「Start execution」(開始執行)。

編輯版本設定

如要編輯版本設定,請按照下列步驟操作:

  1. 在存放區中,前往「發布與排程」。
  2. 在要編輯的版本設定中,按一下 「More」(更多) 選單,然後點選「Edit」(編輯)。
  3. 在「Edit release configuration」(編輯版本設定) 窗格中,編輯版本設定,然後按一下「Save」(儲存)。

刪除版本設定

如要刪除版本設定,請按照下列步驟操作:

  1. 在存放區中,前往「發布與排程」。
  2. 在要刪除的發布版本設定中,按一下 「More」(更多) 選單,然後點選「Delete」(刪除)。
  3. 在「Delete release configuration」(刪除發布版本設定) 對話方塊中,按一下「Delete」(刪除)。

後續步驟