排查 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 代码库。

远程仓库的身份验证状态为“未知”

在 Google Cloud 控制台中查看已连接的第三方代码库时,身份验证状态列可能会显示未知,并显示以下错误:

An error occurred during computation of the authentication status.

如果代码库使用区域级 Secret Manager 密钥版本(例如使用 Dataform API 或 Terraform 配置时),则可能会出现此错误。区域 Secret 版本使用 projects/PROJECT_ID/locations/LOCATION/secrets/SECRET_ID/versions/VERSION 格式。

Dataform 仅支持格式为 projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION 的全局 Secret Manager Secret 版本。

如需解决此问题,请执行以下操作:

  1. 在 Secret Manager 中,创建一个全局 Secret,其中包含您的 Git 访问令牌或 SSH 私钥。

    如果您必须限制密文数据的存储位置,请使用用户管理的复制政策配置全局密文,并选择允许的区域。

  2. 向默认 Dataform 服务代理授予对 Secret 的访问权限,并为其分配 roles/secretmanager.secretAccessor 角色。

    默认 Dataform 服务代理采用以下格式:

    service-PROJECT_NUMBER@gcp-sa-dataform.
    
  3. 更新代码库的 Git 连接,以使用全局 Secret 版本。如需了解详情,请参阅修改远程仓库连接。

Secure Source Manager 连接缺少 Developer Connect 代理

当您使用未启用代理的 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.

如需解决此错误,请选择其他代码库,通过已启用代理的连接来关联新代码库,或更新现有 Developer Connect 连接以启用代理。如需了解详情,请参阅使用 Developer Connect 连接远程仓库。

已超出 BigQuery 查询并发数限制

当对 BigQuery 运行的并发查询数量超过 BigQuery 查询并发限制时,会发生以下错误:

Exceeded rate limits: too many concurrent queries for this project_and_region

如需解决此错误,请通过以下方式将并行查询数量减少到 250 个以下:

如需了解如何在 BigQuery 中解决此错误,请参阅排查配额和限制错误。

已超出 BigQuery 配额

当 Dataform 发送到 BigQuery 的 API 请求数量超过 BigQuery 配额时,会发生以下错误:

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

如需解决此错误,请通过以下方式将并行查询数量减少到 250 个以下:

如需了解如何在 BigQuery 中解决此错误,请参阅排查配额和限制错误。

BigQuery 流水线调用错误

在执行到 BigQuery 的工作流期间,会发生以下错误:

如需解决这些错误,请参阅 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.
  • Compilation cancelled because it exceeded size limits.

如需解决这些错误,请按以下步骤操作:

  1. 将 Dataform 核心更新到最新版本。
  2. 检查您的工作流,找出并减少低效环节。
  3. 缩减 SQL 查询的大小。
  4. 减少内存中的 JavaScript 操作量,例如:

    config { config {type: "table" }}
    js {
        const tooBig = new Uint8Array(110_000_000);
    }
    SELECT ...
    
  5. 拆分代码库。

如需详细了解 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

