在 Dataform 建立及執行工作流程
本快速入門導覽課程的對象,是想要在 BigQuery 中管理資料轉換作業的資料工程師和資料分析師。在本快速入門導覽中,您將瞭解如何使用 Dataform Core 建立及執行 Dataform 工作流程。Dataform Core 是以 SQL 為基礎的架構,可將原始資料轉換為經過管理、測試及記錄的資料資產。使用 Dataform,您可以在中央存放區開發及版本控管資料模型管道,確保可靠性和擴充性。
本快速入門導覽課程會逐步引導您完成下列程序:在 Dataform 中建立工作流程,並在 BigQuery 中執行:
事前準備
- 登入 Google Cloud 帳戶。如果您是 Google Cloud新手,歡迎 建立帳戶,親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額,可用於執行、測試及部署工作負載。
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery and Dataform APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery and Dataform APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.
必要的角色
如要取得執行本快速入門導覽課程所有工作所需的權限,請要求管理員授予您下列 IAM 角色:
-
專案或存放區的 Dataform 管理員 (
roles/dataform.admin) -
BigQuery 資料編輯者 (
roles/bigquery.dataEditor) 專案或特定資料集 -
專案的 BigQuery 工作使用者 (
roles/bigquery.jobUser) 角色 -
服務帳戶使用者 (
roles/iam.serviceAccountUser) 自訂服務帳戶
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
授予必要角色
如要在 BigQuery 中執行工作流程,可以使用自訂服務帳戶或 Google 帳戶。
自訂服務帳戶必須具備下列必要角色:
- BigQuery 資料編輯者
(
roles/bigquery.dataEditor) 專案或特定 BigQuery 資料集,Dataform 需要讀取和寫入權限。這通常包括代管 Dataform 存放區的專案。 - BigQuery 資料檢視者
(
roles/bigquery.dataViewer) 專案或特定 BigQuery 資料集,Dataform 需要這些專案或資料集的唯讀存取權。 - 專案的 BigQuery Job User
(
roles/bigquery.jobUser) ,其中包含 Dataform 存放區。
如要讓 Dataform 使用自訂服務帳戶,預設的 Dataform 服務代理程式必須具備自訂服務帳戶資源的下列角色:
如要授予這些角色,請按照下列步驟操作:
前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
按一下「授予存取權」。
在「新增主體」欄位中,輸入自訂服務帳戶 ID。
在「Select a role」(選取角色) 選單中,逐一選取下列角色,並為每個額外角色使用「Add another role」(新增其他角色):
- BigQuery 資料編輯者
- BigQuery 資料檢視者
- BigQuery 工作使用者
按一下 [儲存]。
前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。
選取自訂服務帳戶。
前往「具備存取權的主體」,然後點選「授予存取權」。
在「新增主體」欄位中,輸入預設的 Dataform 服務代理程式 ID。
預設 Dataform 服務代理 ID 的格式如下:
service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com將
PROJECT_NUMBER替換為專案的數字 ID。Google Cloud 您可以在 Google Cloud 控制台資訊主頁中找到專案 ID。Google Cloud 詳情請參閱「識別專案」。在「Select a role」(選取角色) 清單中,新增下列角色:
- 服務帳戶使用者
- 服務帳戶權杖建立者
按一下 [儲存]。
如要進一步瞭解如何授予角色,請參閱「授予 Dataform 必要存取權」。
建立 Dataform 存放區
Dataform 存放區是一種資源,代表包含 Dataform 專案程式碼的 Git 存放區,用於開發、版本控管及協調工作流程。如要建立存放區,請選取下列任一選項:
控制台
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
按一下 「建立存放區」。
在「建立存放區」頁面中執行下列操作:
在「Repository ID」(存放區 ID) 欄位中輸入
quickstart-repository。在「Region」(區域) 清單中選取「
europe-west4」。在「Service account」(服務帳戶) 清單中,選取存放區的自訂服務帳戶。
在「actAs 權限檢查」部分,針對存放區的使用者動作強制執行權限檢查。
點選「建立」。
點選「前往存放區」。
您已成功建立 Dataform 存放區。接著,您可以建立並初始化開發工作區。
API
如要建立存放區,請使用 projects.locations.repositories.create 方法。
使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories - 查詢參數:
repositoryId=REPOSITORY_ID
curl 指令:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{"serviceAccount": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com"}' \
"https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories?repositoryId=REPOSITORY_ID"
更改下列內容:
LOCATION:要建立存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:您要建立 Dataform 存放區的Google Cloud 專案專屬 ID。REPOSITORY_ID:新 Dataform 存放區的專屬 ID,例如quickstart-repository。SERVICE_ACCOUNT_NAME:為執行 BigQuery 工作而建立的自訂服務帳戶 ID。
建立並初始化開發工作區
Dataform 工作區是獨立的開發環境,類似於 Git 分支,可供您編輯及編譯程式碼。如要建立工作區,請選取下列其中一個選項:
控制台
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
按一下 [
quickstart-repository]。按一下「建立開發工作區」。
在「建立開發工作區」視窗中執行下列操作:
在「Workspace ID」(工作區 ID) 欄位中輸入
quickstart-workspace。點選「建立」。
系統隨即會顯示開發工作區頁面。
按一下「Initialize workspace」(初始化工作區)。
API
如要建立 Dataform 工作區,請使用
projects.locations.repositories.workspaces.create方法。使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces - 查詢參數:
workspaceId=WORKSPACE_ID
curl指令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d "{}" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces?workspaceId=WORKSPACE_ID"- 端點:
如要使用必要的設定初始化工作區,請建立名為
workflow_settings.yaml的本機檔案,並貼上下列設定:defaultProject: PROJECT_ID defaultDataset: dataform dataformCoreVersion: CORE_VERSION在終端機中執行下列指令,將檔案內容編碼為單一連續字串:
base64 -w 0 workflow_settings.yaml複製產生的輸出字串,在 JSON 要求主體的
SETTINGS_DEFINITION欄位中使用。如要在工作區中建立設定檔,請使用
projects.locations.repositories.workspaces.writeFile方法。使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile
curl指令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "path": "workflow_settings.yaml", "contents": "SETTINGS_DEFINITION" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"更改下列內容:
CORE_VERSION:最新穩定 (非 Beta) 版的 Dataform Core,例如3.0.43。您可以在「版本」中找到最新版本。LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的Google Cloud 專案專屬 ID。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。SETTINGS_DEFINITION:YAML 檔案的內容,採用 Base64 編碼字串。WORKSPACE_ID:Dataform 開發工作區的專屬 ID,例如feature-branch-1。
- 端點:
建立檢視表
Dataform 檢視區塊是 SQLX 檔案中定義的資產,可讓您轉換資料,並做為工作流程中其他資料表或檢視區塊的來源。如要建立及定義 view,做為資料表的資料來源,請選取下列其中一個選項:
控制台
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
依序按一下
quickstart-repository和quickstart-workspace。在「Files」(檔案) 窗格中,點按
definitions/旁的 「更多」選單。點選「建立檔案」。
在「建立新檔案」窗格中,執行下列步驟:
在「Add a file path」(新增檔案路徑) 欄位中,輸入
definitions/quickstart-source.sqlx。點選「建立檔案」。
在「檔案」窗格中,展開 definitions 資料夾。
按一下 [
definitions/quickstart-source.sqlx]。在檔案中輸入下列程式碼片段:
config { type: "view" } SELECT "apples" AS fruit, 2 AS count UNION ALL SELECT "oranges" AS fruit, 5 AS count UNION ALL SELECT "pears" AS fruit, 1 AS count UNION ALL SELECT "bananas" AS fruit, 0 AS count按一下「格式」。
API
如要建立檢視區塊,請先準備 API 要求的 SQLX 檔案內容。
建立名為
quickstart-source.sqlx的本機檔案,並貼上下列 SQL 程式碼片段:config { type: "view" } SELECT "apples" AS fruit, 2 AS count UNION ALL SELECT "oranges" AS fruit, 5 AS count UNION ALL SELECT "pears" AS fruit, 1 AS count UNION ALL SELECT "bananas" AS fruit, 0 AS count在終端機中執行下列指令,將檔案內容編碼為單一連續字串:
base64 -w 0 quickstart-source.sqlx複製產生的輸出字串,在 JSON 要求主體的
VIEW_DEFINITION欄位中使用。如要在工作區中建立及定義檢視定義檔,請使用
projects.locations.repositories.workspaces.writeFile方法。使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile
JSON 酬載 (
write_view.json):{ "path": "definitions/quickstart-source.sqlx", "contents": "VIEW_DEFINITION" }curl指令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @write_view.json \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"更改下列內容:
LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的Google Cloud 專案專屬 ID。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。VIEW_DEFINITION:SQLX 檔案的內容,以 Base64 編碼字串表示。WORKSPACE_ID:Dataform 開發工作區的專屬 ID,例如feature-branch-1。
- 端點:
建立資料表
Dataform 資料表是在 SQLX 檔案中定義的資產,可將轉換後的查詢結果儲存在 BigQuery 中,做為工作流程的一部分。如要為工作流程定義資料表,請選取下列其中一個選項:
控制台
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
依序按一下
quickstart-repository和quickstart-workspace。在「檔案」窗格中,點選「
definitions/」旁的 「更多」選單,然後選取「建立檔案」。在「Add a file path」(新增檔案路徑) 欄位中,輸入
definitions/quickstart-table.sqlx。點選「建立檔案」。
在「檔案」窗格中,展開
definitions/目錄。選取
quickstart-table.sqlx,然後輸入下列資料表類型和SELECT陳述式:config { type: "table" } SELECT fruit, SUM(count) as count FROM ${ref("quickstart-source")} GROUP BY 1按一下「格式」。
定義資料表類型後,Dataform 會擲回查詢驗證錯誤,因為 BigQuery 中尚不存在 quickstart-source。執行工作流程時,這項錯誤就會解決。
API
如要建立資料表,請先準備 API 要求的 SQLX 檔案內容。
建立名為
quickstart-table.sqlx的本機檔案,並貼上下列 SQL 程式碼片段:config { type: "table" } SELECT fruit, SUM(count) as count FROM ${ref("quickstart-source")} GROUP BY 1在終端機中執行下列指令,將檔案內容編碼為單一連續字串:
base64 -w 0 quickstart-table.sqlx複製產生的輸出字串,在 JSON 要求主體的
TABLE_DEFINITION欄位中使用。如要在工作區中定義資料表,請使用
projects.locations.repositories.workspaces.writeFile方法。只要發出這項 API 要求,就能取代手動建立 SQLX 檔案,以及定義資料表結構和依附元件的步驟。使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile
JSON 酬載 (
write_table.json):{ "path": "definitions/quickstart-table.sqlx", "contents": "TABLE_DEFINITION" }curl指令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @write_table.json \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID:writeFile"更改下列內容:
LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的Google Cloud 專案專屬 ID。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。TABLE_DEFINITION:SQLX 檔案的內容,以 Base64 編碼字串表示。WORKSPACE_ID:Dataform 開發工作區的專屬 ID,例如feature-branch-1。
- 端點:
在 BigQuery 中執行工作流程
如要執行工作流程,請選取下列其中一個選項:
控制台
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
依序按一下
quickstart-repository和quickstart-workspace。按一下「Start execution」(開始執行)。
按一下「All actions」(所有動作)。
按一下「Start execution」(開始執行)。
在開啟的對話方塊中,按一下「允許」,授予 BigQuery Pipelines 存取 Google 帳戶的權限。
Dataform 會使用預設存放區設定,在名為
dataform的 BigQuery 資料集中建立工作流程的內容。
您已成功建立 Dataform 工作流程,並在 BigQuery 中執行該工作流程。
API
如要在 BigQuery 中執行工作流程,請將 SQLX 檔案編譯為標準 SQL,然後觸發叫用。
如要根據工作區建立編譯結果,請使用
projects.locations.repositories.compilationResults.create方法。使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults
curl指令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "workspace": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workspaces/WORKSPACE_ID" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults"更改下列內容:
LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的Google Cloud 專案專屬 ID。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。WORKSPACE_ID:Dataform 開發工作區的專屬 ID,例如feature-branch-1。
- 端點:
從回應中,記下
/compilationResults/COMPILATION_ID格式的編譯結果 ID。如要觸發工作流程調用,請使用
projects.locations.repositories.workflowInvocations.create方法。提供您建立的彙整結果 ID。使用下列資訊執行 API 要求:
- 端點:
POST https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations
curl指令:curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "compilationResult": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/compilationResults/COMPILATION_ID" }' \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations"更改下列內容:
COMPILATION_ID:編譯結果的專屬 ID。LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的專屬 Google Cloud 專案 ID 。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。
- 端點:
您已成功建立 Dataform 工作流程,並在 BigQuery 中執行該工作流程。
在 Dataform 中查看執行記錄檔
如要查看執行記錄,請選取下列其中一個選項:
控制台
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
依序按一下
quickstart-repository和quickstart-workspace。按一下「Workflow Execution Logs」(工作流程執行記錄)。
如要查看執行作業的詳細資料,請點選最新的執行作業。
API
如要查看執行記錄,請使用
projects.locations.repositories.workflowInvocations.list方法。使用下列資訊執行 API 要求:
- 端點:
GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations - 查詢參數:如要確保最新執行作業顯示在結果頂端,請使用
?orderBy=create_time desc。
curl指令:curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations?orderBy=create_time%20desc"更改下列內容:
LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的專屬 Google Cloud 專案 ID 。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。
- 端點:
如要查看特定執行作業的詳細記錄和狀態,請使用
projects.locations.repositories.workflowInvocations.query方法。使用下列資訊執行 API 要求:
- 端點:
GET https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations/WORKFLOW_INVOCATION_ID:query
curl指令:curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \ "https://dataform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY_ID/workflowInvocations/WORKFLOW_INVOCATION_ID:query"更改下列內容:
LOCATION:存放區的 Google Cloud 區域,例如europe-west4。PROJECT_ID:Dataform 存放區所在的專屬 Google Cloud 專案 ID 。REPOSITORY_ID:Dataform 存放區的專屬 ID,例如quickstart-repository。WORKFLOW_INVOCATION_ID:特定工作流程執行的專屬 ID。您可以從workflowInvocations.list要求的結果,或workflowInvocations.create回應的name欄位中取得這個 ID。
- 端點:
清除所用資源
為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用,請按照下列步驟操作。
刪除在 BigQuery 中建立的資料集
如要避免系統依 BigQuery 資產收取費用,請刪除名為 dataform 的資料集。
前往 Google Cloud 控制台的「BigQuery」頁面。
在「Explorer」面板中展開專案,然後選取
dataform。按一下 「Actions」(動作) 選單,然後選取「Delete」(刪除)。
在「Delete dataset」(刪除資料集) 對話方塊中,在欄位輸入
delete,然後按一下「Delete」(刪除)。
刪除 Dataform 開發工作區
建立 Dataform 開發工作區不會產生任何費用,但如要刪除開發工作區,請按照下列步驟操作:
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
按一下 [
quickstart-repository]。在「Development workspaces」(開發工作區) 分頁,按一下
quickstart-workspace旁的 「More」(更多) 選單,然後選取「Delete」(刪除)。按一下「Delete」(刪除) 確認操作。
刪除 Dataform 存放區
建立 Dataform 存放區不會產生任何費用,但如要刪除存放區,請按照下列步驟操作:
前往 Google Cloud 控制台的 BigQuery「Dataform」頁面。
按一下「
quickstart-repository」的 「More」(更多) 選單,然後選取「Delete」(刪除)。在「Delete repository」(刪除存放區) 視窗中,輸入存放區名稱來確認刪除。
按一下「Delete」(刪除) 確認操作。
後續步驟
- 如要進一步瞭解 Dataform,請參閱「Dataform 總覽」。
- 如要瞭解如何將遠端存放區連結至 Dataform 存放區,請參閱「連結至第三方 Git 存放區」。
- 如要瞭解如何覆寫存放區的預設 Dataform 設定,請參閱「設定 Dataform 工作流程設定」。
- 如要進一步瞭解如何在 BigQuery 中管理資料集,請參閱「管理資料集」一文。
- 如要進一步瞭解如何在 BigQuery 中管理資料表,請參閱「管理資料表」。