排定執行時間

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

• 使用工作流程設定排定執行時間。
• 使用 Workflows 和 Cloud Scheduler 排定執行時間。
• 使用 Cloud Composer 排定執行時間。
• 使用 Cloud Build 觸發條件自動執行測試。

下表比較這兩種方法：

方法	目標	觸發條件類型
工作流程設定	在 Dataform 中執行的標準正式環境作業 (以時間為準)。	根據時間
Workflows 和 Cloud Scheduler	輕量級無伺服器 Dataform 自動化調度管理工具，可與其他 API 搭配使用。	根據時間或事件
Cloud Composer	具有 BigQuery 外部依附元件的複雜管道。	根據時間或事件
Cloud Build 觸發條件	在 Git 推送後立即自動發布。	以事件為依據

事前準備

如要使用工作流程設定排定執行時間 或使用工作流程和 Cloud Scheduler 排定執行時間，請按照下列步驟操作：

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

   前往 Dataform

2. 選取或建立存放區。

   注意： Dataform 存放區清單只會列出為 Dataform 工作流程開發作業建立的存放區。BigQuery Studio 資產 (例如筆記本或已儲存的查詢) 的存放區是分開管理，不會顯示在這個清單中。

3. 建立發布設定。

如要使用 Cloud Composer 安排執行時間，請按照下列步驟操作：

1. 選取或建立 Dataform 存放區。
2. 將 BigQuery 存取權授予 Dataform。
3. 選取或建立 Dataform 工作區。
4. 至少建立一個資料表。
5. 建立 Cloud Composer 2 環境。

必要的角色

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

• Dataform 管理員 (roles/dataform.admin) 存放區
• Composer Worker (roles/composer.worker) Cloud Composer 環境的服務帳戶
• 使用 Cloud Build 自動執行：
  • 自訂服務帳戶的服務帳戶管理員 (roles/iam.serviceAccountAdmin)
  • 專案的 Cloud Build 編輯者 (roles/cloudbuild.builds.editor)

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

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

重要事項： 如要排定工作流程執行時間，請使用自訂服務帳戶或 Google 帳戶使用者憑證。

如要在建立工作流程設定時使用自訂服務帳戶，請授予自訂服務帳戶存取權。

如要在建立工作流程設定 (預覽版) 時使用 Google 帳戶使用者憑證，請授予 Google 帳戶存取權。

如要為工作流程設定啟用排程執行作業，您必須為工作流程設定中使用的自訂服務帳戶，授予iam.serviceAccounts.actAs權限給預設的 Dataform 服務代理程式。這項權限屬於服務帳戶使用者角色 (roles/iam.serviceAccountUser)。詳情請參閱「使用嚴格 act-as 模式」。

重要事項： 建議您在現有存放區中啟用嚴格的「以…身分執行」模式，確保 Dataform 專案的權限模式更加安全且可預測。

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

使用工作流程設定排定執行作業

本節說明如何在 Dataform 中建立工作流程設定，排定及設定工作流程執行作業。您可以運用工作流程設定，讓系統按照排程執行 Dataform 工作流程。

關於工作流程設定

如要排定在 BigQuery 中執行所有或所選工作流程動作的 Dataform 執行作業，可以建立工作流程設定。在工作流程設定中，選取編譯版本設定、要執行的工作流程動作，以及執行時間表。

接著，在排定的工作流程設定執行期間，Dataform 會將您在發布設定中選取的動作，從最新的編譯結果部署至 BigQuery。您也可以使用 Dataform API workflowConfigs 手動觸發工作流程設定的執行作業。

Dataform 工作流程設定包含下列執行設定：

• 工作流程設定的 ID。
• 版本設定。

• 服務帳戶。

  這是與工作流程設定相關聯的自訂服務帳戶。您可以選取與 Google Cloud 專案相關聯的自訂服務帳戶，也可以手動輸入其他服務帳戶。根據預設，工作流程設定會使用與存放區相同的服務帳戶。

  服務帳戶憑證是建立及執行排定工作流程設定時的預設授權方法。

  注意： 您最多可以將 100 個不重複的服務帳戶附加至存放區中的所有工作流程設定。

