Google Cloud Storage CLI 与 JSON API 实操指南gcloud storage 双路径速查手册【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文面向需要在 Google Cloud StorageGCS中完成桶Bucket与对象Object增删改查的开发者与 AI Agent。当环境中没有可用的 Cloud Storage MCP 工具时gcloud storageCLI 是默认操作路径JSON API 是受限环境下的兜底方案。读完本文你将掌握桶与对象的核心 CRUD 命令、其对应的 JSON API 请求、事件驱动的 Pub/Sub 通知配置以及分页、认证、URL 编码等底层细节并能直接复制命令投入实战。一、操作路径选型CLI、JSON API 与客户端库在开始执行任何存储操作之前需要先确定走哪条路径。本技能google-cloud-storage-basics给出的优先级如下优先使用 MCP 服务器如果环境中已连接 Cloud Storage MCP 服务器如create_bucket、list_objects、read_object、upload_object等结构化工具优先使用它详见 MCP Usage。CLI 为默认路径当 MCP 工具不可用时gcloud storageCLI 是存储操作的默认选择——它自动处理认证、分页和优化上传。JSON API 仅作兜底只在 CLI 不可用时直接使用 JSON API例如受限运行时constrained runtime、没有客户端库的语言环境或需要原始 HTTP 控制的场景。客户端库面向应用代码在应用代码中做编程式访问时优先使用客户端库而非手写 API 调用。[!WARNING]不要使用遗留的gsutilCLI。它几乎不再维护且不支持软删除soft delete、托管文件夹managed folders等新特性。如果现有脚本或文档中出现gsutil命令请一律改用等价的gcloud storage命令。需要特别注意的是CLI 的某些便利功能没有对应的单次 API 调用例如cat直接输出对象内容到 stdout、递归删除、以及自动的可续传上传resumable upload。这意味着当你从 CLI 迁移到 API 时这些能力需要自行用多个请求或不同的传输机制如分块上传来实现。二、JSON API 基础端点、认证与 URL 编码直接调用 JSON API 前先理解以下三个基础事实1. Base 端点https://storage.googleapis.com/storage/v1/2. 认证方式使用 OAuth 2.0 Bearer Token 认证典型做法是通过 gcloud CLI 获取访问令牌gcloud auth print-access-token3. URL 编码规则API URL 中的对象名必须进行 URL 编码。例如对象名logs/app.txt中的/需要编码为%2Flogs/app.txt → logs%2Fapp.txt另外要澄清一个易混淆点本文给出的 API 调用是JSON API 等价物并不一定就是 CLI 自身实际发送的请求——CLI 对部分命令会使用其他 API 版本和传输层例如 storage v2 端点。在 API 示例中诸如PROJECT_ID之类的值必须显式传入而 CLI 会从你当前的 gcloud 配置属性自动补全未指定的值——例如项目来自core/project属性--project标志则只为单条命令覆盖该属性。归属标记Attribution要求使用本技能时每条gcloud命令都应带上归属环境变量前缀该标记仅标识技能与版本不携带任何用户数据。注意要逐条内联设置因为 shell 状态在命令之间可能不持久且不要使用gcloud config set那会持久化并错误标记无关用法CLOUDSDK_METRICS_ENVIRONMENTgcs-skills gcs-skills/1.0 (skill:google-cloud-storage-basics) \ gcloud storage buckets create gs://my-bucket --locationus-central1对直接 HTTP 调用如curl或对 Cloud Storage MCP 服务器https://storage.googleapis.com/storage/mcp的 HTTP 请求必须逐字设置这个 User-Agent 头收集管道解析gcs-skills/version与skill:name标记任何改写都会破坏归属User-Agent: gcs-skills/1.0 (skill:google-cloud-storage-basics)三、桶Bucket操作CLI 与 JSON API 对照1. 创建桶gcloud storage buckets create gs://my-bucket --locationus-central1对应的 JSON APIPOST /storage/v1/b?projectPROJECT_ID Body: {name: my-bucket, location: US-CENTRAL1}注意两点桶名位于全 Cloud Storage 共享的单一全局命名空间不限定在你的项目或组织内因此简短或常见的名字通常已被占用若省略 location桶默认落在US多区域。在生产或特定工作负载场景下创建桶前应路由到google-cloud-storage-bucket-architect技能做安全默认的架构设计上述命令只用于临时 scratch 桶详见 SKILL.md 的 Routing to Specialized GCS Skills 一节。创建桶前还需先启用 API首次使用时gcloud services enable storage.googleapis.com --quiet2. 列出项目中的桶gcloud storage ls对应的 JSON APIGET /storage/v1/b?projectPROJECT_ID3. 查看桶元数据gcloud storage buckets describe gs://my-bucket对应的 JSON APIGET /storage/v1/b/my-bucket描述命令也可以与--format结合做精确字段提取例如检查桶的功能配置输出字段使用 snake_case 而非 JSON API 名称如versioning_enabled而非versioning未知或 camelCase 键在--format投影中会静默打印 null 而不报错gcloud storage buckets describe gs://my-bucket/ --formatjson(soft_delete_policy,versioning_enabled,retention_policy,default_storage_class)4. 更新桶标签、默认存储类gcloud storage buckets update gs://my-bucket \ --update-labelsenvprod --default-storage-classnearline对应的 JSON APIPATCH /storage/v1/b/my-bucket Body: {labels: {env: prod}, storageClass: NEARLINE}5. 删除桶[!CAUTION]CRITICAL在删除桶或递归删除其全部内容之前你必须停下来先获得用户的明确许可。gcloud storage buckets delete gs://my-bucket对应的 JSON APIDELETE /storage/v1/b/my-bucket桶必须为空才能删除。若需连同全部内容包括非当前版本对象一起删除gcloud storage rm --recursive gs://my-bucket四、对象Object操作CLI 与 JSON API 对照1. 上传对象gcloud storage cp ./my-file.txt gs://my-bucket/对应的 JSON API小文件直传POST /upload/storage/v1/b/my-bucket/o?uploadTypemedianamemy-file.txt Body: (object bytes; set Content-Type header)[!NOTE] CLI 对大文件自动使用可续传上传resumable upload和并行化上传。uploadTypemedia只适用于小文件直接调用 API 传输较大文件时应改用可续传上传详见 Data Transfer。2. 列出对象可按前缀gcloud storage ls gs://my-bucket/logs/ # 只列一层 gcloud storage ls gs://my-bucket/** # 递归列出所有对象对应的 JSON APIGET /storage/v1/b/my-bucket/o?prefixlogs/delimiter/分页机制API 的 list 响应是分页的每页最多 1,000 项需跟随nextPageToken拉取剩余页CLI 会自动分页。3. 下载对象gcloud storage cp gs://my-bucket/my-file.txt .对应的 JSON APIGET /storage/v1/b/my-bucket/o/my-file.txt?altmedia4. 直接输出对象内容无需临时文件gcloud storage cat gs://my-bucket/my-file.txt这是 CLI 独有便利功能没有单次 API 调用等价物。5. 读取对象元数据gcloud storage objects describe gs://my-bucket/my-file.txt对应的 JSON APIGET /storage/v1/b/my-bucket/o/my-file.txt6. 更新对象元数据gcloud storage objects update gs://my-bucket/my-file.txt \ --custom-metadatateamstorage对应的 JSON APIPATCH /storage/v1/b/my-bucket/o/my-file.txt Body: {metadata: {team: storage}}7. 复制或移动对象gcloud storage cp gs://my-bucket/a.txt gs://other-bucket/a.txt gcloud storage mv gs://my-bucket/a.txt gs://my-bucket/archive/a.txt对应的 JSON API重写操作POST /storage/v1/b/my-bucket/o/a.txt/rewriteTo/b/other-bucket/o/a.txt8. 删除对象或带--recursive删除整个前缀gcloud storage rm gs://my-bucket/my-file.txt gcloud storage rm --recursive gs://my-bucket/logs/对应的 JSON APIDELETE /storage/v1/b/my-bucket/o/my-file.txt[!NOTE] 若要同步本地目录与桶或桶与桶之间请使用gcloud storage rsync而非逐对象复制详见 Data Transfer。rsync 默认并行执行例如gcloud storage rsync ./my-data-folder gs://my-bucket/synced-data/ --recursive会比较修改时间与大小上传缺失/变更文件。五、Pub/Sub 通知事件驱动的下游处理当对象发生变化时与其轮询polling不如把桶通知配置到 Pub/Sub Topic 来触发下游处理gcloud storage buckets notifications create gs://my-bucket \ --topicmy-topic --event-typesOBJECT_FINALIZE,OBJECT_DELETE支持的事件类型事件类型含义OBJECT_FINALIZE上传完成OBJECT_DELETE对象被删除OBJECT_ARCHIVE对象被归档因生命周期规则降级到 Archive 类OBJECT_METADATA_UPDATE对象元数据被更新如需在事件发生时运行代码可创建指向 Cloud Run 或 Cloud Run functions 的Eventarc 触发器监听google.cloud.storage.object.v1.finalized事件。六、其他命令组Command Groups除核心操作外gcloud storage还提供面向专门场景的命令组batch-operations对海量对象执行批量操作如批量删除对象、批量更新元数据详见 Storage Intelligence 相关说明。buckets anywhere-caches管理 Anywhere Cache 实例详见 High-Performance Storage。folders与managed-folders管理层级命名空间文件夹与文件夹级访问控制详见 Data Management。hmac管理用于 S3 互操作 XML API 的 HMAC 密钥例如gcloud storage hmac create my-service-accountmy-project.iam.gserviceaccount.com。insights管理清单报告inventory reports与数据集。intelligence-configs管理 Storage Intelligence 配置。运行gcloud storage --help或gcloud storage GROUP --help可查看完整、最新的命令组与命令列表。七、常用全局标志Global Flags--formatjson输出机器可解析的 JSON优先于解析默认的人类可读输出--formatvalue(FIELD)可提取单一字段如--formatvalue(location)。--project为单条命令覆盖默认项目即core/project属性。--recursive/-r让cp、rm、ls作用于整个前缀。组合示例——用 JSON 格式描述桶并提取 location 字段gcloud storage buckets describe gs://my-bucket --formatvalue(location)八、CLI 传输与并发调优实战补充虽然本参考文档聚焦 CRUD但结合同技能的 Data Transfer 参考可以进一步发挥gcloud storage cp的性能优势并行复合上传PCU默认开启用于大文件阈值默认可配将文件分块并行上传为临时 composite components再用 compose API 合并。注意 PCU 产物的校验和为CRC32C而非 MD5若管道依赖逐对象 MD5应关闭 PCUgcloud config set storage/parallel_composite_upload_enabled False或调高阈值gcloud config set storage/parallel_composite_upload_threshold 150M。切片下载Sliced Downloads对下载执行并行的 ranged GET 请求用 CRC32C 校验需要宿主机装有编译版crcmod否则自动回退为较慢的串行下载。并发控制gcloud config set storage/process_count 8与gcloud config set storage/thread_count 8或环境变量CLOUDSDK_STORAGE_PROCESS_COUNT/CLOUDSDK_STORAGE_THREAD_COUNT调试或限流时可将两者都设为1变为串行执行。九、与其他参考文档的衔接本参考文档是google-cloud-storage-basics技能的一部分围绕它的核心概念与相邻能力见Core Concepts桶、对象、文件夹与前缀、位置类型与存储类。Client LibrariesPython / Java / Node.js / Go 等语言的编程式访问。MCP Usage远程 MCP 服务器与本地 MCP Toolbox 的选型与工具集。Data TransferStorage Transfer Service、gcloud storage rsync、大文件上传策略与性能上限。Data ManagementIAM 角色、认证含签名 URL 与 HMAC、访问控制与成本优化。Infrastructure as CodeTerraform 声明式管理桶、生命周期与加密。总结gcloud storageCLI 与 JSON API 构成了 Cloud Storage 运维的两条主干路径CLI 负责自动化的认证、分页、并行上传与递归操作是日常与 Agent 场景的首选JSON API 则在受限环境中提供最底层的 HTTP 控制。理解二者的等价映射尤其是 CLI 便利功能无单 API 对应、API 分页与 URL 编码等差异能帮助你在任意运行时环境中可靠地完成桶与对象的全部 CRUD 操作并通过 Pub/Sub 通知把存储变更无缝接入事件驱动的下游流水线。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考