Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

排解 Dataform 問題

本文說明如何解決 Dataform 相關問題。

無法存取 BigQuery

如果在授予 Dataform BigQuery 存取權之前觸發管道叫用，會發生下列錯誤：

Access Denied: Project PROJECT_ID: User does not have bigquery.jobs.create permission in project PROJECT_ID.

如要解決這項錯誤，請將 BigQuery 存取權授予 Dataform。

遠端存放區的存取權杖遭拒

如果已連結第三方存放區的驗證權杖沒有該存放區的存取權，就會發生下列錯誤：

The access token for remote repository REPOSITORY_NAME was rejected

如要解決這個錯誤，請檢查 Git 供應商中的必要權限，並據此更新 Secret Manager 驗證權杖。如要進一步瞭解如何在 Dataform 驗證第三方 Git 存放區，請參閱「連線至第三方 Git 存放區」。

Secure Source Manager 連線缺少 Developer Connect Proxy

使用未啟用 Proxy 的 Developer Connect 連線，將 Dataform 存放區連結至 Secure Source Manager (搶先版) 存放區時，會發生下列錯誤：

This repository uses a Secure Source Manager connection that does not have the Developer Connect proxy enabled. Dataform cannot access it. Select a different repository, or link a new repository using a connection with the proxy enabled.

如要解決這項錯誤，請改選其他存放區、透過已啟用 Proxy 的連線連結新的存放區，或是更新現有的 Developer Connect 連線來啟用 Proxy。詳情請參閱「使用 Developer Connect 連結遠端存放區」。

超過 BigQuery 查詢並行限制

如果同時對 BigQuery 執行的查詢數量超過 BigQuery 查詢並行限制，就會發生下列錯誤：

Exceeded rate limits: too many concurrent queries for this project_and_region

如要解決這項錯誤，請透過下列方式，將平行查詢數量減少至 250 個以下：

在 Dataform 中，使用標記分類動作，並一次只執行所選標記。
在 Dataform 中，建立動作之間的依附關係。
在 Dataform 中，將動作的執行作業分配到不同的Google Cloud 專案。

如要瞭解如何在 BigQuery 中解決這項錯誤，請參閱「排解配額和限制錯誤」。

超過 BigQuery 配額

如果 Dataform 傳送至 BigQuery 的 API 要求數量超過 BigQuery 配額，就會發生下列錯誤：

Quota exceeded: Your user_method exceeded quota for concurrent api requests
per user per method.

如要解決這項錯誤，請透過下列方式，將平行查詢數量減少至 250 個以下：

在 Dataform 中，使用標記將動作分類，並一次只執行所選標記。
在 Dataform 中，建立動作之間的依附關係。
在 Dataform 中，將動作執行作業分配到不同的Google Cloud 專案。

如需在 BigQuery 中解決這項錯誤的操作說明，請參閱「排解配額和限制錯誤」。

BigQuery 管道叫用錯誤

執行 BigQuery 工作流程時，會發生下列錯誤：

以「BigQuery error messages」開頭的管道叫用錯誤。

如要解決這些錯誤，請參閱「BigQuery 錯誤訊息」一文。

編譯失敗

由於編譯的查詢大小或數量，編譯期間會發生下列錯誤：

Compilation timed out. Reduce the complexity of your project to ensure it can compile within limits.
Compilation exceeded its allowed heap memory limits. Reduce the complexity of your project to ensure it can compile within limits.
Compilation exceeded its allowed ArrayBuffer or string memory limits. Reduce the complexity of your project to ensure it can compile within limits.

如要解決這些錯誤，請按照下列步驟操作：

將 Dataform 核心更新至最新版本。
檢查工作流程，找出並減少效率不彰的情況。
縮減 SQL 查詢的大小。

減少記憶體中的 JavaScript 作業量，例如：

config { config {type: "table" }}
js {
    const tooBig = new Uint8Array(110_000_000);
}
SELECT ...

分割存放區。

如要進一步瞭解 Dataform 編譯資源限制，請參閱「配額與限制」。

相衝突的 `includeDependentAssertions` 屬性

如果在同一個檔案中，為同一個動作設定了不同的 includeDependentAssertions 參數值，編譯期間會發生下列錯誤：

Conflicting "includeDependentAssertions" properties are not allowed. Dependency
dependencyName has different values set for this property.

如要解決這個錯誤，請編輯檔案並移除重複的 includeDependentAssertions 參數。

如要進一步瞭解如何使用 includeDependentAssertions 參數將斷言設為依附元件，請參閱「將所選動作的斷言設為依附元件」。

