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

排解 Dataform 問題

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

存取 BigQuery 的要求遭拒

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

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

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

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

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

The access token for remote repository REPOSITORY_NAME was rejected

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

超出 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 pipeline 叫用錯誤

將工作流程執行至 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，然後按一下「安裝套件」。

不支援 `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 修訂版本，請確認目標位置的 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 安全連線。
確認驗證權杖或 SSH 金鑰有效、未過期，且有權存取存放區。
請按照「連結至第三方 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 服務代理程式有權存取密鑰。

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

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

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

如要解決這個問題，請採取下列任一做法：

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

不明引數：標記

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

Unknown argument: tags