一套 公开 API JSON 接口让软件通过 HTTP 请求和响应交换结构化数据。Capgo 的类型化 RESTful API 让 CapacitorJS 和 Electron 团队能以编程方式控制实时更新、频道、bundle 和设备分发。
目录
了解 Capgo 公开 API JSON 基础
Capgo 并非通用数据目录。其公开的 API JSON 接口将你的构建系统与 Capgo 的云分发服务连接起来，让发布自动化可以发布并定向分发已签名的 Web bundle，无需等待 App Store 或 Play 审核。REST 使用常见的 HTTP 方法，例如 GET、POST、PUT、PATCH 和 DELETE，JSON 通常作为响应格式，详见这篇 Postman 的 REST API 指南.
对 Capgo 来说，JSON 是自动化脚本、CI/CD 任务、TypeScript 客户端与分发平台之间的共同语言。这种一致性让 payload 在日志中更易读，也更容易在部署开始前验证。
接口控制的内容
使用公开的 API JSON 端点来管理运营发布资源，包括：
- Bundle，即构成可部署更新的 Web 资产和元数据。
- 通道，例如 staging、beta、production 或特定客户的发布流。
- 版本，用于识别和跟踪分配给这些渠道的构建。
- 设备定向，帮助将发布定向到选定的平台、应用版本、操作系统或元数据组。
- 可观测性数据，包括采用率、失败情况、回滚活动以及每台设备的状态。
典型的请求遵循可预测的顺序。您的 pipeline 创建或准备一个 bundle，向 Capgo 发送 JSON 元数据，检查返回的状态，然后将发布分配给合适的渠道。后续的查询可以确认哪些设备接收了更新。
核心思路： 将 Capgo JSON 视为发布控制契约，而不仅仅是数据格式。每个字段都应支持应用的发布、定向、监控或恢复更新。
类型化 JSON 的好处
类型化负载可减少 TypeScript 代码库中的歧义。版本标识符应保持为字符串，灰度发布标志应保持为布尔值，设备数量应保持为数字。在连接自动化之前，先定义请求和响应的接口，然后验证必填字段和可空值。
延伸阅读： 了解如何在 API 中使用 TypeScript.
在每个集成中保持以下三个习惯：
- 同时检查状态码和响应体，因为仅凭 HTTP 成功可能无法描述部署是否完成。
- 保留返回的标识符，特别是 bundle、版本和 channel ID，以便后续调用。
- 安全记录日志，不包括 API 键和敏感设备数据。
以下参考章节基于此基础，解释身份验证、上传负载、通道架构、目标查询和错误对象。有关当前的端点名称和字段定义，请在以下位置查看 Capgo 的文档： capgo.app.
{\n“authorization”: “Bearer YOUR_CAPGO_API_KEY”,\n“contentType”: “application/json”,\n“accept”: “application/json”\n}
{ “success”: true, “bundleId”: “com.example.field-app”, “version”: “2.4.0”, “status”: “uploaded”, “bundleUuid”: “generated-bundle-identifier”, “createdAt”: “2026-01-15T10:30:00Z” }
{\n“defaultVersion”: “2.4.3”,\n“autoUpdate”: true,\n“rollbackProtection”: {\n“enabled”: true,\n“fallbackVersion”: “2.4.2”\n}\n}
{ “data”: [ { “timestamp”: “2026-02-04T09:00:00Z”, “installs”: 842, “rollbacks”: 3, “errors”: 11 }, { “timestamp”: “2026-02-04T10:00:00Z”, “installs”: 1276, “rollbacks”: 2, “errors”: 8 } ], “summary”: { “totalInstalls”: 2118, “totalRollbacks”: 5, “totalErrors”: 19 } }
{ “error”: { “code”: “INVALID_PARAMETER”, “message”: “缺少 ‘version’ 字段”, “field”: “version”, “details”: { “expected”: “string”, “received”: “null” } } }
{ “version”: “2.4.0”, “checksum”: “sha256-value”, “encryption”: true, “externalUrl”: “https://storage.example/bundle.zip}” }