• Google 帳戶使用者憑證 (預先發布版)

  Google 帳戶使用者憑證是手動建立及執行非排程工作流程設定時的預設授權方法。詳情請參閱「授權給您的 Google 帳戶」。

• 要執行的工作流程動作：

  • 所有動作。
  • 選取動作。
  • 選取標記。

• 執行時間表和時區。

建立工作流程設定

如要建立 Dataform 工作流程設定，請按照下列步驟操作：

1. 在存放區中，前往「發行內容和排程」。
2. 在「工作流程設定」部分，按一下「建立」。

3. 在「Create workflow configuration」(建立工作流程設定) 窗格的「Configuration ID」(設定 ID) 欄位中，輸入工作流程設定的專屬 ID。

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

4. 在「Release configuration」(版本設定) 選單中，選取編譯版本設定。

5. 在「驗證」部分，使用 Google 帳戶使用者憑證或服務帳戶授權工作流程設定。

   • 如要使用 Google 帳戶使用者憑證 (預覽)，請選取「以我的使用者憑證執行」。
   • 如要使用自訂服務帳戶，請選取「以所選服務帳戶執行」，然後選取與您有權存取的 Google Cloud 專案相關聯的服務帳戶。如未選取服務帳戶，工作流程設定會使用存放區的服務帳戶。
   注意： 您無法使用預設的 Dataform 服務代理程式執行工作流程。您必須使用自訂服務帳戶或 Google 帳戶使用者憑證。

6. 選用：在「排程頻率」欄位中，以 Unix-Cron 格式輸入執行頻率。

   如要確認 Dataform 會在對應的發布設定中執行最新的編譯結果，請在編譯結果建立時間和排定執行時間之間，至少間隔一小時。

7. 選用：在「時區」選單中，選取跑步活動的時區。

   預設時區為世界標準時間。

8. 選取要執行的工作流程動作：

   • 如要執行整個工作流程，請按一下「所有動作」。
   • 如要執行工作流程中選取的動作，請按一下「選取動作」，然後選取動作。
   • 如要對所選標記執行動作，請按一下「選取標記」，然後選取標記。
   • 選用：如要執行所選動作或代碼及其依附元件，請選取「Include dependencies」(包含依附元件) 選項。
   • 選用：如要執行所選動作或代碼及其依附元件，請選取「Include dependents」(納入依附元件) 選項。

   • 選用：如要從頭重建所有表格，請選取「以完整重新整理執行」選項。

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

   • 選用：使用「以高優先順序執行互動式工作 (預設)」選項，設定 BigQuery 查詢工作優先順序。根據預設，BigQuery 會以互動式查詢工作的形式執行查詢，這類工作會盡快開始執行。清除這個選項後，查詢會以批次查詢工作的形式執行，優先順序較低。

9. 按一下「建立」，如果選取「使用我的使用者憑證執行」做為驗證方法，您必須授權 Google 帳戶 (預覽)。

舉例來說，下列工作流程設定會以 CEST 時區每小時執行一次標記為 hourly 的動作：

• 設定 ID：production-hourly
• 版本設定：-
• 頻率：0 * * * *
• 時區：Central European Summer Time (CEST)
• 選取工作流程動作：選取標記、hourly 標記

授權給您的 Google 帳戶

預先發布版

這項產品或功能 適用《服務專屬條款》。 正式發布前的產品和功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

注意： 如要尋求支援或針對這項功能提供意見回饋，請傳送電子郵件至 [e-mail]。

如要使用Google 帳戶使用者憑證驗證資源，您必須手動授予 BigQuery 管道權限，以便取得 Google 帳戶的存取權杖，並代表您存取來源資料。您可以使用 OAuth 對話方塊介面手動核准。

您只需要授予 BigQuery 管道一次權限。

如要撤銷授予的權限，請按照下列步驟操作：

1. 前往 Google 帳戶頁面。
2. 按一下「BigQuery Pipelines」。
3. 按一下「移除存取權」。

警告： 撤銷存取權後，這個 Google 帳戶在所有區域擁有的管道日後都無法執行。

如果新的 Google 帳戶擁有者從未建立工作流程設定，更新憑證以變更工作流程設定擁有者時，也需要手動核准。

編輯工作流程設定

如要編輯工作流程設定，請按照下列步驟操作：

