Skip to main content
Square Cloud API 是基于 HTTPS 的 REST API,覆盖你在控制台中完成的操作:部署和控制应用、读取应用的日志和指标,以及管理文件、环境变量、快照、数据库和 workspace。它以 JSON 收发数据,但有两个例外:上传和提交以 multipart/form-data 接收 zip 文件,实时日志则以 Server-Sent Events 推送数据。

基础 URL

本参考中的每个端点都相对于:
Blob Storage 是一个独立的 API,拥有自己的基础 URL https://blob.squarecloud.app/v1,并使用同一个 API 密钥。

身份验证

在账户安全设置中创建 API 密钥,并在每个请求的 Authorization 请求头中发送。Bearer 前缀是可选的。
密钥只会在创建时显示一次。请将其保存在服务器上的环境变量中,切勿放进客户端代码或代码仓库。每个密钥都带有限制其操作范围的权限范围:各端点所需的权限范围见身份验证。

第一个请求

账户信息会返回你的个人资料、套餐,以及你拥有的所有应用和数据库。它需要具有 account:read 权限范围的密钥。
如果收到 401 ACCESS_DENIED,说明密钥缺失或无法识别。如果收到 403 MISSING_SCOPE,说明密钥有效,但缺少 account:read。

响应格式

调用成功时返回 2xx 和 "status": "success",如果有数据需要返回,则放在 response 中:
启动或停止等操作只返回 { "status": "success" }。调用失败时返回 4xx 或 5xx、"status": "error",以及可用于分支处理的 code:
响应中的字段名使用 snake_case。所有错误代码及其处理方式见错误代码。

ID

  • 应用和数据库使用 32 位十六进制 ID,例如 a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d。可以从账户信息或控制台中该资源的地址获取。
  • 通过 workspace 与你共享的应用在路径中写作 <appId>-<workspaceId>,例如 /v2/apps/<appId>-<workspaceId>/status。
  • workspace 使用 32 位十六进制 ID。较早创建的 workspace 保留 40 位的 ID。

限制

每个账户每 60 秒有一定的请求额度,由套餐决定;部分端点另有自己的限制,会在其页面中注明。具体数值见限制与约束,429 的工作方式见错误代码。

OpenAPI 规范

整个 API 都由一份 OpenAPI 文档描述,地址为 https://api.squarecloud.app/v2/openapi.json。你可以将其导入 Postman 或 Insomnia,或用它生成客户端。
更喜欢类型化的客户端?适用于 JavaScript、Python 和 Go 的 Square Cloud SDK 封装了本参考中的每个端点,CLI 则可在终端中完成相同的任务。

后续步骤

身份验证与权限范围

为每个集成挑选所需的权限范围。

错误代码

API 返回的所有代码及处理方式。

上传应用

一个请求即可部署 zip 文件。

速率限制

各套餐的请求额度。