要解决此错误,请执行以下操作:

  1. 确定自定义服务账号所在的 Google Cloud 项目。
  2. 在该项目中,停用 iam.disableCrossProjectServiceAccountUsage 组织政策限制条件。如需了解详情,请参阅允许跨项目关联服务账号。
  3. 确保调用方主账号在自定义服务账号上具有 Service Account User 角色 (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 会自动使用当前版本的 @dataform/core 填充 package.json。您需要将 @dataform/core 更新到最新版本。

如需解决这些错误,请将 @dataform/core 更新到最新版本。

Google 账号用户凭据权限遭拒

如果您使用 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 依赖项的总大小不超过 200Mb。

如果您的发布配置引用了 Git commitish(例如分支、标记或提交 SHA),请确保其目标位置的 package.json 文件有效。

充当服务账号的权限请求被拒

如果执行操作的主体缺少有效服务账号的 iam.serviceAccounts.actAs 权限,则会发生以下错误:

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

此错误可能会在执行以下操作期间发生:

  • 创建或更新代码库。
  • 创建或更新工作流配置。
  • 创建工作流调用。
  • 更新版本配置。

如需解决此错误,请向有效服务账号的主账号授予 Service Account User 角色 (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.

解决这些连接错误的方式取决于故障是永久性的还是暂时性的。

永久性连接失败

如果每次尝试编译或在初始代码库设置期间都持续发生错误,则连接失败是永久性的。连接配置不正确或凭证已过期。如需解决此错误,请按以下步骤操作:

  1. 确认您的 Git 代码库主机可通过公共互联网访问。
  2. 如果无法通过公共互联网访问您的远程 Git 代码库,请使用 Developer Connect 从 Dataform 安全地连接。
  3. 验证您的身份验证令牌或 SSH 密钥是否有效、未过期,并且有权访问代码库。
  4. 按照连接到第三方 Git 代码库中的所有步骤操作。

暂时性或间歇性连接失败

如果错误在预定执行期间或多个工作流同时触发时偶尔发生,则连接失败是暂时性的。您与远程仓库的外部网络连接可能暂时不可靠。

为优化生产可靠性并防止暂时性连接错误,请遵循以下最佳实践:

  1. 避免在生产环境中频繁编译 commitish:直接在 Git commitish(例如分支、标记或提交 SHA)上调用 CreateCompilationResult 会要求 Dataform 在每次执行时执行全新的 Git 克隆并通过网络安装软件包。在多个流水线中频繁触发 commitish 编译会增加外部网络依赖性和执行延迟。
  2. 使用发布配置:对于生产执行,请使用发布配置。发布配置会按受控时间表编译代码库,并保存不可变的编译结果。下游工作流执行会立即使用此缓存结果,而无需查询外部 Git 代码库。
  3. 错开预定执行时间:安排多个编译或发布触发器时,请错开其 cron 计划,以分散网络负载。例如,将时间表错开 5-10 分钟,而不是同时运行所有作业。
  4. 在编排工作流中添加重试机制:从外部调度器(例如 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 资产的代码库。

无法访问远程仓库的 Secret

当 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 服务代理是否有权访问该 Secret。

下拉菜单中未显示服务账号

配置代码库或工作流调用时,服务账号菜单可能不会列出现有的自定义服务账号。

Dataform 使用 Identity and Access Management API 列出服务账号。这需要项目级层的 iam.serviceAccounts.list 权限。

如需解决此问题,请执行以下某项操作:

  • 点击手动输入,然后输入服务账号 ID。
  • 请让您的项目管理员为您授予 View Service Accounts 角色 (roles/iam.serviceAccountViewer) 或包含项目的 iam.serviceAccounts.list 权限的其他角色。

未知参数:tags

如果您的 Dataform CLI 版本无法识别 tags 参数,则会发生以下错误:

Unknown argument: tags

要解决此错误,请执行以下操作:

  • 将 CLI 的版本更新为 3.0.0 或更高版本。在生产环境中部署新软件包版本之前,请务必先在非生产环境中进行测试。
  • 最佳实践是始终使用 Dataform 核心软件包的最新可用版本。
  • 在 package.json 中明确指定软件包版本,例如 3.0.0。请勿使用 package.json 的其他 dependencies 选项,例如 >version。

未显示“限制并发操作数”选项

在以下情况下,限制并发操作数选项不可用:

  • 执行模式设置为单元测试。单元测试不支持并发操作限制。如需配置并发操作数限制,请将执行模式设置为操作。
  • 您正在安排笔记本工作流。

操作长时间处于“已加入队列”状态

如果工作流执行配置了并发操作限制,那么当正在运行的操作占满所有并发槽时,操作会进入已加入队列状态。

如需解决此问题,请考虑以下选项:

  • 等待正在运行的操作完成。当并发槽可用时,Dataform 会启动已排队的操作。
  • 如果操作在队列中停留的时间过长或工作流运行时间过长,请在工作流配置时间表中增加后续执行的最大并发操作数值。