系統會封鎖跨專案服務帳戶連結

如果您嘗試使用 Dataform 存放區以外專案的自訂服務帳戶，且作業遭到組織政策限制封鎖，就會發生下列錯誤：

The caller does not have permission to act as service account: SERVICE_ACCOUNT_EMAIL

如要解決這項錯誤，請執行下列操作：

找出自訂服務帳戶所在的 Google Cloud 專案。
在該專案中，停用 iam.disableCrossProjectServiceAccountUsage 組織政策限制。詳情請參閱「啟用跨專案附加服務帳戶的功能」。
確認呼叫端主體具備自訂服務帳戶的服務帳戶使用者角色 (roles/iam.serviceAccountUser)。

詳情請參閱「處理跨專案服務帳戶連結」。

`@dataform/core` 依附元件錯誤

如果 package.json 中的 dataform-core 依附元件過時，編譯期間會發生下列錯誤：

Failed to resolve @dataform/core

@dataform/core version should be X.X.X or newer

package.json 中必須有 @dataform/core 依附元件。在存放區中初始化第一個工作區時，Dataform 會自動在 package.json 中填入目前版本的 @dataform/core。@dataform/core推出後，請務必更新至最新版本。

如要解決這類問題，請將 @dataform/core 更新至最新版本。

使用者憑證權限遭拒

使用 Google 帳戶的使用者憑證執行工作負載時，如果 Dataform 沒有必要權限，就會發生下列錯誤：

Dataform does not have the necessary permissions to run your workload using end user credentials. Error details: Account restricted: https://accounts.google.com/info/servicerestricted?...

如果貴組織使用情境感知存取權規則，根據使用者身分和情境限制 Google Cloud 服務的存取權，就可能發生這項錯誤。

如要解決這項錯誤，您可能需要更新情境感知存取權設定，允許 Dataform 使用 Google 帳戶使用者憑證。如要這麼做，您需要在存取層級設定中，排除 Dataform 的 OAuth 用戶端 ID。如要瞭解如何豁免應用程式，請參閱「為支援的應用程式設定存取層級」。

如要取得 Dataform 的 OAuth 用戶端 ID，請與 Cloud Customer Care 團隊聯絡。

無法解決`dataform.json`

初始化 Dataform 工作區時，如果初始化程序無法安裝所有套件，就會發生下列錯誤：

Uncaught Error: Failed to resolve dataform.json

如要解決這個錯誤，請在工作區中開啟 package.json，然後按一下「安裝套件」。

無法解決`workflow_settings.yaml`

初始化 Dataform 工作區時，如果初始化程序無法安裝所有套件，就會發生下列錯誤：

Uncaught Error: Failed to resolve workflow_settings.yaml

如要解決這個錯誤，請在工作區中開啟 workflow_settings.yaml，然後按一下「Install packages」(安裝套件)。

不支援 `git+` 套裝方案指定目標

在 package.json 中定義套件時，如果目標的前置字串為 git+，就會發生下列錯誤：

'git+' prefixed package targets are not currently supported. However,
in most cases they can be used via a '.tar.gz' suffixed target instead.

Dataform 不支援前置字串為 git+ 的套件目標。

如要解決這項錯誤，請產生套件的 tar.gz 網址，並更新 package.json 中的套件目標。如要進一步瞭解如何在 Dataform 中安裝套件，請參閱「安裝套件」。

套件安裝逾時

如果 package.json 中定義的套件大小超過 NPM 依附元件大小上限，就會發生下列錯誤：

API request error: Package installation timed out

如要解決這項錯誤，請從 package.json 移除多餘的套件。請確認 package.json 檔案不含 @dataform/cli，且定義的 NPM 依附元件總大小不超過 200 MB。

如果版本設定參照 Git commitish，請確認目標的 package.json 檔案有效。

權限遭拒，無法以服務帳戶身分操作

如果執行動作的主體在有效服務帳戶中缺少 iam.serviceAccounts.actAs 權限，就會發生下列錯誤：

Permission denied: Principal CALLER_EMAIL is missing 'iam.serviceAccounts.actAs' permission on service account SERVICE_ACCOUNT_EMAIL.

執行下列動作時，可能會發生這項錯誤：

建立或更新存放區。
建立或更新工作流程設定。
建立工作流程叫用。
更新版本設定。

如要解決這項錯誤，請將服務帳戶使用者角色 (roles/iam.serviceAccountUser) 授予有效服務帳戶中的主體。詳情請參閱「授予必要的 IAM 角色」。

無法連線至私人套件登錄檔

私有套件的 Dataform 驗證過期時，會發生下列錯誤：

