选择语言并安装
四个官方包:三个用于 Square Cloud API,一个用于 Blob Storage。每个包只需要对应语言的运行时。
JavaScript 和 TypeScript
@squarecloud/api
Node.js 22+、Deno、Bun 和边缘运行时
npm install @squarecloud/apiPython
squarecloud-api
Python 3.11+,提供同步和异步客户端
pip install squarecloud-apiGo
github.com/squarecloudofc/sdk-api-go/v3
Go 1.22+,每次调用都接受 context
go get github.com/squarecloudofc/sdk-api-go/v3Blob Storage
@squarecloud/blob
Node.js 20+ 和浏览器
npm install @squarecloud/blob
第一次调用
创建一个 API 密钥,将其设为 SQUARECLOUD_API_KEY 环境变量,然后运行下面任意一个程序。程序会输出你的名字,以及该密钥可以看到多少个应用。
import { SquareCloudAPI } from "@squarecloud/api";const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);const { user, applications } = await api.account.me();console.log(`Hi ${user.name}, you have ${applications.length} apps`);import osfrom squarecloud import SquareCloudwith SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client: me = client.account.me() print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps")package mainimport ( "context" "fmt" "log" "os" "github.com/squarecloudofc/sdk-api-go/v3")func main() { c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY")) me, err := c.Account.Me(context.Background()) if err != nil { log.Fatal(err) } fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications))}API 能做的一切,都能在代码中完成
JavaScript、Python 和 Go SDK 覆盖 API 参考中的所有操作,每次 CI 运行都会对照其 OpenAPI 规范进行检查。下方的方法名以 JavaScript 为例,Python 使用 snake_case,Go 使用 PascalCase。
应用
查看单个或全部应用的状态,启动、停止和重启应用,并获取日志以及 CPU、内存和网络指标。
apps.statusAllapps.restartapps.logsapps.metrics部署
从 zip 创建应用,向其提交新文件,关联 GitHub 仓库和分支或设置 Webhook,并列出过往部署。
apps.createapps.commitdeploys.linkGithubApp文件与变量
列出、读取、写入、移动和删除应用的文件,并获取、设置或替换其环境变量。
files.writefiles.readenvs.set实时
以可循环遍历的迭代器实时跟踪应用的日志和状态。连接中断后会自动重新建立。
apps.realtime快照
为应用和数据库创建、列出并恢复快照,还能以流的方式下载快照文件。
snapshots.createsnapshots.restoredownloadSnapshot网络
设置自定义域名,读取其 DNS 记录,清除缓存,并按时间范围查询分析、错误和性能数据。
network.setDomainnetwork.purgeCachenetwork.analytics数据库
创建 MongoDB、PostgreSQL、MySQL 和 Redis 数据库,调整内存,查看状态,并重置密码或证书。
databases.createdatabases.resetCredentials工作区
创建工作区,通过邀请码添加成员,更改成员的分组,并与团队共享应用。
workspaces.members.addworkspaces.apps.addAI
使用同一个客户端和同一个密钥,向 Square Cloud AI Gateway 发送兼容 OpenAI 的聊天请求。
ai.chat
在 JavaScript 中使用 Blob Storage
@squarecloud/blob 是 Blob Storage 的 SDK:上传、私有文件、分享链接、文件夹规则以及兼容 S3 的网关,可在 Node.js 和浏览器中使用。 了解 Blob Storage
大文件上传
传入文件路径、Blob 或字节即可。大文件会从磁盘流式读取,分片并行上传,最大 10 GiB。
putlist私有文件
私有文件没有公开 URL。你可以创建会过期的下载链接,或随时可撤销的分享链接。
downloadUrlshares.createshares.revoke从浏览器上传
由你的服务器创建短时有效的上传令牌,浏览器用它上传,API 密钥始终不会离开你的服务器。
uploadTokens.create
每种语言,同样的构建方式
零依赖
每个 SDK 只使用其语言的标准库或平台自带的 fetch,不会往你的锁文件里添加任何其他内容。
统一的错误类型
所有 API、网络和本地错误都抛出同一个错误类,并附带 HTTP 状态码和 API 的错误代码。
安全的重试
每次尝试 30 秒超时,只对可以安全重复的失败进行重试,遇到 429 绝不重试。
限定范围的密钥
密钥可以只授予部分权限,并限定到特定的应用或数据库。列表只返回该密钥能看到的内容。
工具箱里的其他工具
同一个 API 密钥和同一个 SQUARECLOUD_API_KEY 变量,可以在终端、CI、编辑器和代码中通用。
项目每个阶段都有合适的套餐
从小规模开始,按需扩展,无绑定合约。
4.9 分(满分 5 分)· Google + Trustpilot 上的 402 条评价Trustpilot
关于 SDK 的常见问题
哪些语言有官方的 Square Cloud SDK?
JavaScript 和 TypeScript(@squarecloud/api)、Python(squarecloud-api)以及 Go(github.com/squarecloudofc/sdk-api-go)。Blob Storage 有单独的 JavaScript SDK:@squarecloud/blob。四个 SDK 都在 GitHub 上开源。
SDK 覆盖整个 API 吗?
是的。JavaScript、Python 和 Go SDK 覆盖 Square Cloud API 参考中的所有操作,外加快照下载,并在每次 CI 运行时对照其 OpenAPI 规范进行检查。Blob Storage 及其兼容 S3 的网关由 @squarecloud/blob 提供支持。
使用 SDK 需要哪个套餐?
SDK 本身是开源包。它们调用的 API 包含在 Square Cloud 的所有套餐中,从 Hobby 起即可使用,每分钟的请求数取决于套餐。
API 密钥应该存放在哪里?
放在 SQUARECLOUD_API_KEY 环境变量中,切勿写进源代码。每个密钥只授予它所需的权限和资源;一旦泄露,请在账户的安全设置中将其撤销。
可以在浏览器中使用 SDK 吗?
API SDK 面向服务器:Node.js、Deno、Bun、边缘运行时、Python 和 Go。在浏览器中使用会暴露 API 密钥。如需从浏览器上传,@squarecloud/blob 会使用由你的服务器创建的短时上传令牌。
我在用旧版本,有哪些变化?
当前版本经过重写:方法挂在客户端上,响应是使用 API 原有字段名的纯数据,所有失败都只有一种错误类型。每个 SDK 的文档都提供从上一个主版本迁移的指南。
SDK、CLI 还是 GitHub Action,该用哪个?
调用写在代码里时用 SDK,比如重启应用的机器人命令,或创建快照的脚本。在终端中用 CLI,每次推送都要部署时用 GitHub Action。