1. 在存放區中，前往「發行內容和排程」。
2. 在要編輯的工作流程設定中，按一下 「更多」選單，然後按一下「編輯」。
3. 在「Edit workflow configuration」(編輯工作流程設定) 窗格中，編輯工作流程設定，然後按一下「Save」(儲存)。

刪除工作流程設定

如要刪除工作流程設定，請按照下列步驟操作：

1. 在存放區中，前往「發行內容和排程」。
2. 在要刪除的工作流程設定中，按一下 「More」(更多) 選單，然後按一下「Delete」(刪除)。
3. 在「刪除發布版本設定」對話方塊中，按一下「刪除」。

使用 Workflows 和 Cloud Scheduler 排定執行作業

本節說明如何使用 Workflows 和 Cloud Scheduler，排定 Dataform 工作流程的執行時間。

關於排定的工作流程執行作業

您可以建立 Cloud Scheduler 工作來觸發 Workflows 工作流程，藉此設定 Dataform 工作流程的執行頻率。Workflows 會在您定義的自動化調度管理工作流程中執行服務。

工作流程會以兩步驟程序執行 Dataform 工作流程。首先，Dataform 會從 Git 供應商提取 Dataform 存放區程式碼，並編譯成編譯結果。接著，系統會使用編譯結果建立 Dataform 工作流程，並按照您設定的頻率執行。

建立排定時間的自動化調度管理工作流程

如要排定 Dataform 工作流程的執行時間，請使用 Workflows 建立協調工作流程，並新增 Cloud Scheduler 工作做為觸發條件。

1. Workflows 會使用服務帳戶授予工作流程存取Google Cloud 資源的權限。建立服務帳戶，並授予下列權限：

   • Dataform 編輯者角色 (roles/dataform.editor)。
   • Dataform 中使用的自訂服務帳戶的服務帳戶使用者角色 (roles/iam.serviceAccountUser)。
   • 管理自動化調度工作流程所需的最低權限。詳情請參閱「授予工作流程權限，以便存取 Google Cloud 資源」。

2. 建立自動化調度管理工作流程，並使用下列 YAML 原始碼做為工作流程定義：

   main:
       steps:
       - init:
           assign:
           - repository: projects/PROJECT_ID/locations/REPOSITORY_LOCATION/repositories/REPOSITORY_ID
       - createCompilationResult:
           call: http.post
           args:
               url: ${"https://dataform.googleapis.com/v1beta1/" + repository + "/compilationResults"}
               auth:
                   type: OAuth2
               body:
                   gitCommitish: GIT_COMMITISH
           result: compilationResult
       - createWorkflowInvocation:
           call: http.post
           args:
               url: ${"https://dataform.googleapis.com/v1beta1/" + repository + "/workflowInvocations"}
               auth:
                   type: OAuth2
               body:
                   compilationResult: ${compilationResult.body.name}
           result: workflowInvocation
       - complete:
           return: ${workflowInvocation.body.name}
   

   更改下列內容：

   • PROJECT_ID：專案 ID。 Google Cloud
   • REPOSITORY_LOCATION：Dataform 存放區的位置。
   • REPOSITORY_ID：Dataform 存放區的名稱。
   • GIT_COMMITISH：要執行 Dataform 程式碼的 Git 分支。如果是新建立的存放區，請替換為 main。

3. 使用 Cloud Scheduler 排定自動化調度工作流程。

自訂 Dataform 工作流程建立編譯結果要求

您可以更新現有的協調工作流程，並以 YAML 格式定義 Dataform 工作流程建立編譯結果要求設定。如要進一步瞭解相關設定，請參閱 projects.locations.repositories.compilationResults REST 資源參考資料。

舉例來說，如要在編譯期間將 _dev schemaSuffix 設定新增至所有動作，請將 createCompilationResult 步驟主體替換為下列程式碼片段：

    - createCompilationResult:
        call: http.post
        args:
            url: ${"https://dataform.googleapis.com/v1beta1/" + repository + "/compilationResults"}
            auth:
                type: OAuth2
            body:
                gitCommitish: GIT_COMMITISH
                codeCompilationConfig:
                    schemaSuffix: dev

您也可以在 Workflows 執行要求中，以執行階段引數的形式傳遞其他設定，並使用變數存取這些引數。詳情請參閱「在執行要求中傳遞執行階段引數」。

