google-cloud-dataproc-metastore Python 客户端实战指南:管理 Dataproc Metastore 服务、元数据导入与备份恢复
google-cloud-dataproc-metastore Python 客户端实战指南:管理 Dataproc Metastore 服务、元数据导入与备份恢复
本文是 google-cloud-dataproc-metastore Python 客户端(版本 1.21.0)的完整使用指南,覆盖安装、认证、客户端初始化、服务生命周期管理、元数据导入与查询、备份恢复六大核心工作流。读完本文,你将能够用 Python 以编程方式创建和管理 Dataproc Metastore 服务、从 Cloud Storage 导入 Hive 元数据、对运行中的服务发起元数据查询,并搭建可靠的备份恢复流程;本文内容以本仓库维护的官方文档 content/google/docs/dataproc-metastore/python/DOC.md 为骨架,并结合仓库内的 CLI 工具与内容组织规范做了源码级佐证与扩充。
用途边界:控制平面 SDK,而非 Hive 客户端
先明确 google-cloud-dataproc-metastore 的定位,这决定了后续所有代码的写法。该包是 Dataproc Metastore 的控制平面(control-plane)SDK,用于:
- 创建和管理 metastore 服务(service);
- 执行元数据导入(metadata import);
- 查询元数据(query metadata);
- 管理备份(backup)与恢复(restore)。
它不是 Hive 或 SQL 客户端,不能直接用它连接你的 metastore 端点去执行 SELECT 之类的查询。标准的导入方式为:
from google.cloud import metastore_v1
metastore_v1 是当前客户端生成的主版本模块,DataprocMetastoreClient 是它的核心服务客户端。在同一作者的姊妹文档 Dataproc 客户端指南 中,Dataproc 本体负责集群与作业管理,而本包负责元数据服务管理,二者配合使用可组成完整的「集群计算 + 元数据服务」体系。
安装
建议先升级 pip,再安装指定版本。本仓库文档锁定的是 1.21.0 版本(对应 frontmatter 中 versions: "1.21.0"、updated-on: 2026-03-13):
python -m pip install --upgrade pip
python -m pip install "google-cloud-dataproc-metastore==1.21.0"
常见包管理器替代方案:
uv add "google-cloud-dataproc-metastore==1.21.0"
poetry add "google-cloud-dataproc-metastore==1.21.0"
PyPI 当前列出 1.21.0,该包面向 Python >=3.7 发布。固定版本号可以避免生产环境中因 SDK 行为变化导致的意外,这在按版本组织的文档体系中尤为重要——本仓库的 Content Guide 明确指出,frontmatter 的 versions 字段始终指向 PyPI/npm 上的包版本,而非 API 版本。
认证与初始化
使用 Application Default Credentials(ADC)
该客户端库使用 Application Default Credentials(ADC) 进行认证,不接受 API key。本地开发推荐三步完成认证与项目配置:
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable metastore.googleapis.com
第一条命令在本地生成本机用户的 ADC 凭据,第二条设置默认项目,第三条启用 Dataproc Metastore API。
服务账号回退方案
在 CI 或服务器环境中,可以用服务账号 JSON 文件配合环境变量完成认证:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"
export METASTORE_REGION="us-central1"
文档特别建议:在已部署环境中,优先使用 Workload Identity 或绑定的服务账号,而不是长期有效的 JSON 密钥,以缩小密钥泄露面。
初始化客户端
默认端点为 metastore.googleapis.com,因此多数场景下直接创建普通客户端即可:
import os
from google.cloud import metastore_v1
PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
REGION = os.getenv("METASTORE_REGION", "us-central1")
client = metastore_v1.DataprocMetastoreClient()
location_name = f"projects/{PROJECT_ID}/locations/{REGION}"
如果显式需要指定凭据,可以改用 google.oauth2.service_account 从文件加载:
from google.cloud import metastore_v1
from google.oauth2 import service_account
credentials = service_account.Credentials.from_service_account_file(
"/path/to/service-account.json"
)
client = metastore_v1.DataprocMetastoreClient(credentials=credentials)
全资源名约定
Dataproc Metastore 的 API 约定使用全资源名(full resource names),而不是短 ID。典型的服务资源名格式为:
service_name = (
f"projects/{PROJECT_ID}/locations/{REGION}/services/my-metastore"
)
后续所有请求(导入、备份、恢复、查询)都会反复用到这种 projects/{project}/locations/{region}/services/{service} 形态的名称,建议在代码中统一封装为构造函数。
核心工作流
1. 列出现有 Metastore 服务
list_services() 返回一个分页对象(pager),可以直接迭代:
from google.cloud import metastore_v1
client = metastore_v1.DataprocMetastoreClient()
parent = "projects/your-project/locations/us-central1"
for service in client.list_services(request={"parent": parent}):
print(service.name, service.state, service.endpoint_uri)
每个 service 对象带有 name(全资源名)、state(服务状态)和 endpoint_uri(服务端点)等字段,便于在脚本中盘点当前项目与区域下的全部 metastore 服务。
2. 创建 Metastore 服务
创建操作返回一个长期运行操作(long-running operation),必须等待 .result() 返回后服务才可用:
from google.cloud import metastore_v1
client = metastore_v1.DataprocMetastoreClient()
parent = "projects/your-project/locations/us-central1"
service = metastore_v1.Service(
network="projects/your-project/global/networks/default",
port=9083,
tier=metastore_v1.Service.Tier.DEVELOPER,
hive_metastore_config=metastore_v1.Service.HiveMetastoreConfig(
version=metastore_v1.Service.HiveMetastoreConfig.Version.V3_1_2
),
)
operation = client.create_service(
request=metastore_v1.CreateServiceRequest(
parent=parent,
service_id="dev-metastore",
service=service,
)
)
created = operation.result(timeout=1800)
print(created.name)
print(created.endpoint_uri)
关键参数说明:
network:必须是完整的 VPC 资源名,如projects/{project}/global/networks/{network},不能传裸名称default。官方服务文档还特别注明:该网络中的所有子网 IP 段必须是 RFC 1918 私有地址范围;port:Hive Metastore 默认端口9083;tier:服务层级,示例使用DEVELOPER(开发者档位,成本更低,适合测试);hive_metastore_config.version:Hive Metastore 版本枚举,示例使用V3_1_2;timeout=1800:.result()的超时上限(秒),创建集群级服务通常需要分钟级等待,务必按业务预期设置合理超时。
3. 从 Cloud Storage 中的数据库转储导入元数据
当已有受支持的数据库转储文件存放在 Cloud Storage 时,可用 create_metadata_import 将其加载进 Dataproc Metastore 服务:
from google.cloud import metastore_v1
client = metastore_v1.DataprocMetastoreClient()
service_name = (
"projects/your-project/locations/us-central1/services/dev-metastore"
)
metadata_import = metastore_v1.MetadataImport(
database_dump=metastore_v1.MetadataImport.DatabaseDump(
database_type=metastore_v1.MetadataImport.DatabaseDump.DatabaseType.MYSQL,
gcs_uri="gs://your-bucket/metastore/hive.sql",
)
)
operation = client.create_metadata_import(
request=metastore_v1.CreateMetadataImportRequest(
parent=service_name,
metadata_import_id="bootstrap-import",
metadata_import=metadata_import,
)
)
result = operation.result(timeout=1800)
print(result.name)
print(result.state)
要点:
- 数据库转储源是 Cloud Storage URI(
gs://),指向本地文件是无效的; - 生成的类型枚举暴露了 MySQL 与 PostgreSQL 两种转储类型(
DatabaseType.MYSQL/DatabaseType.POSTGRESQL),可按源库类型选择; - 这也是把既有 Hive 元数据「引导」进新服务的最常见场景(文档中的示例即命名为
bootstrap-import)。
4. 查询 Metastore 元数据
query_metadata() 可对运行中的 metastore 服务发起元数据查询:
from google.cloud import metastore_v1
client = metastore_v1.DataprocMetastoreClient()
response = client.query_metadata(
request=metastore_v1.QueryMetadataRequest(
service=(
"projects/your-project/locations/us-central1/services/dev-metastore"
),
query="SHOW DATABASES",
)
)
print(response.result_manifest)
print(response.result_uri)
响应包含 result_manifest 与 result_uri 两个字段:前者是查询结果的清单信息,后者是查询输出的 URI,用于进一步读取查询产物。注意 QueryMetadataRequest.query 是元数据查询字符串,应视为服务输入(service input),不要在其中拼接不受信任的文本——它不是安全的插值位置。
5. 创建备份并从备份恢复
备份创建同样是长期运行操作:
from google.cloud import metastore_v1
client = metastore_v1.DataprocMetastoreClient()
service_name = (
"projects/your-project/locations/us-central1/services/dev-metastore"
)
operation = client.create_backup(
request=metastore_v1.CreateBackupRequest(
parent=service_name,
backup_id="nightly-backup-20260313",
backup=metastore_v1.Backup(),
)
)
backup = operation.result(timeout=1800)
print(backup.name)
print(backup.state)
从备份恢复服务时,传入备份的全资源名:
from google.cloud import metastore_v1
client = metastore_v1.DataprocMetastoreClient()
operation = client.restore_service(
request=metastore_v1.RestoreServiceRequest(
service=(
"projects/your-project/locations/us-central1/services/dev-metastore"
),
backup=(
"projects/your-project/locations/us-central1/"
"services/dev-metastore/backups/nightly-backup-20260313"
),
)
)
restored = operation.result(timeout=1800)
print(restored.name)
print(restored.state)
生成的 Backup 类型特别注明:只有运行受支持 Hive Metastore 版本的服务才支持备份。因此如果你的工作流依赖备份/恢复,必须先核实目标服务的 Hive Metastore 版本是否在支持列表内,否则 create_backup 可能直接失败。
配置要点与约定
综合本仓库文档的 Configuration Notes 部分,使用该 SDK 时应遵守以下约定:
- 请求中使用全资源名,不要用短 ID:
service、backup、parent等字段都要求projects/.../locations/.../services/...的完整形态; - 写操作均为长期运行操作:创建(create)、导入(import)、备份(backup)、恢复(restore)、更新(update)、删除(delete)都不会立即完成,必须等待 operation 的
.result(),或保存 operation name 后自行轮询; - 异步场景使用 AsyncClient:如果你的代码是异步的,使用
metastore_v1.DataprocMetastoreAsyncClient而不是同步客户端; - 查询字符串视为服务输入:
QueryMetadataRequest.query不要用于拼接不受信任的文本。
这些约定与 Dataproc 姊妹文档 content/google/docs/dataproc/python/DOC.md 中的模式一致(同样强调全资源名、区域对齐、operation.result(timeout=1800) 的等待模式),说明「长期运行操作 + 全资源名」是整个 Dataproc 生态客户端的一致设计。
常见陷阱排查清单
文档在 Common Pitfalls 部分列出了开发中最容易踩的六个坑,逐条对照可显著减少调试时间:
- 不要用 API key 认证:本包只接受 Google Cloud 凭据(ADC / 服务账号),传 API key 必然失败;
- 不要混淆管理 SDK 与直接 Hive 访问:该库管理服务和运维操作,不是直接连 Hive 端点的 SQL 客户端;
- 不要传裸网络名:
Service.network需要完整 VPC 资源路径,如projects/your-project/global/networks/default,传default会报错; - 不要假设创建是瞬时的:必须先等待返回的 operation,再使用服务端点;
- 不要把元数据导入指向本地文件:
MetadataImport.DatabaseDump.gcs_uri必须是 Cloud Storage 的gs://URI; - 不要假设所有 Hive Metastore 版本都支持备份:依赖备份工作流前,先核实服务的版本。
在本仓库中如何获取与验证这份文档
本文对应的文档本体存放在本仓库 content/google/docs/dataproc-metastore/python/DOC.md,按仓库的内容组织规范(见 Content Guide),其入口 ID 为 google/dataproc-metastore,语言变体为 Python。开发者或编码 Agent 可以通过本仓库配套的 chub CLI 检索并获取该文档的最新版本:
chub search "dataproc metastore" # 找到文档入口
chub get google/dataproc-metastore --lang py # 获取 Python 变体文档
相关命令的完整说明见 CLI Reference,Agent 侧的使用流程(先 chub --help、再 chub search、后 chub get <id> --lang py、最后用 chub annotate 记录坑点、chub feedback 反馈质量)见 get-api-docs 技能。本仓库 README(README.md)的定位是「给编码 Agent 提供精选、版本化的文档,让 Agent 每次任务都能更聪明」,本文即属于这类为 Agent 与开发者准备的精选技术文档之一。
官方参考资源
如需进一步查阅,可访问以下官方资源(均可在 Google Cloud 官方站点找到):
- PyPI 包页面:
google-cloud-dataproc-metastore; - Python 客户端参考根页面:Cloud 官方 Python 参考文档中 metastore 的
latest版本页; DataprocMetastoreClient类参考:google.cloud.metastore_v1.services.dataproc_metastore_service.DataprocMetastoreClient;- 包源码树与生成类型源码(
google/cloud/metastore_v1/types/metastore.py):位于googleapis/google-cloud-python仓库的packages/google-cloud-dataproc-metastore目录; - Google Cloud 客户端库认证指南:Application Default Credentials 与客户端库认证章节。
注意:官方参考站点的部分页面存在版本标签滞后,判断版本行为差异时应以 PyPI 包版本与本文档 frontmatter 中的 versions: 1.21.0 为准。