Permission denied when fetching one or more npm packages. Please verify that
private registry authentication details are valid for each npm registry

如要解決這個錯誤，請確認每個 NPM 登錄檔的私人登錄檔驗證詳細資料都有效。詳情請參閱「驗證私人套件」。

無法連線至遠端存放區

如果 Dataform 無法連線至遠端 Git 存放區，就會發生下列其中一個錯誤：

Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

Error during remote operation: SSH connection to remote repository 'REMOTE_REPOSITORY_URL' timed out.

Error during remote operation: `Read timed out`.

Error during remote operation: `Connection time out`.

Error during remote operation: The remote repository 'REMOTE_REPOSITORY_URL' closed connection during remote operation.

解決這些連線錯誤的方式，取決於失敗是永久性還是暫時性。

永久連線失敗

如果每次嘗試編譯或在初始存放區設定期間都發生錯誤，表示連線永久失敗。連線設定有誤或憑證已過期。如要解決這項錯誤，請按照下列步驟操作：

確認可透過公用網際網路存取 Git 存放區主機。
如果無法透過公開網際網路存取遠端 Git 存放區，請使用 Developer Connect 從 Dataform 安全連線。
確認驗證權杖或安全殼層金鑰有效、未過期，且可存取存放區。
按照「連線至第三方 Git 存放區」中的所有步驟操作。

暫時性或間歇性連線失敗

如果錯誤是在排定執行的作業期間或多個工作流程同時觸發時偶爾發生，則連線失敗是暫時性的。連至遠端存放區的外部網路連線可能暫時不穩定。

為提高正式環境的可靠性，並避免暫時性連線錯誤，請遵循下列最佳做法：

避免在正式環境中頻繁編譯 commitish：直接在 Git commitish (例如 main 或特定 Git 標記) 上呼叫 CreateCompilationResult，Dataform 就必須在每次執行時，透過網路執行全新的 Git 複製作業並安裝套件。在多個管道中頻繁觸發 commitish 編譯，會增加外部網路依附元件和執行延遲時間。
使用版本設定：如要執行正式環境，請使用版本設定。版本設定會按照控管的時間表編譯存放區，並儲存不可變更的編譯結果。下游工作流程執行作業會立即使用這項快取結果，不會查詢外部 Git 存放區。
錯開排定的執行時間：排定多項編譯或發布觸發條件時，請錯開 cron 排程，分散網路負載。舉例來說，您可以將排程延後 5 到 10 分鐘，而不是同時執行所有工作。
在自動化調度管理工作流程中新增重試機制：從外部排程器 (例如 Managed Service for Apache Airflow) 自動化調度管理 Dataform 編譯作業時，請在運算子上設定自動重試機制，並採用指數輪詢間隔，以便妥善處理暫時性的網路不穩定問題。舉例來說，在 Airflow DAG 中使用 DataformCreateCompilationResultOperator 時，請按照下列方式設定重試：

from datetime import timedelta
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
)

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",
    },
    retries=5,
    retry_delay=timedelta(minutes=2),
    retry_exponential_backoff=True,
)

Dataform 中未顯示存放區

部分 Dataform 存放區可能會出現在 Cloud Asset Inventory 搜尋或 IAM 權限稽核中，但不會顯示在 Google Cloud 控制台的 Dataform 中。

如要瞭解如何使用標籤識別這些存放區的來源，請參閱「識別 BigQuery 資產的存放區」。

無法存取遠端存放區的密鑰

如果 Dataform 服務代理無法存取已連結第三方存放區的 Secret Manager 密鑰，就會發生下列錯誤：

Dataform's service account is unable to reach the configured secret.
Make sure the secret exists and is shared with your Dataform service account:
SERVICE_ACCOUNT_ID.

如要解決這項錯誤，請確認 Dataform 服務代理程式有權存取密鑰。

下拉式選單中未顯示服務帳戶

設定存放區或工作流程叫用時，「Service account」(服務帳戶) 選單可能不會列出現有的自訂服務帳戶。

Dataform 會使用 Identity and Access Management API 列出服務帳戶。這項操作需要專案層級的 iam.serviceAccounts.list 權限。

如要解決這個問題，請按照下列其中一種做法進行：

按一下「手動輸入」，然後輸入服務帳戶 ID。
請專案管理員授予您「查看服務帳戶」角色 (roles/iam.serviceAccountViewer)，或在專案中授予您具備 iam.serviceAccounts.list 權限的其他角色。

不明引數：tags

如果 Dataform CLI 版本無法辨識 tags 引數，就會發生下列錯誤：

Unknown argument: tags