自訂 Dataform 工作流程叫用要求

您可以更新現有的協調工作流程，並以 YAML 格式定義 Dataform 工作流程叫用要求設定。如要進一步瞭解叫用要求設定，請參閱 projects.locations.repositories.workflowInvocations REST 資源參考資料。

舉例來說，如要只執行含有 hourly 標記的動作，並納入所有遞移依附元件，請將 createWorkflowInvocation 主體替換為下列程式碼片段：

    - createWorkflowInvocation:
        call: http.post
        args:
            url: ${"https://dataform.googleapis.com/v1beta1/" + repository + "/workflowInvocations"}
            auth:
                type: OAuth2
            body:
                compilationResult: ${compilationResult.body.name}
                invocationConfig:
                    includedTags:
                    - hourly
                    transitiveDependenciesIncluded: true
                

您也可以在 Workflows 執行要求中，以執行階段引數的形式傳遞其他設定，並使用變數存取這些引數。詳情請參閱「在執行要求中傳遞執行階段引數」。

使用 Cloud Composer 排定執行作業

您可以使用 Cloud Composer 2 排定 Dataform 執行作業。Dataform 不支援 Cloud Composer 1。

如要使用 Cloud Composer 2 管理 Dataform 執行的時間表，您可以在 Airflow 有向非循環圖 (DAG) 中使用 Dataform 運算子。您可以建立 Airflow DAG，排定 Dataform 工作流程叫用時間。

Dataform 提供各種 Airflow 運算子。包括用於取得編譯結果、取得工作流程叫用項目，以及取消工作流程叫用項目的運算子。如要查看可用的 Dataform Airflow 運算子完整清單，請參閱「Google Dataform 運算子」。

安裝 google-cloud-dataform PyPi 套件

如果您使用 Cloud Composer 2 2.0.25 以上版本，環境中會預先安裝這個套件。你不需要安裝。

重要事項： 使用 Airflow 2.3.3 的 Cloud Composer 映像檔會使用 apache-airflow-providers-google 套件的公開版本 8.1.0。版本 8.1.0 不含 Dataform 連接器。自 8.3.0 版起，Cloud Composer 將支援 Dataform 連接器，該版本會與 Airflow 2.3.4 的 Cloud Composer 映像檔一併發布。詳情請參閱 Cloud Composer 版本資訊。

如果您使用較舊的 Cloud Composer 2 版本，請安裝 google-cloud-dataform PyPi 套件。

在 PyPI 套件部分，指定版本 ==0.2.0。

建立 Airflow DAG，排定 Dataform 工作流程的呼叫作業

如要使用 Cloud Composer 2 管理 Dataform 工作流程的排定執行作業，請使用 Dataform Airflow 運算子編寫 DAG，然後將其上傳至環境的 bucket。

下列程式碼範例顯示 Airflow DAG，可建立 Dataform 編譯結果，並啟動 Dataform 工作流程調用：

from datetime import datetime

from airflow import models
from airflow.models.baseoperator import chain
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
    DataformCreateWorkflowInvocationOperator,
)

DAG_ID = "dataform"
PROJECT_ID = "PROJECT_ID"
REPOSITORY_ID = "REPOSITORY_ID"
REGION = "REGION"
GIT_COMMITISH = "GIT_COMMITISH"

with models.DAG(
    DAG_ID,
    schedule_interval='@once',  # Override to match your needs
    start_date=datetime(2022, 1, 1),
    catchup=False,  # Override to match your needs
    tags=['dataform'],
) as dag:

    create_compilation_result = DataformCreateCompilationResultOperator(
        task_id="create_compilation_result",
        project_id=PROJECT_ID,
        region=REGION,
        repository_id=REPOSITORY_ID,
        compilation_result={
            "git_commitish": GIT_COMMITISH,
        },
    )
    create_workflow_invocation = DataformCreateWorkflowInvocationOperator(
        task_id='create_workflow_invocation',
        project_id=PROJECT_ID,
        region=REGION,
        repository_id=REPOSITORY_ID,
         workflow_invocation={
            "compilation_result": "{{ task_instance.xcom_pull('create_compilation_result')['name'] }}"
        },
    )


create_compilation_result >> create_workflow_invocation

