設定彙整內容

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

事前準備

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

    前往 Dataform

  2. 選取或建立存放區。

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

  4. 選用：如要覆寫發布設定中的預設 Google Cloud 專案，請在您打算使用的專案中授予自訂服務帳戶存取權。

必要的角色

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

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

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

如要提升排程安全性，請參閱「實作進階排程權限」。

如要更新 Dataform 存放區版本設定的發布版本，您必須為使用此版本設定的工作流程設定中的每個自訂服務帳戶，授予 Dataform 服務代理程式 iam.serviceAccounts.actAs 權限。這項權限包含在服務帳戶使用者角色 (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 存放區的編譯結果。接著，您可以建立工作流程設定，排定所選發布版本設定中建立的編譯結果執行時程。
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 的單一編譯結果。

在 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 會即時將程式碼編譯為編譯結果，以提供查詢驗證。以這種方式建立的編譯結果會在 24 小時後過期。

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

Dataform 會從版本設定「詳細資料」頁面的過往編譯結果清單中，移除過期的編譯結果。

Dataform 會保留工作流程叫用建立的編譯結果，保留時間為工作流程叫用的整個生命週期，最長可達工作流程叫用過期或刪除後的 24 小時。

建立工作區編譯覆寫設定

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

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

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

您可以透過工作區編譯覆寫設定，覆寫存放區中所有工作區的下列設定：

專案

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

資料表前置字串

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

結構定義後置字串

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

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

編輯工作區編譯覆寫設定

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

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

刪除工作區編譯覆寫設定

如要刪除 Dataform 工作區編譯覆寫，請按照下列步驟操作：

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

使用 Dataform API 設定編譯覆寫

本節說明如何使用 Dataform API，透過編譯覆寫建立及執行編譯結果。

關於 Dataform API 編譯覆寫

如要執行工作流程，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 執行編譯結果的專案，在 workflow_settings.yaml 檔案中設為 defaultProject 屬性，或在 dataform.json 檔案中設為 defaultDatabase 屬性。

資料表前置字串

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

結構定義後置字串

附加至資料表結構定義的自訂後置字串，這些資料表定義於 workflow_settings.yaml 檔案的 defaultDataset 屬性、dataform.json 檔案的