Google Cloud Dataproc Python 客户端(google-cloud-dataproc 5.25.0)实战指南

原创2026-10-10 21:11:151,873 阅读

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 选项,需要更严格的运维行为时可以显式配置。

常见陷阱清单

  1. 安装名与导入名不一致:pip install google-cloud-dataproc(连字符),from google.cloud import dataproc_v1(下划线);
  2. 误用全局端点:官方参考文档明确要求 Dataproc 客户端使用区域端点,不要图省事使用全局端点;
  3. 混淆集群作业与 Serverless 批次:JobControllerClient 面向已有集群;BatchControllerClient 面向 Dataproc Serverless。两者 API 面不同,不能混用;
  4. 忘记处理长时操作:创建/更新/删除类调用需调用 .result(),或保存 operation name 后主动轮询;
  5. 本地代码不会自动上传:脚本、jar、依赖归档必须先放到 GCS,客户端不会替你上传;
  6. latest 参考页面版本不同步:官方 latest 参考文档的各页面版本标注并不完全一致,复制代码片段前应交叉核对 PyPI 版本与 Dataproc changelog;
  7. 功能受区域/镜像版本限制:部分批次与集群功能对区域或镜像版本敏感。如果字段在参考文档中看似合法但 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 精确、按版本地检索与引用。

登录后查看全文
context-hub