更改下列內容：

• PROJECT_ID：您的 Dataform Google Cloud 專案 ID。
• REPOSITORY_ID：Dataform 存放區的名稱。
• REGION：Dataform 存放區所在的區域。
• COMPILATION_RESULT：您要用於這項工作流程呼叫的編譯結果名稱。
• GIT_COMMITISH：遠端 Git 存放區中的 Git commitish，用於指定要使用的程式碼版本，例如分支或 Git SHA。

以下程式碼範例顯示的 Airflow DAG 會執行下列作業：

1. 建立 Dataform 編譯結果。
2. 以非同步方式啟動 Dataform 工作流程叫用。
3. 使用 DataformWorkflowInvocationStateSensor 輪詢工作流程的狀態，直到工作流程進入預期狀態為止。

from datetime import datetime

from google.cloud.dataform_v1beta1 import WorkflowInvocation

from airflow import models
from airflow.models.baseoperator import chain
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
    DataformCreateWorkflowInvocationOperator,
)
from airflow.providers.google.cloud.sensors.dataform import DataformWorkflowInvocationStateSensor

DAG_ID = "dataform"
PROJECT_ID = "PROJECT_ID"
REPOSITORY_ID = "REPOSITORY_ID"
REGION = "REGION"
GIT_COMMITISH = "GIT_COMMITISH"

with models.DAG(
    DAG_ID,
    schedule_interval='@once',  # Override to match your needs
    start_date=datetime(2022, 1, 1),
    catchup=False,  # Override to match your needs
    tags=['dataform'],
) as dag:

    create_compilation_result = DataformCreateCompilationResultOperator(
        task_id="create_compilation_result",
        project_id=PROJECT_ID,
        region=REGION,
        repository_id=REPOSITORY_ID,
        compilation_result={
            "git_commitish": GIT_COMMITISH,
        },
    )

create_workflow_invocation = DataformCreateWorkflowInvocationOperator(
    task_id='create_workflow_invocation',
    project_id=PROJECT_ID,
    region=REGION,
    repository_id=REPOSITORY_ID,
    asynchronous=True,
    workflow_invocation={
        "compilation_result": COMPILATION_RESULT
    }
)

is_workflow_invocation_done = DataformWorkflowInvocationStateSensor(
    task_id="is_workflow_invocation_done",
    project_id=PROJECT_ID,
    region=REGION,
    repository_id=REPOSITORY_ID,
    workflow_invocation_id=("{{ task_instance.xcom_pull('create_workflow_invocation')['name'].split('/')[-1] }}"),
    expected_statuses={WorkflowInvocation.State.SUCCEEDED},
)


create_compilation_result >> create_workflow_invocation

更改下列內容：

• PROJECT_ID：您的 Dataform Google Cloud projectID。
• REPOSITORY_ID：Dataform 存放區的名稱。
• REGION：Dataform 存放區所在的區域。
• COMPILATION_RESULT：您要用於這項工作流程呼叫的編譯結果名稱。
• GIT_COMMITISH：遠端 Git 存放區中的 Git commitish，用於指定要使用的程式碼版本，例如分支或 Git SHA。
• COMPILATION_RESULT：您要用於這項工作流程呼叫的編譯結果名稱。

新增編譯設定參數

您可以將其他編譯設定參數新增至 create_compilation_result Airflow DAG 物件。如要進一步瞭解可用參數，請參閱 CodeCompilationConfig Dataform API 參考資料。

• 如要將編譯設定參數新增至 create_compilation_result Airflow DAG 物件，請以以下格式將所選參數新增至 code_compilation_config 欄位：

      create_compilation_result = DataformCreateCompilationResultOperator(
          task_id="create_compilation_result",
          project_id=PROJECT_ID,
          region=REGION,
          repository_id=REPOSITORY_ID,
          compilation_result={
              "git_commitish": GIT_COMMITISH,
              "code_compilation_config": { "PARAMETER": "PARAMETER_VALUE"}
          },
      )
  

  更改下列內容：

  • PROJECT_ID：您的 Dataform Google Cloud 專案 ID。
  • REPOSITORY_ID：Dataform 存放區的名稱。
  • REGION：Dataform 存放區所在的區域。
  • GIT_COMMITISH：遠端 Git 存放區中的 Git commitish，用於指定要使用的程式碼版本，例如分支或 Git SHA。
  • PARAMETER：所選CodeCompilationConfig參數。您可以新增多個參數。
  • PARAMETER_VALUE：所選參數的值。

