OpenMetadata BigQuery 连接器完全指南权限配置、连接参数与元数据/用量/血缘提取实战【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata本指南以 OpenMetadata 仓库中的 BigQuery 连接器文档 为骨架结合 连接器源码 与 JSON Schema 定义系统讲解如何创建 BigQuery 数据服务从 GCP 侧最小权限的授予、Data Catalog API 的启用到 UI 表单中每一个连接字段的取值来源与语义再到元数据、Profiler、数据质量、Usage 与 Lineage 工作流的运行前提帮助你一次性完成可用、合规且可排障的 BigQuery 接入。一、接入前的 GCP 侧准备在 OpenMetadata 中创建 BigQuery 服务之前需要先在 Google Cloud 完成两类准备启用 Data Catalog API以及为执行抽取的账号用户或服务账号授予一组最小权限。1.1 启用 Data Catalog API文档明确要求启用 Data Catalog API具体步骤如下打开 Google Cloud Console 中的 Data Catalog API 页面选择你想要启用该 API 的GCP Project ID点击Enable API即可在选定的项目上启用 Data Catalog API。Data Catalog API 主要服务于两个场景一是策略标签Policy Tags的读取二是部分表/列元数据的辅助获取。如果跳过这一步后续在连接测试阶段读取 taxonomies 或策略标签时会直接收到权限拒绝类错误详见下文连接测试与错误分类一节源码中专门定义了PolicyTagAccessError来区分这类失败。1.2 GCP 最小权限集合为了成功执行元数据抽取Metadata Extraction与用量Usage工作流用户或服务账号需要具备以下权限权限用途bigquery.datasets.get读取数据集Dataset信息bigquery.tables.get读取表信息bigquery.tables.getData读取表数据Profiler / 抽样等场景需要bigquery.tables.list列举项目下的表resourcemanager.projects.get获取项目元数据bigquery.jobs.create创建查询作业执行 INFORMATION_SCHEMA 查询的前提bigquery.jobs.listAll列举项目内全部作业用量分析依赖可选权限一获取策略标签Policy Tagsdatacatalog.taxonomies.getdatacatalog.taxonomies.list可选权限二Usage 与 Lineage 工作流bigquery.readsessions.createbigquery.readsessions.getData在 GCP 中推荐的做法是创建一个自定义角色Custom Role把上表权限绑定到该角色再将该角色授予执行抽取的服务账号。文档中也建议参考 OpenMetadata 官方文档中关于如何在 GCP 创建自定义角色并绑定权限的说明。从源码看这些权限在 connection.py 中的BIGQUERY_ERRORS错误分类表 中得到了印证当缺失bigquery.jobs.create时会提示授予 BigQuery Job User 角色出现access denied时则提示授予 BigQuery Data Viewer / Metadata Viewer 角色或授予访问INFORMATION_SCHEMA.JOBS_BY_PROJECT的权限。1.3 Profiler 与数据质量Data Quality的额外要求执行 Profiler 工作流或数据质量测试时用户需要对执行 Profiler/测试的表或 Schema 具备SELECT权限被允许查看数据库中所有对象的table_storage信息即INFORMATION_SCHEMA.TABLE_STORAGE视图的可见性。table_storage视图被用于获取表的存储统计信息这在 queries.py 中查询表清单与存储信息的语句INFORMATION_SCHEMA.TABLES t left join INFORMATION_SCHEMA.TABLE_STORAGE s中可以找到直接证据。若权限不足Profiler 步骤会在抽取存储指标时失败。二、连接详情Connection DetailsUI 表单字段逐项解析本部分是 UI 中创建 BigQuery 连接时表单字段的完整参考。所有字段在 bigQueryConnection.json 中有对应的 JSON Schema 定义含类型与默认值可直接对照查阅。2.1 基础连接字段SchemeschemeSQLAlchemy 驱动 scheme 选项。Schema 中枚举值固定为bigquery默认值即bigquery。它是后续构造 SQLAlchemy 连接 URL 的前缀见 connection.py 的get_connection_url最终生成的 URL 形如bigquery://project_id。Host PorthostPortBigQuery API 的 URL默认为bigquery.googleapis.com。如果你使用的是 BigQuery 的自定义实现如本地模拟器或代理可以修改该值。注意该字段只影响 API 端点不影响认证方式。2.2 GCP 凭据配置gcpConfig这是连接的核心部分。OpenMetadata 支持三种凭据注入方式由gcpConfig的类型决定对应源码中的三个 Pydantic 模型见 connection.py 的导入GCP Credentials Path指定服务账号密钥文件的路径GcpCredentialsPathGCP Credentials Values将服务账号密钥文件中的字段值逐个粘贴到表单GcpCredentialsValuesGCP ADCApplication Default Credentials将 GCP 凭据留空让 OpenMetadata 使用环境中的 ADC 认证GcpADC。建议若在本地开发或运行在 GCE/GKE 等拥有元数据服务器的环境中ADC 方式最简单——直接留空 gcpConfig 即可OpenMetadata 会通过google.auth默认凭据链路解析身份。下面逐项说明Credentials Values方式下各字段的取值来源全部来自服务账号密钥 JSON 文件字段取值来源JSON 键说明Credentials Typetypetype服务账号此值为service_accountProject IDprojectIdproject_id可从下拉框单选或多选项目Private Key IDprivateKeyIdprivate_key_id服务账号私钥的唯一标识Private KeyprivateKeyprivate_key认证与授权访问 GCP 的私钥Client EmailclientEmailclient_email服务账号的邮箱地址Client IDclientIdclient_id服务账号的唯一标识Auth URIauthUriauth_uri授权服务器的 URIToken URItokenUritoken_uri获取 OAuth 2.0 访问令牌的端点Auth Provider X509Cert URLauthProviderX509CertUrlauth_provider_x509_cert_url验证授权服务器真实性的证书 URLClient X509Cert URLclientX509CertUrlclient_x509_cert_url验证服务账号真实性的证书 URL2.3 Private Key 的格式陷阱必读privateKey字段是最容易出错的配置项。密钥文件中的私钥是多行 PEM 格式直接粘贴会因换行符导致解析失败。文档给出了明确的转换规则原始格式多行-----BEGIN ENCRYPTED PRIVATE KEY----- MII.. MBQ... CgU.. 8Lt.. ... h4 -----END ENCRYPTED PRIVATE KEY-----需要将换行替换为\n后的格式单行字符串-----BEGIN ENCRYPTED PRIVATE KEY-----\nMII..\nMBQ...\nCgU..\n8Lt..\n...\nh4\n-----END ENCRYPTED PRIVATE KEY-----\n源码侧对此有双重校验在 connection.py 的BIGQUERY_ERRORS中捕获InvalidPrivateKeyException并提示私钥无法被解析为 PEM 密钥请粘贴完整密钥含 BEGIN/END 行与真实换行该异常由 utils/credentials.py 的set_google_credentials在凭据解析阶段抛出。换言之私钥格式错误会在连接测试的第一步即被拦截并得到明确的修复指引。2.4 策略标签相关字段Include Policy TagsincludePolicyTags是否采集 BigQuery 策略标签Policy Tags。Schema 中该字段默认值为true。需注意两点联动关系必须同时开启采集代理ingestion agent中的Include Tags选项若关闭本选项代理将只按Include Tags设置采集标签Labels不再采集策略标签。从源码看metadata.py 的get_columns在构建列对象时会把field.policy_tags直接写入列属性而连接测试中的 GetTags 检查项_list_policy_tags会在includePolicyTagsfalse或未设置taxonomyProjectID/taxonomyLocation时跳过该项测试避免无谓失败。Taxonomy Project IDtaxonomyProjectID策略标签通过 taxonomy分类体系组织。若 BigQuery 表的列上挂了策略标签OpenMetadata 会抓取这些标签并挂到对应列上。此处填写创建了 taxonomy 的项目 ID。注意 Schema 中它是字符串数组type: array支持填写多个项目 ID连接测试会遍历所有这些项目去读取 taxonomy。Taxonomy LocationtaxonomyLocationtaxonomy 所在的位置/区域Schema 默认值为us。连接测试中会以projects/{project_id}/locations/{location}为父路径调用 Data Catalog 的list_taxonomies。2.5 用量Usage与成本相关字段Usage LocationusageLocation用于查询INFORMATION_SCHEMA.JOBS_BY_PROJECT获取用量数据的位置。可传多区域multi-region如us或eu也可传具体区域如us-east1。文档特别提示Australia 与 Asia 多区域暂不支持。Schema 默认值为us。源码中的使用方式有两处connection.py 的_add_location把usageLocation以 URL 参数location...的形式追加到连接 URL 上若已有该参数则跳过usage.py 中的用量查询语句BIGQUERY_STATEMENT直接以FROM \region-{region}.INFORMATION_SCHEMA.JOBS_BY_PROJECT 形式引用该位置。Cost Per TiBcostPerTBBigQuery 用量分析期间每处理 1 TiBtebibyte数据所折算的成本美元。该值用于在分析INFORMATION_SCHEMA.JOBS_BY_PROJECT的用量指标时估算查询成本。两点重要说明它不影响实际计费仅用于内部报告与预估成本的可视化文档提醒默认值可能按 BigQuery 标准按需计费如 $5.00/TiB估算但应根据组织协商的折扣价或 flat-rate 计费模式调整。在 bigQueryConnection.json 中该字段的类型为number默认值是 6.25仓库当前版本实际默认值而非文档示例中的 $5.00请以仓库为准。用量 SQL 中对应的计算为(total_bytes_billed / POWER(2, 40)) * {cost_per_tib}见 queries.py 第 35 行即按 TiB 换算后乘以单价。2.6 高级连接选项Connection OptionsconnectionOptions额外的连接选项用于构造发送给服务端的 URL追加为 URL 查询参数。Connection ArgumentsconnectionArguments额外的连接参数如安全或协议配置在建立连接时传给服务端。在 connection.py 的get_connection_args中可以看到这些参数会合并进 SQLAlchemy 引擎的connect_args。2.7 服务账号冒充Impersonation相关字段以下字段用于**服务账号冒充Service Account Impersonation**场景——即用源服务账号换取目标服务账号的短期凭据后执行操作这在跨项目或需要以特定身份运行查询时非常有用字段说明Target Service Account EmailimpersonateServiceAccount被冒充的目标服务账号邮箱Lifetimelifetime委托凭据的有效秒数AudienceaudienceGoogle Security Token ServiceSTS的 audience包含 workload identity pool 的资源名及其中 provider 标识符Subject Token TypesubjectTokenType基于 OAuth 2.0 令牌交换规范的 STS subject token 类型Token URLtokenURLSTS 令牌交换端点Credential SourcecredentialSource定义从本地环境获取外部凭据的机制以便通过 STS 端点将其交换为 GCP 访问令牌源码实现位于 helper.py 的get_impersonate_client_kwargs当配置了非空的目标账号时会向 BigQuery 客户端注入impersonate_service_account与lifetime同时 connection.py 的get_connection_args会构造一个以冒充身份运行的bigquery.Client注入引擎使连接测试与所有 INFORMATION_SCHEMA 查询都走目标身份。策略标签读取同样遵循冒充配置见 helper.py 的get_policy_tag_client避免元数据以目标身份读取、策略标签却用源身份读取的身份错位。相关行为有专门单元测试覆盖见 test_bigquery_impersonation.py。2.8 Billing Project IDbillingProjectId计费项目 ID 是用于在 Google Cloud 中标识并授权计费的唯一字符串。在 BigQuery 中查询作业需要挂在一个可计费项目下执行。从源码看它有两个作用connection.py 的BigQueryConnection._get_client将其作为billing_project_id传入 SQLAlchemy 引擎helper.py 的get_bigquery_client_for_project在构造项目级客户端时优先使用它作为 project_id。当未配置billingProjectId时连接 URL 中的 project id 会从凭据配置中解析单项目取projectId.root多项目取第一个并在必要时设置GOOGLE_CLOUD_PROJECT环境变量见 connection.py 第 182-192 行。三、多项目支持Project ID 单选与多选projectId字段支持从下拉框选择一个或多个项目。Schema 层面对应 gcpValues 中的SingleProjectId与MultipleProjectId两个模型。多项目连接的底层实现值得注意由于连接 URL 只能携带一个 project idhelper.py 的clone_connection_for_project会为每个项目深拷贝一份连接配置并把projectId收敛为单项目从而让每个项目都能被独立巡检与测试。该函数同时覆盖GcpCredentialsValues、GcpADC、GcpCredentialsPath三种凭据形态避免 ADC/密钥路径场景下多项目连接每次迭代都重新扫描第一个配置项目的隐性 bug。提示多项目模式下get_connection_url只解析第一个项目用于构造引擎 URL真正的项目切换由上层BigquerySource逐项目克隆连接驱动见 connection.py 的BigQueryChecks注释。若你的数据分散在多个项目请确认每个项目都已授予 1.2 节的最小权限。四、筛选模式Filter Pattern连接配置还提供三组正则筛选器用于控制采集范围Default Database Filter PatterndatabaseFilterPattern仅包含/排除匹配正则的数据库在 BigQuery 中即项目Default Schema Filter PatternschemaFilterPattern仅包含/排除匹配正则的 Schema即 DatasetDefault Table Filter PatterntableFilterPattern仅包含/排除匹配正则的表Default Stored Procedure Filter PatternstoredProcedureFilterPattern仅包含/排除匹配正则的存储过程。这些字段在 bigQueryConnection.json 中均引用filterPattern.json的通用定义excludes/includes两个正则数组。用法示例includes: [^my_project\\..*]只采集指定项目excludes: [temp_.*]跳过临时表。五、Sample Storage AWS S3 配置当需要把样本数据Sample Data存储到 AWS S3时例如开启 Profiler 抽样并落盘连接配置中会出现一组 S3 相关字段它们定义在sampleDataStorageConfig见 bigQueryConnection.json 第 144-147 行字段说明AWS Access Key IDawsAccessKeyIdAWS 访问密钥 ID如AKIAIOSFODNN7EXAMPLE需与 Secret Access Key 成对使用AWS Secret Access KeyawsSecretAccessKey秘密访问密钥如wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYAWS RegionawsRegion服务所在区域是连接配置中唯一必填的 AWS 参数AWS Session TokenawsSessionToken使用临时凭据时需额外提供会话令牌Endpoint URLendPointURL可指定 AWS 服务的替代端点 URL默认按区域使用标准端点Profile NameprofileName使用default以外的 AWS CLI 命名配置文件Assume Role ARNassumeRoleArn跨账号访问时的角色 ARN使用 AssumeRole 时必填Assume Role Session NameassumeRoleSessionName假定角色会话标识符默认OpenMetadataSessionAssume Role Source IdentityassumeRoleSourceIdentity调用 AssumeRole 的主体源身份可在 CloudTrail 日志中溯源Bucket NamebucketNameS3 存储桶名称用于组织与存储数据对象Prefixprefix数据路径前缀用于在桶内组织/分类数据说明这组字段属于sampleDataStorageConfig样本数据存储配置只有在需要把样本数据写入 S3 时才需要完整填写若未配置存储Profiler 的抽样数据按默认行为处理。六、连接测试与错误分类源码级排障指引BigQuery 连接器在测试连接阶段会依次执行一组检查项定义在 connection.py 的BigQueryChecksCheckAccessping 连通性跳过 TCP 探测因为 BigQuery 无 host:port 可预检仅捕获真实的 socket/DNS 网络错误GetSchemas列举 SchemaDatasetGetTables / GetViews枚举数据集及其中的 TABLE / EXTERNAL / VIEW / MATERIALIZED_VIEW 对象对列表过程中被删除的数据集做了NotFound容忍GetTags仅当includePolicyTagstrue且配置了 taxonomyProjectID/taxonomyLocation 时执行遍历 taxonomy 与 policy tagsGetQueries用BIGQUERY_TEST_STATEMENT探测region-{usageLocation}.INFORMATION_SCHEMA.JOBS_BY_PROJECT查询历史的可读性。这些检查项由 BIGQUERY_ERRORS 错误分类表 提供精准诊断。常见的失败与修复建议速查报错特征诊断修复建议PolicyTagAccessError无法读取策略标签授予 Data Catalog Viewer 角色datacatalog.taxonomies.list/.get若配置了冒充则授予被冒充的服务账号核对taxonomyProjectID/taxonomyLocationInvalidPrivateKeyException私钥格式错误粘贴完整 PEM 密钥含 BEGIN/END 行与真实换行invalid_grant服务账号凭据被拒核对私钥与 client email检查密钥是否被撤销/禁用/过期DefaultCredentialsError找不到 GCP 凭据提供服务账号密钥或在运行环境配置 ADCRefreshError无法换取访问令牌检查密钥、client email 及账号状态含bigquery.jobs.create缺少运行作业权限在计费项目上授予 BigQuery Job User 角色access denied/Forbidden已认证但未授权授予 BigQuery Data Viewer / Metadata Viewer 等角色NotFound项目或数据集不存在核对 project id 与 dataset 是否存在、服务账号是否可见每个步骤的超时预算为 3 分钟step_timeout_seconds THREE_MIN见 connection.py 第 402 行以便大项目不会因单步过慢被误判失败。对应测试见 test_bigquery_test_connection.py。七、工作流配置实战YAML 示例与能力矩阵7.1 元数据抽取工作流仓库中提供了可直接参考的 bigquery.yaml 示例其核心结构如下source: type: bigquery serviceName: local_bigquery serviceConnection: config: type: BigQuery taxonomyProjectID: [ project-id-where-policy-tags-exist ] # includePolicyTags: false credentials: gcpConfig: type: service_account projectId: project_id privateKeyId: private_key_id privateKey: private_key clientEmail: gcpuserproject_id.iam.gserviceaccount.com clientId: client_id authUri: https://accounts.google.com/o/oauth2/auth tokenUri: https://oauth2.googleapis.com/token authProviderX509CertUrl: https://www.googleapis.com/oauth2/v1/certs clientX509CertUrl: https://www.googleapis.com/oauth2/v1/certs sourceConfig: config: type: DatabaseMetadata sink: type: metadata-rest config: {} workflowConfig: openMetadataServerConfig: hostPort: http://localhost:8585/api authProvider: openmetadata securityConfig: jwtToken: your-jwt-token字段与 UI 表单一一对应taxonomyProjectID对应策略标签项目、credentials.gcpConfig对应 GCP 凭据 Values 表单privateKey需按 2.3 节的\n转义规则填入。在 单元测试 test_bigquery.py 的 mock 配置 中可以看到同一结构的完整形态含billingProjectId、includeTags等字段。7.2 连接器能力矩阵从 service_spec.py 可以看到 BigQuery 连接器注册的全部能力组件能力实现类说明元数据抽取BigquerySource表/视图/物化视图、Schema 描述、主外键约束、存储过程、生命周期、DDL、策略标签与标签血缘BigqueryLineageSource基于查询历史的血缘 存储过程血缘StoredProcedureLineageMixin用量BigqueryUsageSource基于INFORMATION_SCHEMA.JOBS_BY_PROJECT的查询级用量分析ProfilerBigQueryProfilerInterface表/列画像与系统指标抽样BigQuerySampler数据采样连接BigQueryConnection连接建立与测试同时在 bigQueryConnection.json 中声明了连接器支持的通用能力开关元数据抽取、增量元数据抽取Incremental、用量抽取、血缘抽取、DBT 抽取、Profiler、System Profile、Query Comment、Data Diff 等。与元数据抽取同目录下还提供 bigquery_lineage.yaml、bigquery_usage.yaml、bigquery_profiler.yaml 等独立工作流示例。7.3 增量元数据抽取Incremental Metadata ExtractionBigQuery 连接器支持增量元数据抽取底层由 incremental_table_processor.py 的BigQueryIncrementalTableProcessor实现配合supportsIncrementalMetadataExtraction开关见 bigQueryConnection.json 第 115-118 行。开启后工作流只处理自上次运行以来发生变更的表可显著缩短大项目的元数据刷新耗时。其行为有专门的单元测试 test_bigquery_incremental_table_processor.py 覆盖。7.4 主外键约束的获取BigQuery 的原生 INFORMATION_SCHEMA 并不直接暴露主外键OpenMetadata 通过 helper.py 的get_pk_constraint/get_foreign_keys覆写 SQLAlchemy 的 inspector 方法用BIGQUERY_CONSTRAINTS查询见 queries.py 第 70-94 行联查KEY_COLUMN_USAGE、CONSTRAINT_COLUMN_USAGE、TABLE_CONSTRAINTS三张视图获取约束并以{project}.{schema}为键做进程内缓存CONSTRAINT_CACHE避免对同一数据集反复查询。八、常见问题速查FAQQ1连接测试在 GetTags 步骤失败先确认是否真的需要策略标签若不需要关闭includePolicyTags同时建议关闭采集代理的 Include Tags即可跳过该项。若需要则授予 Data Catalog Viewer 角色并确认taxonomyProjectID数组可多填与taxonomyLocation指向 taxonomy 真实所在的项目与区域。Q2Usage 工作流查不到数据确认usageLocation已正确设置多区域us/eu或具体区域注意 Australia 与 Asia 多区域不支持且服务账号拥有bigquery.jobs.listAll、bigquery.jobs.create与读取INFORMATION_SCHEMA.JOBS_BY_PROJECT的权限。用量 SQL 会过滤掉 OpenMetadata 自身与 dbt 发起的查询见 queries.py 第 42-43 行。Q3多项目连接只采集到第一个项目确认每个项目都已授予最小权限且各项目 id 在projectId下拉框中正确勾选。多项目场景依赖clone_connection_for_project逐项目克隆连接若某个项目权限缺失会体现在该项目对应的测试结果中。Q4私钥粘贴后报Malformed private key按 2.3 节将 PEM 块中的换行替换为\n确保包含-----BEGIN ... PRIVATE KEY-----与-----END ... PRIVATE KEY-----完整行。九、相关资源索引连接器 UI 文档BigQuery.mdJSON Schema 定义字段/默认值/必填项bigQueryConnection.json连接建立与测试实现connection.py辅助工具冒充、约束、策略标签helper.py元数据抽取实现metadata.py用量抽取实现usage.py血缘抽取实现lineage.py查询语句集合queries.py能力注册service_spec.py工作流示例bigquery.yaml另见同目录下 bigquery_lineage.yaml、bigquery_usage.yaml、bigquery_profiler.yaml、bigquery_classifier.yaml单元测试test_bigquery.py、test_bigquery_test_connection.py、test_bigquery_impersonation.py、test_bigquery_incremental_table_processor.py【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenMetadata BigQuery 连接器完全指南：权限配置、连接参数与元数据/用量/血缘提取实战
OpenMetadata BigQuery 连接器完全指南权限配置、连接参数与元数据/用量/血缘提取实战【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata本指南以 OpenMetadata 仓库中的 BigQuery 连接器文档 为骨架结合 连接器源码 与 JSON Schema 定义系统讲解如何创建 BigQuery 数据服务从 GCP 侧最小权限的授予、Data Catalog API 的启用到 UI 表单中每一个连接字段的取值来源与语义再到元数据、Profiler、数据质量、Usage 与 Lineage 工作流的运行前提帮助你一次性完成可用、合规且可排障的 BigQuery 接入。一、接入前的 GCP 侧准备在 OpenMetadata 中创建 BigQuery 服务之前需要先在 Google Cloud 完成两类准备启用 Data Catalog API以及为执行抽取的账号用户或服务账号授予一组最小权限。1.1 启用 Data Catalog API文档明确要求启用 Data Catalog API具体步骤如下打开 Google Cloud Console 中的 Data Catalog API 页面选择你想要启用该 API 的GCP Project ID点击Enable API即可在选定的项目上启用 Data Catalog API。Data Catalog API 主要服务于两个场景一是策略标签Policy Tags的读取二是部分表/列元数据的辅助获取。如果跳过这一步后续在连接测试阶段读取 taxonomies 或策略标签时会直接收到权限拒绝类错误详见下文连接测试与错误分类一节源码中专门定义了PolicyTagAccessError来区分这类失败。1.2 GCP 最小权限集合为了成功执行元数据抽取Metadata Extraction与用量Usage工作流用户或服务账号需要具备以下权限权限用途bigquery.datasets.get读取数据集Dataset信息bigquery.tables.get读取表信息bigquery.tables.getData读取表数据Profiler / 抽样等场景需要bigquery.tables.list列举项目下的表resourcemanager.projects.get获取项目元数据bigquery.jobs.create创建查询作业执行 INFORMATION_SCHEMA 查询的前提bigquery.jobs.listAll列举项目内全部作业用量分析依赖可选权限一获取策略标签Policy Tagsdatacatalog.taxonomies.getdatacatalog.taxonomies.list可选权限二Usage 与 Lineage 工作流bigquery.readsessions.createbigquery.readsessions.getData在 GCP 中推荐的做法是创建一个自定义角色Custom Role把上表权限绑定到该角色再将该角色授予执行抽取的服务账号。文档中也建议参考 OpenMetadata 官方文档中关于如何在 GCP 创建自定义角色并绑定权限的说明。从源码看这些权限在 connection.py 中的BIGQUERY_ERRORS错误分类表 中得到了印证当缺失bigquery.jobs.create时会提示授予 BigQuery Job User 角色出现access denied时则提示授予 BigQuery Data Viewer / Metadata Viewer 角色或授予访问INFORMATION_SCHEMA.JOBS_BY_PROJECT的权限。1.3 Profiler 与数据质量Data Quality的额外要求执行 Profiler 工作流或数据质量测试时用户需要对执行 Profiler/测试的表或 Schema 具备SELECT权限被允许查看数据库中所有对象的table_storage信息即INFORMATION_SCHEMA.TABLE_STORAGE视图的可见性。table_storage视图被用于获取表的存储统计信息这在 queries.py 中查询表清单与存储信息的语句INFORMATION_SCHEMA.TABLES t left join INFORMATION_SCHEMA.TABLE_STORAGE s中可以找到直接证据。若权限不足Profiler 步骤会在抽取存储指标时失败。二、连接详情Connection DetailsUI 表单字段逐项解析本部分是 UI 中创建 BigQuery 连接时表单字段的完整参考。所有字段在 bigQueryConnection.json 中有对应的 JSON Schema 定义含类型与默认值可直接对照查阅。2.1 基础连接字段SchemeschemeSQLAlchemy 驱动 scheme 选项。Schema 中枚举值固定为bigquery默认值即bigquery。它是后续构造 SQLAlchemy 连接 URL 的前缀见 connection.py 的get_connection_url最终生成的 URL 形如bigquery://project_id。Host PorthostPortBigQuery API 的 URL默认为bigquery.googleapis.com。如果你使用的是 BigQuery 的自定义实现如本地模拟器或代理可以修改该值。注意该字段只影响 API 端点不影响认证方式。2.2 GCP 凭据配置gcpConfig这是连接的核心部分。OpenMetadata 支持三种凭据注入方式由gcpConfig的类型决定对应源码中的三个 Pydantic 模型见 connection.py 的导入GCP Credentials Path指定服务账号密钥文件的路径GcpCredentialsPathGCP Credentials Values将服务账号密钥文件中的字段值逐个粘贴到表单GcpCredentialsValuesGCP ADCApplication Default Credentials将 GCP 凭据留空让 OpenMetadata 使用环境中的 ADC 认证GcpADC。建议若在本地开发或运行在 GCE/GKE 等拥有元数据服务器的环境中ADC 方式最简单——直接留空 gcpConfig 即可OpenMetadata 会通过google.auth默认凭据链路解析身份。下面逐项说明Credentials Values方式下各字段的取值来源全部来自服务账号密钥 JSON 文件字段取值来源JSON 键说明Credentials Typetypetype服务账号此值为service_accountProject IDprojectIdproject_id可从下拉框单选或多选项目Private Key IDprivateKeyIdprivate_key_id服务账号私钥的唯一标识Private KeyprivateKeyprivate_key认证与授权访问 GCP 的私钥Client EmailclientEmailclient_email服务账号的邮箱地址Client IDclientIdclient_id服务账号的唯一标识Auth URIauthUriauth_uri授权服务器的 URIToken URItokenUritoken_uri获取 OAuth 2.0 访问令牌的端点Auth Provider X509Cert URLauthProviderX509CertUrlauth_provider_x509_cert_url验证授权服务器真实性的证书 URLClient X509Cert URLclientX509CertUrlclient_x509_cert_url验证服务账号真实性的证书 URL2.3 Private Key 的格式陷阱必读privateKey字段是最容易出错的配置项。密钥文件中的私钥是多行 PEM 格式直接粘贴会因换行符导致解析失败。文档给出了明确的转换规则原始格式多行-----BEGIN ENCRYPTED PRIVATE KEY----- MII.. MBQ... CgU.. 8Lt.. ... h4 -----END ENCRYPTED PRIVATE KEY-----需要将换行替换为\n后的格式单行字符串-----BEGIN ENCRYPTED PRIVATE KEY-----\nMII..\nMBQ...\nCgU..\n8Lt..\n...\nh4\n-----END ENCRYPTED PRIVATE KEY-----\n源码侧对此有双重校验在 connection.py 的BIGQUERY_ERRORS中捕获InvalidPrivateKeyException并提示私钥无法被解析为 PEM 密钥请粘贴完整密钥含 BEGIN/END 行与真实换行该异常由 utils/credentials.py 的set_google_credentials在凭据解析阶段抛出。换言之私钥格式错误会在连接测试的第一步即被拦截并得到明确的修复指引。2.4 策略标签相关字段Include Policy TagsincludePolicyTags是否采集 BigQuery 策略标签Policy Tags。Schema 中该字段默认值为true。需注意两点联动关系必须同时开启采集代理ingestion agent中的Include Tags选项若关闭本选项代理将只按Include Tags设置采集标签Labels不再采集策略标签。从源码看metadata.py 的get_columns在构建列对象时会把field.policy_tags直接写入列属性而连接测试中的 GetTags 检查项_list_policy_tags会在includePolicyTagsfalse或未设置taxonomyProjectID/taxonomyLocation时跳过该项测试避免无谓失败。Taxonomy Project IDtaxonomyProjectID策略标签通过 taxonomy分类体系组织。若 BigQuery 表的列上挂了策略标签OpenMetadata 会抓取这些标签并挂到对应列上。此处填写创建了 taxonomy 的项目 ID。注意 Schema 中它是字符串数组type: array支持填写多个项目 ID连接测试会遍历所有这些项目去读取 taxonomy。Taxonomy LocationtaxonomyLocationtaxonomy 所在的位置/区域Schema 默认值为us。连接测试中会以projects/{project_id}/locations/{location}为父路径调用 Data Catalog 的list_taxonomies。2.5 用量Usage与成本相关字段Usage LocationusageLocation用于查询INFORMATION_SCHEMA.JOBS_BY_PROJECT获取用量数据的位置。可传多区域multi-region如us或eu也可传具体区域如us-east1。文档特别提示Australia 与 Asia 多区域暂不支持。Schema 默认值为us。源码中的使用方式有两处connection.py 的_add_location把usageLocation以 URL 参数location...的形式追加到连接 URL 上若已有该参数则跳过usage.py 中的用量查询语句BIGQUERY_STATEMENT直接以FROM \region-{region}.INFORMATION_SCHEMA.JOBS_BY_PROJECT 形式引用该位置。Cost Per TiBcostPerTBBigQuery 用量分析期间每处理 1 TiBtebibyte数据所折算的成本美元。该值用于在分析INFORMATION_SCHEMA.JOBS_BY_PROJECT的用量指标时估算查询成本。两点重要说明它不影响实际计费仅用于内部报告与预估成本的可视化文档提醒默认值可能按 BigQuery 标准按需计费如 $5.00/TiB估算但应根据组织协商的折扣价或 flat-rate 计费模式调整。在 bigQueryConnection.json 中该字段的类型为number默认值是 6.25仓库当前版本实际默认值而非文档示例中的 $5.00请以仓库为准。用量 SQL 中对应的计算为(total_bytes_billed / POWER(2, 40)) * {cost_per_tib}见 queries.py 第 35 行即按 TiB 换算后乘以单价。2.6 高级连接选项Connection OptionsconnectionOptions额外的连接选项用于构造发送给服务端的 URL追加为 URL 查询参数。Connection ArgumentsconnectionArguments额外的连接参数如安全或协议配置在建立连接时传给服务端。在 connection.py 的get_connection_args中可以看到这些参数会合并进 SQLAlchemy 引擎的connect_args。2.7 服务账号冒充Impersonation相关字段以下字段用于**服务账号冒充Service Account Impersonation**场景——即用源服务账号换取目标服务账号的短期凭据后执行操作这在跨项目或需要以特定身份运行查询时非常有用字段说明Target Service Account EmailimpersonateServiceAccount被冒充的目标服务账号邮箱Lifetimelifetime委托凭据的有效秒数AudienceaudienceGoogle Security Token ServiceSTS的 audience包含 workload identity pool 的资源名及其中 provider 标识符Subject Token TypesubjectTokenType基于 OAuth 2.0 令牌交换规范的 STS subject token 类型Token URLtokenURLSTS 令牌交换端点Credential SourcecredentialSource定义从本地环境获取外部凭据的机制以便通过 STS 端点将其交换为 GCP 访问令牌源码实现位于 helper.py 的get_impersonate_client_kwargs当配置了非空的目标账号时会向 BigQuery 客户端注入impersonate_service_account与lifetime同时 connection.py 的get_connection_args会构造一个以冒充身份运行的bigquery.Client注入引擎使连接测试与所有 INFORMATION_SCHEMA 查询都走目标身份。策略标签读取同样遵循冒充配置见 helper.py 的get_policy_tag_client避免元数据以目标身份读取、策略标签却用源身份读取的身份错位。相关行为有专门单元测试覆盖见 test_bigquery_impersonation.py。2.8 Billing Project IDbillingProjectId计费项目 ID 是用于在 Google Cloud 中标识并授权计费的唯一字符串。在 BigQuery 中查询作业需要挂在一个可计费项目下执行。从源码看它有两个作用connection.py 的BigQueryConnection._get_client将其作为billing_project_id传入 SQLAlchemy 引擎helper.py 的get_bigquery_client_for_project在构造项目级客户端时优先使用它作为 project_id。当未配置billingProjectId时连接 URL 中的 project id 会从凭据配置中解析单项目取projectId.root多项目取第一个并在必要时设置GOOGLE_CLOUD_PROJECT环境变量见 connection.py 第 182-192 行。三、多项目支持Project ID 单选与多选projectId字段支持从下拉框选择一个或多个项目。Schema 层面对应 gcpValues 中的SingleProjectId与MultipleProjectId两个模型。多项目连接的底层实现值得注意由于连接 URL 只能携带一个 project idhelper.py 的clone_connection_for_project会为每个项目深拷贝一份连接配置并把projectId收敛为单项目从而让每个项目都能被独立巡检与测试。该函数同时覆盖GcpCredentialsValues、GcpADC、GcpCredentialsPath三种凭据形态避免 ADC/密钥路径场景下多项目连接每次迭代都重新扫描第一个配置项目的隐性 bug。提示多项目模式下get_connection_url只解析第一个项目用于构造引擎 URL真正的项目切换由上层BigquerySource逐项目克隆连接驱动见 connection.py 的BigQueryChecks注释。若你的数据分散在多个项目请确认每个项目都已授予 1.2 节的最小权限。四、筛选模式Filter Pattern连接配置还提供三组正则筛选器用于控制采集范围Default Database Filter PatterndatabaseFilterPattern仅包含/排除匹配正则的数据库在 BigQuery 中即项目Default Schema Filter PatternschemaFilterPattern仅包含/排除匹配正则的 Schema即 DatasetDefault Table Filter PatterntableFilterPattern仅包含/排除匹配正则的表Default Stored Procedure Filter PatternstoredProcedureFilterPattern仅包含/排除匹配正则的存储过程。这些字段在 bigQueryConnection.json 中均引用filterPattern.json的通用定义excludes/includes两个正则数组。用法示例includes: [^my_project\\..*]只采集指定项目excludes: [temp_.*]跳过临时表。五、Sample Storage AWS S3 配置当需要把样本数据Sample Data存储到 AWS S3时例如开启 Profiler 抽样并落盘连接配置中会出现一组 S3 相关字段它们定义在sampleDataStorageConfig见 bigQueryConnection.json 第 144-147 行字段说明AWS Access Key IDawsAccessKeyIdAWS 访问密钥 ID如AKIAIOSFODNN7EXAMPLE需与 Secret Access Key 成对使用AWS Secret Access KeyawsSecretAccessKey秘密访问密钥如wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYAWS RegionawsRegion服务所在区域是连接配置中唯一必填的 AWS 参数AWS Session TokenawsSessionToken使用临时凭据时需额外提供会话令牌Endpoint URLendPointURL可指定 AWS 服务的替代端点 URL默认按区域使用标准端点Profile NameprofileName使用default以外的 AWS CLI 命名配置文件Assume Role ARNassumeRoleArn跨账号访问时的角色 ARN使用 AssumeRole 时必填Assume Role Session NameassumeRoleSessionName假定角色会话标识符默认OpenMetadataSessionAssume Role Source IdentityassumeRoleSourceIdentity调用 AssumeRole 的主体源身份可在 CloudTrail 日志中溯源Bucket NamebucketNameS3 存储桶名称用于组织与存储数据对象Prefixprefix数据路径前缀用于在桶内组织/分类数据说明这组字段属于sampleDataStorageConfig样本数据存储配置只有在需要把样本数据写入 S3 时才需要完整填写若未配置存储Profiler 的抽样数据按默认行为处理。六、连接测试与错误分类源码级排障指引BigQuery 连接器在测试连接阶段会依次执行一组检查项定义在 connection.py 的BigQueryChecksCheckAccessping 连通性跳过 TCP 探测因为 BigQuery 无 host:port 可预检仅捕获真实的 socket/DNS 网络错误GetSchemas列举 SchemaDatasetGetTables / GetViews枚举数据集及其中的 TABLE / EXTERNAL / VIEW / MATERIALIZED_VIEW 对象对列表过程中被删除的数据集做了NotFound容忍GetTags仅当includePolicyTagstrue且配置了 taxonomyProjectID/taxonomyLocation 时执行遍历 taxonomy 与 policy tagsGetQueries用BIGQUERY_TEST_STATEMENT探测region-{usageLocation}.INFORMATION_SCHEMA.JOBS_BY_PROJECT查询历史的可读性。这些检查项由 BIGQUERY_ERRORS 错误分类表 提供精准诊断。常见的失败与修复建议速查报错特征诊断修复建议PolicyTagAccessError无法读取策略标签授予 Data Catalog Viewer 角色datacatalog.taxonomies.list/.get若配置了冒充则授予被冒充的服务账号核对taxonomyProjectID/taxonomyLocationInvalidPrivateKeyException私钥格式错误粘贴完整 PEM 密钥含 BEGIN/END 行与真实换行invalid_grant服务账号凭据被拒核对私钥与 client email检查密钥是否被撤销/禁用/过期DefaultCredentialsError找不到 GCP 凭据提供服务账号密钥或在运行环境配置 ADCRefreshError无法换取访问令牌检查密钥、client email 及账号状态含bigquery.jobs.create缺少运行作业权限在计费项目上授予 BigQuery Job User 角色access denied/Forbidden已认证但未授权授予 BigQuery Data Viewer / Metadata Viewer 等角色NotFound项目或数据集不存在核对 project id 与 dataset 是否存在、服务账号是否可见每个步骤的超时预算为 3 分钟step_timeout_seconds THREE_MIN见 connection.py 第 402 行以便大项目不会因单步过慢被误判失败。对应测试见 test_bigquery_test_connection.py。七、工作流配置实战YAML 示例与能力矩阵7.1 元数据抽取工作流仓库中提供了可直接参考的 bigquery.yaml 示例其核心结构如下source: type: bigquery serviceName: local_bigquery serviceConnection: config: type: BigQuery taxonomyProjectID: [ project-id-where-policy-tags-exist ] # includePolicyTags: false credentials: gcpConfig: type: service_account projectId: project_id privateKeyId: private_key_id privateKey: private_key clientEmail: gcpuserproject_id.iam.gserviceaccount.com clientId: client_id authUri: https://accounts.google.com/o/oauth2/auth tokenUri: https://oauth2.googleapis.com/token authProviderX509CertUrl: https://www.googleapis.com/oauth2/v1/certs clientX509CertUrl: https://www.googleapis.com/oauth2/v1/certs sourceConfig: config: type: DatabaseMetadata sink: type: metadata-rest config: {} workflowConfig: openMetadataServerConfig: hostPort: http://localhost:8585/api authProvider: openmetadata securityConfig: jwtToken: your-jwt-token字段与 UI 表单一一对应taxonomyProjectID对应策略标签项目、credentials.gcpConfig对应 GCP 凭据 Values 表单privateKey需按 2.3 节的\n转义规则填入。在 单元测试 test_bigquery.py 的 mock 配置 中可以看到同一结构的完整形态含billingProjectId、includeTags等字段。7.2 连接器能力矩阵从 service_spec.py 可以看到 BigQuery 连接器注册的全部能力组件能力实现类说明元数据抽取BigquerySource表/视图/物化视图、Schema 描述、主外键约束、存储过程、生命周期、DDL、策略标签与标签血缘BigqueryLineageSource基于查询历史的血缘 存储过程血缘StoredProcedureLineageMixin用量BigqueryUsageSource基于INFORMATION_SCHEMA.JOBS_BY_PROJECT的查询级用量分析ProfilerBigQueryProfilerInterface表/列画像与系统指标抽样BigQuerySampler数据采样连接BigQueryConnection连接建立与测试同时在 bigQueryConnection.json 中声明了连接器支持的通用能力开关元数据抽取、增量元数据抽取Incremental、用量抽取、血缘抽取、DBT 抽取、Profiler、System Profile、Query Comment、Data Diff 等。与元数据抽取同目录下还提供 bigquery_lineage.yaml、bigquery_usage.yaml、bigquery_profiler.yaml 等独立工作流示例。7.3 增量元数据抽取Incremental Metadata ExtractionBigQuery 连接器支持增量元数据抽取底层由 incremental_table_processor.py 的BigQueryIncrementalTableProcessor实现配合supportsIncrementalMetadataExtraction开关见 bigQueryConnection.json 第 115-118 行。开启后工作流只处理自上次运行以来发生变更的表可显著缩短大项目的元数据刷新耗时。其行为有专门的单元测试 test_bigquery_incremental_table_processor.py 覆盖。7.4 主外键约束的获取BigQuery 的原生 INFORMATION_SCHEMA 并不直接暴露主外键OpenMetadata 通过 helper.py 的get_pk_constraint/get_foreign_keys覆写 SQLAlchemy 的 inspector 方法用BIGQUERY_CONSTRAINTS查询见 queries.py 第 70-94 行联查KEY_COLUMN_USAGE、CONSTRAINT_COLUMN_USAGE、TABLE_CONSTRAINTS三张视图获取约束并以{project}.{schema}为键做进程内缓存CONSTRAINT_CACHE避免对同一数据集反复查询。八、常见问题速查FAQQ1连接测试在 GetTags 步骤失败先确认是否真的需要策略标签若不需要关闭includePolicyTags同时建议关闭采集代理的 Include Tags即可跳过该项。若需要则授予 Data Catalog Viewer 角色并确认taxonomyProjectID数组可多填与taxonomyLocation指向 taxonomy 真实所在的项目与区域。Q2Usage 工作流查不到数据确认usageLocation已正确设置多区域us/eu或具体区域注意 Australia 与 Asia 多区域不支持且服务账号拥有bigquery.jobs.listAll、bigquery.jobs.create与读取INFORMATION_SCHEMA.JOBS_BY_PROJECT的权限。用量 SQL 会过滤掉 OpenMetadata 自身与 dbt 发起的查询见 queries.py 第 42-43 行。Q3多项目连接只采集到第一个项目确认每个项目都已授予最小权限且各项目 id 在projectId下拉框中正确勾选。多项目场景依赖clone_connection_for_project逐项目克隆连接若某个项目权限缺失会体现在该项目对应的测试结果中。Q4私钥粘贴后报Malformed private key按 2.3 节将 PEM 块中的换行替换为\n确保包含-----BEGIN ... PRIVATE KEY-----与-----END ... PRIVATE KEY-----完整行。九、相关资源索引连接器 UI 文档BigQuery.mdJSON Schema 定义字段/默认值/必填项bigQueryConnection.json连接建立与测试实现connection.py辅助工具冒充、约束、策略标签helper.py元数据抽取实现metadata.py用量抽取实现usage.py血缘抽取实现lineage.py查询语句集合queries.py能力注册service_spec.py工作流示例bigquery.yaml另见同目录下 bigquery_lineage.yaml、bigquery_usage.yaml、bigquery_profiler.yaml、bigquery_classifier.yaml单元测试test_bigquery.py、test_bigquery_test_connection.py、test_bigquery_impersonation.py、test_bigquery_incremental_table_processor.py【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考