17370845950

GCS XML API 是遗留接口，需手动构造HMAC-SHA256签名的PUT请求，仅支持完整上传、无分块重试，官方库已移除支持；推荐改用JSON API上传XML文件并设置Content-Type。

用 REST API 上传 XML 格式文件到 GCS 需要手动构造签名请求

Google Cloud Storage 的 XML API 是遗留接口，不推荐新项目使用，但某些旧系统或合规场景仍需调用。它要求你手动构造 Authorization 头（基于 HMAC-SHA256 签名），且只支持 PUT 请求上传对象，不走 OAuth2。

• 必须使用服务账号的私钥（.p12 或 .json）生成签名，不能复用 OAuth2 token
• 请求 URL 必须是 https://storage.googleapis.com//，不能带查询参数
• Content-Type 必须显式设置，否则 GCS 可能拒绝或误判 MIME 类型
• 时间戳用 Date 头（RFC 2822 格式），不是 X-Goog-Date

PUT /my-bucket/report.xml HTTP/1.1
Host: storage.googleapis.com
Date: Wed, 12 Jun 2025 14:23:15 GMT
Authorization: GOOG1 KEY_ID:BASE64_SIGNATURE
Content-Type: application/xml
Content-Length: 1234

data

Python 客户端库默认走 JSON API，XML API 需降级并手动配置

官方 google-cloud-storage 库（v2+）完全移除了 XML API 支持，只对接 JSON API 和 gRPC。若硬要走 XML 协议，只能用低层 HTTP 客户端（如 requests）自己封装，或回退到已弃用的 gsutil + boto 组合。

• 用 gsutil 时可通过 -o "GSUtil:prefer_api=xml" 强制走 XML，但仅限命令行，无法嵌入 Python 逻辑
• boto 库（非 Google 官方）支持 XML，但需手动配置 gs_conn 并指定 provider 为 google，且已多年无维护
• 新版 google-auth 不提供 HMAC 签名工具，得用 cryptography 或 pyopenssl 自己实现

上传大 XML 文件时，XML API 不支持分块上传或断点续传

XML API 的 PUT Object 是单次完整上传，没有 POST 分片接口（不像 JSON API 的 resumable upload）。这意味着：

• 内存需一次性加载整个 XML 内容，100MB+ 文件容易触发 OOM
• 网络中断即失败，重试必须从头开始，无 upload_id 或 upload_url



• 无法设置 Content-MD5 校验（虽可加 header，但 GCS XML API 实际不校验）

替代方案：改用 JSON API 的 resumable upload，哪怕内容是 XML，GCS 只认 Content-Type，不解析结构。

客户端库里“上传 XML”实际只是设 Content-Type，和协议无关

很多开发者误以为用 blob.upload_from_string(..., content_type="application/xml") 就在走 XML API —— 其实不然。该调用走的是 JSON API，只是告诉 GCS 这个对象的 MIME 类型是 XML。GCS 存储后，下载时会返回正确的 Content-Type，但上传过程仍是 JSON over HTTPS。

• 所有 Python/Node.js/Java 官方库的 upload 方法，默认且唯一使用 JSON API
• XML API 仅在你显式拼接 HTTP 请求、手算签名、发原始 PUT 时才生效
• 控制台、gsutil cp、gcloud storage cp 默认也走 JSON API，除非显式指定 --api=xml（gsutil）

真正需要 XML API 的场景极少，多数时候只是想存一个 XML 文件——直接用客户端库上传，设对 content_type 就够了。强行走 XML 协议只会增加签名、时钟同步、调试难度，还失去自动重试和流式上传能力。