以下程式碼範例顯示新增至 create_compilation_result Airflow DAG 物件的 defaultDatabase 參數：

    create_compilation_result = DataformCreateCompilationResultOperator(
        task_id="create_compilation_result",
        project_id=PROJECT_ID,
        region=REGION,
        repository_id=REPOSITORY_ID,
        compilation_result={
            "git_commitish": REMOTE_BRANCH,
            "code_compilation_config": { "default_database": "my-custom-gcp-project"}
        },
    )

新增工作流程叫用設定參數

您可以將其他工作流程叫用設定參數新增至 create_workflow_invocation Airflow DAG 物件。如要進一步瞭解可用參數，請參閱 InvocationConfig Dataform API 參考資料。

• 如要將工作流程叫用設定參數新增至 create_workflow_invocation Airflow DAG 物件，請以以下格式將所選參數新增至 invocation_config 欄位：

      create_workflow_invocation = DataformCreateWorkflowInvocationOperator(
          task_id='create_workflow_invocation',
          project_id=PROJECT_ID,
          region=REGION,
          repository_id=REPOSITORY_ID,
          workflow_invocation={
              "compilation_result": "{{ task_instance.xcom_pull('create_compilation_result')['name'] }}",
              "invocation_config": { "PARAMETER": PARAMETER_VALUE }
          },
      )
  
  

  更改下列內容：

  • PROJECT_ID：您的 Dataform Google Cloud 專案 ID。
  • REPOSITORY_ID：Dataform 存放區的名稱。
  • REGION：Dataform 存放區所在的區域。
  • PARAMETER：所選InvocationConfig參數。您可以新增多個參數。
  • PARAMETER_VALUE：所選參數的值。

以下程式碼範例顯示新增至 create_workflow_invocation Airflow DAG 物件的 includedTags[] 和 transitiveDependenciesIncluded 參數：

    create_workflow_invocation = DataformCreateWorkflowInvocationOperator(
        task_id='create_workflow_invocation',
        project_id=PROJECT_ID,
        region=REGION,
        repository_id=REPOSITORY_ID,
        workflow_invocation={
            "compilation_result": "{{ task_instance.xcom_pull('create_compilation_result')['name'] }}",
            "invocation_config": { "included_tags": ["daily"], "transitive_dependencies_included": true }
        },
    )

透過 Cloud Build 觸發條件自動執行執行作業

如要使用發布設定中的時間排程以外的排程，可以使用 Cloud Build 觸發條件建立事件導向管道。每當有新的修訂版本推送至 Git 分支版本時，這個方法會自動編譯程式碼，並立即觸發 Dataform 工作流程呼叫，以更新資料。

準備資源

1. 在 Google Cloud 專案中，啟用 Dataform 和 Cloud Build API：

   啟用 Dataform API

   啟用 Cloud Build API

2. 請確認您已具備以下條件：

   • 用於編譯的自訂服務帳戶。請記下服務帳戶的電子郵件地址，例如 dataform-compiler@PROJECT_NUMBER.iam.gserviceaccount.com。

   • 連結至 Git 供應商的 Dataform 存放區。

   • Dataform 存放區中的版本設定。記下發布設定 ID。

   • Dataform 存放區中的工作流程設定，會使用發布設定。記下工作流程設定 ID。

授予必要的 IAM 權限

在 Dataform 存放區中，將Dataform 管理員角色 (roles/dataform.admin) 授予自訂服務帳戶。這個角色提供存放區的完整存取權，包括建立編譯結果、更新發布版本設定，以及啟動新工作流程調用的權限。如要瞭解如何授予個別存放區 IAM 角色，請參閱「控管個別存放區的存取權」。

將工作流程設定自訂服務帳戶的服務帳戶使用者角色 (roles/iam.serviceAccountUser) 授予 Cloud Build 觸發程序的服務帳戶。如要進一步瞭解這項規定，請參閱「使用嚴格的『扮演』模式」。

