google-cloud-dataproc-metastore Python 客户端实战指南:管理 Dataproc Metastore 服务、元数据导入与备份恢复

原创2026-10-10 21:07:041,902 阅读

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 部分列出了开发中最容易踩的六个坑,逐条对照可显著减少调试时间:

  1. 不要用 API key 认证:本包只接受 Google Cloud 凭据(ADC / 服务账号),传 API key 必然失败;
  2. 不要混淆管理 SDK 与直接 Hive 访问:该库管理服务和运维操作,不是直接连 Hive 端点的 SQL 客户端;
  3. 不要传裸网络名:Service.network 需要完整 VPC 资源路径,如 projects/your-project/global/networks/default,传 default 会报错;
  4. 不要假设创建是瞬时的:必须先等待返回的 operation,再使用服务端点;
  5. 不要把元数据导入指向本地文件:MetadataImport.DatabaseDump.gcs_uri 必须是 Cloud Storage 的 gs:// URI;
  6. 不要假设所有 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 为准。

登录后查看全文
context-hub