Google Cloud Dataproc Python 客户端(google-cloud-dataproc 5.25.0)实战指南
Google Cloud Dataproc Python 客户端(google-cloud-dataproc 5.25.0)实战指南
本文以 Context Hub 仓库中收录的 Google Cloud Dataproc Python 官方文档为骨架,系统讲解 google-cloud-dataproc 5.25.0 的安装、认证、客户端初始化,以及「集群生命周期管理」「向既有集群提交作业」「Dataproc Serverless 批次」三大核心使用模式,并结合本仓库的源码与内容组织方式补充实现层面的细节。读完本文,你将能够用 Python 正确编写可运行的 Dataproc 客户端代码,理解区域端点、ADC 认证、长时操作轮询等关键约定,并避开安装名与导入名不一致、全局端点误用、本地代码不自动上传等高频陷阱。
Golden Rule:把 Dataproc 当作「区域化 API」来使用
使用 Dataproc Python 客户端,核心准则是:
- 使用官方
google-cloud-dataproc客户端库; - 使用 Application Default Credentials(ADC)认证,而不是 API Key;
- 将 Dataproc 视为区域级 API 面:创建客户端时必须指定区域端点(如
us-central1-dataproc.googleapis.com:443),并且请求体中的region要与端点保持一致; - 提交作业前先把代码和数据放到 Cloud Storage,客户端不会替你上传本地文件。
作为版本事实来源,PyPI 当前列出的 google-cloud-dataproc 版本为 5.25.0(截至本仓库文档更新日期 2026-03-12)。官方 latest 参考站点的各个页面存在版本标注不一致的情况,因此以 PyPI 作为包版本的事实来源,以官方参考文档作为 API 形态的参考——这是本指南贯穿全文的版本核对原则。
在 Context Hub 中,本指南对应的源文档位于 content/google/docs/dataproc/python/DOC.md,其 frontmatter 标记了 languages: "python"、versions: "5.25.0"、source: maintainer,属于由维护者维护的 Python 语言变体;同目录下还有 JavaScript 变体 content/google/docs/dataproc/javascript/DOC.md(对应 @google-cloud/dataproc 6.3.0)。这种「作者/文档/语言变体」的组织方式遵循 docs/content-guide.md 中定义的多语言文档规范。
安装与版本锁定
推荐先用 pip 升级自身,再安装指定版本:
python -m pip install --upgrade pip
python -m pip install "google-cloud-dataproc==5.25.0"
常见的替代安装方式(适合不同包管理习惯的项目):
uv add "google-cloud-dataproc==5.25.0"
poetry add "google-cloud-dataproc==5.25.0"
由于 Dataproc 作业通常引用存放在 Google Cloud Storage(GCS)中的代码与数据,许多项目还会单独安装 google-cloud-storage,用于在提交作业前上传产物(jar、脚本、依赖归档等):
python -m pip install google-cloud-storage
注意:安装名与导入名不同。安装时使用 pip install google-cloud-dataproc(带连字符),导入时使用 from google.cloud import dataproc_v1(带下划线),二者不要混淆。
从源码层面看,Context Hub 的 CLI 通过 chub get <id> --lang py 按语言变体拉取文档:cli/src/lib/registry.js 中的 resolveDocPath() 会先按语言(py 等)定位语言对象,再按 recommendedVersion 或显式 --version 定位具体版本目录,最终解析到对应语言/版本下的 DOC.md 入口文件(见 cli/src/lib/registry.js 与 cli/src/commands/get.js)。这正是多语言、多版本文档能够被 Agent 精确获取的实现基础。
认证与项目配置
Dataproc 使用 Google Cloud 凭据(Credentials),而不是 API Key。
本地开发推荐配置(ADC 方式):
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable dataproc.googleapis.com
gcloud auth application-default login会在本地生成 ADC 所需的默认凭据;gcloud config set project指定默认项目;gcloud services enable dataproc.googleapis.com启用 Dataproc API。
CI 或服务器环境(服务账号方式):
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GOOGLE_CLOUD_PROJECT=your-project-id
export DATAPROC_REGION=us-central1
其中 GOOGLE_APPLICATION_CREDENTIALS 指向服务账号 JSON 文件,GOOGLE_CLOUD_PROJECT 供代码读取项目 ID,DATAPROC_REGION 供代码读取区域(本文示例代码中即通过 os.getenv("DATAPROC_REGION", "us-central1") 读取)。
生产环境建议优先使用 Workload Identity 或附加服务账号(attached service account),避免使用长期有效的 JSON 密钥文件——这是 Google Cloud 官方推荐的安全实践。
初始化客户端:三大 Controller 与区域端点
该包暴露多个服务客户端。对绝大多数编码任务而言,关键的是这三个:
| 客户端 | 职责 |
|---|---|
ClusterControllerClient |
集群生命周期管理(创建、更新、删除、列出) |
JobControllerClient |
向已有集群提交 Spark / PySpark / Hive / Hadoop 作业 |
BatchControllerClient |
Dataproc Serverless 批次(无长期集群的独立 API 面) |
三个客户端都应通过区域端点创建:
import os
from google.api_core.client_options import ClientOptions
from google.cloud import dataproc_v1
PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
REGION = os.getenv("DATAPROC_REGION", "us-central1")
def regional_client_options(region: str) -> ClientOptions:
return ClientOptions(api_endpoint=f"{region}-dataproc.googleapis.com:443")
cluster_client = dataproc_v1.ClusterControllerClient(
client_options=regional_client_options(REGION)
)
job_client = dataproc_v1.JobControllerClient(
client_options=regional_client_options(REGION)
)
batch_client = dataproc_v1.BatchControllerClient(
client_options=regional_client_options(REGION)
)
注意端点是 {region}-dataproc.googleapis.com:443 形式,不要误用全局端点。官方参考文档明确要求 Dataproc 客户端使用区域端点;端点、请求中的 region、parent 三者必须保持一致,否则会出现请求错配。
如果需要显式传入凭据(例如在非 ADC 环境下),可以用 service_account 方式:
from google.api_core.client_options import ClientOptions
from google.cloud import dataproc_v1
from google.oauth2 import service_account
credentials = service_account.Credentials.from_service_account_file(
"/path/to/service-account.json"
)
client = dataproc_v1.JobControllerClient(
credentials=credentials,
client_options=ClientOptions(
api_endpoint="us-central1-dataproc.googleapis.com:443"
),
)
核心使用模式一:创建与列出集群
需要自行管理经典 Dataproc 集群时,使用 ClusterControllerClient。以下示例创建一个名为 analytics-dev 的小型开发集群(1 个主节点 + 2 个工作节点,均为 e2-standard-4),随后列出该区域下的全部集群:
from google.api_core.client_options import ClientOptions
from google.cloud import dataproc_v1
region = "us-central1"
project_id = "your-project-id"
cluster_client = dataproc_v1.ClusterControllerClient(
client_options=ClientOptions(
api_endpoint=f"{region}-dataproc.googleapis.com:443"
)
)
cluster = {
"cluster_name": "analytics-dev",
"config": {
"gce_cluster_config": {
"zone_uri": "us-central1-a",
},
"master_config": {
"num_instances": 1,
"machine_type_uri": "e2-standard-4",
},
"worker_config": {
"num_instances": 2,
"machine_type_uri": "e2-standard-4",
},
},
}
operation = cluster_client.create_cluster(
request={
"project_id": project_id,
"region": region,
"cluster": cluster,
}
)
created_cluster = operation.result(timeout=1800)
print(created_cluster.cluster_uuid)
for item in cluster_client.list_clusters(
request={"project_id": project_id, "region": region}
):
print(item.cluster_name, item.status.state)
配置字段说明:
gce_cluster_config.zone_uri:集群所在可用区(这里写的是区域简写形式,实际创建时按需求填写完整 zone URI);master_config.num_instances/worker_config.num_instances:主节点/工作节点数量;master_config.machine_type_uri/worker_config.machine_type_uri:节点机器类型,如e2-standard-4。
长时操作(Long-Running Operation)是 Dataproc 客户端的常态:create_cluster、update_cluster、delete_cluster 都不会立即完成,必须调用 .result() 等待。示例中 operation.result(timeout=1800) 即等待操作完成,超时上限 1800 秒;也可以保存 operation.name 之后主动轮询。
核心使用模式二:向已有集群提交作业
已经拥有集群、想要在上面运行 Spark / PySpark / Hive / Hadoop 作业时,使用 JobControllerClient。以下示例向 analytics-dev 集群提交一个 PySpark 作业,入口脚本存放在 GCS,并传入一个命令行参数:
from google.api_core.client_options import ClientOptions
from google.cloud import dataproc_v1
region = "us-central1"
project_id = "your-project-id"
cluster_name = "analytics-dev"
job_client = dataproc_v1.JobControllerClient(
client_options=ClientOptions(
api_endpoint=f"{region}-dataproc.googleapis.com:443"
)
)
job = {
"placement": {
"cluster_name": cluster_name,
},
"pyspark_job": {
"main_python_file_uri": "gs://your-bucket/jobs/main.py",
"args": ["--date", "2026-03-12"],
},
}
operation = job_client.submit_job_as_operation(
request={
"project_id": project_id,
"region": region,
"job": job,
}
)
submitted_job = operation.result(timeout=1800)
print(submitted_job.reference.job_id)
print(submitted_job.driver_output_resource_uri)
两种提交方式的取舍:
submit_job():立即返回Job资源,适合自行轮询作业状态的场景;submit_job_as_operation():返回操作对象,适合走 Operation 流程、用.result()等待的场景。
driver_output_resource_uri 是作业 driver 输出在 GCS 上的位置,可用于事后排查 Spark 日志。
核心使用模式三:运行 Dataproc Serverless 批次
Dataproc Serverless 与「在长期集群上跑作业」是两个不同的 API 面:Serverless 批次由 BatchControllerClient 管理,不需要你维护任何集群。以下示例创建一个 PySpark Serverless 批次,并指定运行时版本与 Spark 属性:
from google.api_core.client_options import ClientOptions
from google.cloud import dataproc_v1
region = "us-central1"
project_id = "your-project-id"
batch_client = dataproc_v1.BatchControllerClient(
client_options=ClientOptions(
api_endpoint=f"{region}-dataproc.googleapis.com:443"
)
)
batch = {
"pyspark_batch": {
"main_python_file_uri": "gs://your-bucket/jobs/etl.py",
"args": ["--env", "dev"],
},
"runtime_config": {
"version": "2.2",
"properties": {
"spark.executor.instances": "2",
},
},
"environment_config": {
"execution_config": {
"service_account": "dataproc-runner@your-project-id.iam.gserviceaccount.com",
"subnetwork_uri": (
"projects/your-project-id/regions/us-central1/subnetworks/default"
),
},
},
}
operation = batch_client.create_batch(
request={
"parent": f"projects/{project_id}/regions/{region}",
"batch": batch,
"batch_id": "daily-etl-20260312",
"request_id": "c1d9b0b1-2b4e-4a47-a03d-9b6d5d118df8",
}
)
created_batch = operation.result(timeout=1800)
print(created_batch.name)
print(created_batch.state)
字段说明:
runtime_config.version:Dataproc 运行时版本(示例为"2.2");runtime_config.properties:Spark 属性键值对,如spark.executor.instances;environment_config.execution_config.service_account:批次运行时使用的服务账号;environment_config.execution_config.subnetwork_uri:批次所在子网 URI(完整形式为projects/{project}/regions/{region}/subnetworks/{name});parent:批次所属父资源,格式为projects/{project_id}/regions/{region},必须与端点区域一致;batch_id:自定义批次 ID,便于后续定位;request_id:值得设置的幂等字段——当可能发生重试时,它能让创建请求在传输失败后安全重放,避免重复创建。
核心使用模式四:轮询与枚举已有批次
创建批次之后,可以用 list_batches 枚举某区域下的所有批次及其状态:
parent = f"projects/{project_id}/regions/{region}"
for batch in batch_client.list_batches(request={"parent": parent}):
print(batch.name, batch.state)
batch.name 是批次的完整资源名,batch.state 是批次状态(如 STATE_UNSPECIFIED、PENDING、RUNNING、SUCCEEDED、FAILED 等),可用于驱动轮询逻辑。
配置要点汇总
- 区域一致性:Dataproc 是区域级资源,
region、parent与客户端端点必须保持对齐,三者不一致是配置错误的高发点; - GCS URI 是主流:请求载荷中常见的脚本/数据路径都是
gs://bucket/path/file.py这样的 GCS URI,本地文件路径不会被自动上传; - 字典与 protobuf 对象均可:多数请求参数既可以传类型化 protobuf 对象,也可以传普通 Python 字典;对于 Agent 或脚本自动化场景,字典通常更容易正确组装(本文示例均采用字典形式);
- 重试与超时:客户端方法通过
google-api-core支持retry与timeout选项,需要更严格的运维行为时可以显式配置。
常见陷阱清单
- 安装名与导入名不一致:
pip install google-cloud-dataproc(连字符),from google.cloud import dataproc_v1(下划线); - 误用全局端点:官方参考文档明确要求 Dataproc 客户端使用区域端点,不要图省事使用全局端点;
- 混淆集群作业与 Serverless 批次:
JobControllerClient面向已有集群;BatchControllerClient面向 Dataproc Serverless。两者 API 面不同,不能混用; - 忘记处理长时操作:创建/更新/删除类调用需调用
.result(),或保存 operation name 后主动轮询; - 本地代码不会自动上传:脚本、jar、依赖归档必须先放到 GCS,客户端不会替你上传;
latest参考页面版本不同步:官方latest参考文档的各页面版本标注并不完全一致,复制代码片段前应交叉核对 PyPI 版本与 Dataproc changelog;- 功能受区域/镜像版本限制:部分批次与集群功能对区域或镜像版本敏感。如果字段在参考文档中看似合法但 API 拒绝,请先确认 Dataproc 镜像/运行时版本与区域是否支持。
5.25.0 版本敏感说明
- PyPI 显示
5.25.0为当前包版本,发布于 2026 年 2 月 19 日; - 官方
latest文档的 changelog 已包含 5.25.0 的变更,其中包括对零规模集群(zero-scale clusters)的ClusterType支持; latest文档根目录下部分服务的 API 参考页面仍显示旧版本标签——请把「包版本」和「页面标题版本」视为两个独立的信号,不要混为一谈。
官方资料与版本核对建议
撰写或维护 Dataproc 客户端代码时,建议以官方渠道为准,按用途区分信息来源:
- 包版本事实:以 PyPI 项目页的
google-cloud-dataproc版本为准(本文撰写时即 5.25.0); - API 形态:以官方 Dataproc Python 参考文档为准,其中分别包含
ClusterControllerClient、JobControllerClient、BatchControllerClient的详细参考页; - 变更记录:以官方 Dataproc changelog 为准,用于确认某个字段或能力在目标版本中的支持情况;
- 认证机制:以 Google Cloud 的 Application Default Credentials(ADC)指南为准。
在本仓库中,这份文档与 JavaScript 变体共用 name: dataproc 标识(见 content/google/docs/dataproc/javascript/DOC.md),由 Context Hub 构建为同一 registry 条目下的多语言版本;Agent 或开发者可通过 chub get google/dataproc --lang py(或 --lang js)按需获取对应语言的最新文档。文档的 frontmatter 解析、语言/版本路径解析分别实现在 cli/src/lib/frontmatter.js 与 cli/src/lib/registry.js 中,而 docs/content-guide.md 则完整说明了此类多语言、多版本条目的组织与构建规则——这些机制保证了仓库中的 API 文档能够被 Agent 精确、按版本地检索与引用。