如要讓 Cloud Build 使用自訂服務帳戶，您必須授予 Cloud Build 服務代理程式權限，允許該代理程式以該帳戶的身分執行作業。如要將模擬權限授予 Cloud Build 服務代理，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

   前往「Service Accounts」(服務帳戶)

2. 選取自訂服務帳戶。

3. 前往「具備存取權的主體」分頁。

4. 按一下 「授予存取權」。

5. 在「New principals」(新增主體) 欄位中，輸入 Cloud Build 服務代理的電子郵件地址，格式應如下所示：

   [e-mail]
   

   將 PROJECT_NUMBER 替換為專案的數字 ID。Google Cloud 您可以在 Google Cloud 控制台資訊主頁中找到專案 ID。Google Cloud 詳情請參閱「尋找專案名稱、編號和 ID」。

6. 在「Select a role」(選取角色) 選單中，選取「Service Account User」(服務帳戶使用者)。

7. 按一下 [儲存]。

建立 cloudbuild.yaml 設定檔

在 Git 存放區的根目錄中，建立 cloudbuild.yaml 檔案。使用這個檔案定義下列多步驟指令碼，建立編譯結果、更新發布設定，將這個編譯結果設為正式版，並啟動新的工作流程叫用。

steps:
  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk:latest'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        set -e -o pipefail # Exit script on any error

        # 1. Get the access token
        TOKEN=$(gcloud auth print-access-token)

        # 2. Define API endpoints and resource names
        RELEASE_CONFIG_RESOURCE="projects/${_PROJECT_ID}/locations/${_DATAFORM_LOCATION}/repositories/${_DATAFORM_REPO_ID}/releaseConfigs/${_RELEASE_CONFIG_ID}"
        COMPILATION_RESULTS_API="https://dataform.googleapis.com/v1/projects/${_PROJECT_ID}/locations/${_DATAFORM_LOCATION}/repositories/${_DATAFORM_REPO_ID}/compilationResults"

        # 3. Create the new compilation result
        echo "Creating new compilation result from $$RELEASE_CONFIG_RESOURCE..."
        CREATE_PAYLOAD="{\"releaseConfig\": \"$$RELEASE_CONFIG_RESOURCE\"}"
        curl --fail-with-body -X POST \
          -H "Authorization: Bearer $$TOKEN" \
          -H "Content-Type: application/json" \
          -d "$$CREATE_PAYLOAD" \
          "$$COMPILATION_RESULTS_API" | tee /workspace/compilation_response.json

  - name: 'alpine'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        set -e # Exit script on any error

        # 4. Parse compilation result name
        apk add --no-cache jq
        COMPILATION_NAME=$(jq -r '.name' < /workspace/compilation_response.json)

        echo "Successfully created compilation result: $$COMPILATION_NAME"
        echo $$COMPILATION_NAME > /workspace/compilation_result_name.txt

  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk:latest'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        set -e # Exit script on any error
        # 5. Update the releaseConfig to set the new compilation result as 'live'
        COMPILATION_NAME=$(cat /workspace/compilation_result_name.txt)
        echo "Updating release config to set $$COMPILATION_NAME as live..."
        PATCH_PAYLOAD="{\"releaseCompilationResult\": \"$$COMPILATION_NAME\", \"gitCommitish\": \"$BRANCH_NAME\"}"

        RELEASE_CONFIG_RESOURCE="projects/${_PROJECT_ID}/locations/${_DATAFORM_LOCATION}/repositories/${_DATAFORM_REPO_ID}/releaseConfigs/${_RELEASE_CONFIG_ID}"
        RELEASE_CONFIG_PATCH_API="https://dataform.googleapis.com/v1/$${RELEASE_CONFIG_RESOURCE}"
        curl --fail-with-body -X PATCH \
          -H "Authorization: Bearer $(gcloud auth print-access-token)" \
          -H "Content-Type: application/json" \
          -d "$$PATCH_PAYLOAD" \
          "$$RELEASE_CONFIG_PATCH_API?updateMask=releaseCompilationResult"

        echo "Successfully updated release config."

  - name: 'gcr.io/google.com/cloudsdktool/cloud-sdk:latest'
    entrypoint: 'bash'
    args:
      - '-c'
      - |
        set -e # Exit script on any error
        # 6. Launch a workflow config after recompiling the release config
        WORKFLOW_CONFIG_RESOURCE="projects/${_PROJECT_ID}/locations/${_DATAFORM_LOCATION}/repositories/${_DATAFORM_REPO_ID}/workflowConfigs/${_WORKFLOW_CONFIG_ID}"
        CREATE_WORKFLOW_PAYLOAD="{\"workflowConfig\": \"$$WORKFLOW_CONFIG_RESOURCE\"}"

        WORKFLOW_INVOCATIONS_API="https://dataform.googleapis.com/v1/projects/${_PROJECT_ID}/locations/${_DATAFORM_LOCATION}/repositories/${_DATAFORM_REPO_ID}/workflowInvocations"
        curl --fail-with-body -X POST \
          -H "Authorization: Bearer $(gcloud auth print-access-token)" \
          -H "Content-Type: application/json" \
          -d "$$CREATE_WORKFLOW_PAYLOAD" \
          "$$WORKFLOW_INVOCATIONS_API"

        echo "Successfully created a new workflow invocation."

# Define substitution variables that can be set in the trigger
substitutions:
  _DATAFORM_LOCATION: 'us-central1'  # Default, change if needed
  _DATAFORM_REPO_ID: ''              # Required: Set this in the trigger
  _RELEASE_CONFIG_ID: ''             # Required: Set this in the trigger
  _WORKFLOW_CONFIG_ID: ''            # Required: Set this in the trigger
  _PROJECT_ID: ${PROJECT_ID}         # Automatically uses the build's Project ID

options:
  logging: CLOUD_LOGGING_ONLY

建立 Cloud Build 觸發條件

如要建立觸發條件，在程式碼推送到存放區時執行建構設定，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，開啟 Cloud Build 的「Triggers」(觸發條件) 頁面。

   前往「Triggers」(觸發條件)

2. 如果尚未連結 Git 存放區，請按一下「連結存放區」，然後按照步驟操作。

3. 按一下「建立觸發條件」。

4. 輸入觸發條件的名稱。

5. 選取觸發條件的區域。

6. 選取觸發條件的事件。

7. 在「來源」部分，將存放區設為已連結的 Git 存放區。

8. 將分支版本設為存放區的主要分支版本。

9. 在「設定」部分，選取 Cloud Build 設定檔，可以是 YAML 或 JSON 檔案。

10. 將檔案位置設為 /cloudbuild.yaml 或檔案路徑。

11. 在「替代變數」部分，新增下列變數和值：

    • _DATAFORM_REPO_ID：您的 Dataform 存放區 ID
    • _RELEASE_CONFIG_ID：您的 Dataform 發布版本設定 ID
    • _WORKFLOW_CONFIG_ID：您的 Dataform 工作流程設定 ID
    • 選用：_DATAFORM_LOCATION：您的 Dataform 存放區區域，例如 us-central1

12. 在「服務帳戶」專區，選取自訂服務帳戶。

13. 點選「建立」。

詳情請參閱「建立建構觸發程序」。

測試觸發條件

1. 將 cloudbuild.yaml 檔案修訂並推送至觸發程序監控的分支版本。

2. 如要查看 Cloud Build 建構作業，請在 Google Cloud 控制台中開啟「Build History」(建構記錄) 頁面。

   前往「Build History」(建構記錄)

3. 如果建構成功，請前往「Dataform」頁面。

   前往 Dataform

4. 選取存放區。

5. 按一下「發行與排程」，然後選取發行設定。

6. 在「手動 / API 編譯結果」清單中，尋找新項目。最近一次成功編譯的結果應標示為發行設定的「即時編譯結果」。

7. 按一下「工作流程執行記錄」。

8. 畫面上應會顯示使用所選工作流程設定啟動的新工作流程呼叫。

後續步驟

• 如要瞭解如何設定 Dataform 編譯版本設定，請參閱建立版本設定。
• 如要進一步瞭解 Dataform 中的程式碼生命週期，請參閱「Dataform 中的程式碼生命週期簡介」。
• 如要進一步瞭解 Dataform API，請參閱「Dataform API」。
• 如要進一步瞭解 Cloud Composer 環境，請參閱「Cloud Composer 總覽」。
• 如要進一步瞭解 Workflows 定價，請參閱「Workflows 定價」。