JavaScript、Python 和 Go 官方 SDK

选择你的 SDK

所有 SDK 均为开源，可在 GitHub 上获取。它们没有任何运行时依赖，并原样返回 API 自身的数据，包括字段名。

JavaScript

@squarecloud/api v6。应用、数据库、workspace、deploy、网络、实时、snapshot 和 AI，支持 Node.js、Deno、Bun 以及边缘运行时。

Python

squarecloud-api v5。覆盖范围相同，提供同步和异步客户端，仅使用标准库。

Go

sdk-api-go v3。覆盖范围相同，每次调用都带有 context，且只有一种错误类型。

Blob Storage (JavaScript)

@squarecloud/blob v4。最大 10 GiB 的上传、私有对象、链接、分享、规则以及 S3 网关，支持 Node.js 和浏览器。

概览

SDK	包	版本	运行环境	安装
JavaScript	`@squarecloud/api`	6.0.0	Node.js 22+、Deno、Bun、边缘运行时	`npm install @squarecloud/api`
Python	`squarecloud-api`（导入名 `squarecloud`）	5.0.0	Python 3.11+	`pip install squarecloud-api`
Go	`github.com/squarecloudofc/sdk-api-go/v3`	3.0.0	Go 1.22+	`go get github.com/squarecloudofc/sdk-api-go/v3`
Blob Storage	`@squarecloud/blob`	4.0.0	Node.js 20+ 和浏览器	`npm install @squarecloud/blob`

快速开始

几分钟内即可完成第一次调用。下面的每个程序都会打印你的账户名称，以及你的 API 密钥可以看到的应用数量。

创建 API 密钥

在账户安全设置中创建密钥。像对待密码一样对待它：不要把它写进源代码。

设置 SQUARECLOUD_API_KEY 环境变量

示例从 SQUARECLOUD_API_KEY 读取密钥。请在运行示例的终端中设置它：

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

安装 SDK 并完成第一次调用

JavaScript
Python
Go

npm install @squarecloud/api

index.mjs

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`);

node index.mjs

pip install squarecloud-api

main.py

import os

from squarecloud import SquareCloud

with SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client:
    me = client.account.me()
    print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps")

python main.py

go mod init example.com/hello
go get github.com/squarecloudofc/sdk-api-go/v3

main.go

package main

import (
	"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))
}

go run .

检查输出

程序会打印你的账户名称，以及该密钥可以看到的应用数量：

Hi Jane, you have 3 apps

如果出现 401 ACCESS_DENIED 错误，说明密钥有误、已吊销或已过期。如果没有设置该变量，程序会在发送任何请求之前停止。

各 SDK 的覆盖范围

JavaScript、Python 和 Go SDK 覆盖了完整的 Square Cloud API：相同的 67 个操作，外加 snapshot 文件的下载。它们拥有相同的页面结构、相同的示例和相同的行为：

一个错误类，包含 HTTP 状态码和 API 的错误代码；
30 秒超时，对于服务器保持连接的调用至少为 120 秒；
仅对可以安全重复的失败进行重试，429 永不重试；
使用 <appId>-<workspaceId> 形式的 ID 来操作通过 workspace 共享的应用。

Blob Storage SDK 覆盖 Blob API 和 S3 网关。它是一个独立的包，拥有自己的客户端、凭据和错误代码。

错误参考

每个 SDK 的错误页面介绍其错误类、重试和速率限制。错误代码本身来自 API：API 错误参考列出了所有错误代码，Blob API 错误参考列出了 Blob Storage 的错误代码。

SDK	错误、重试和速率限制
JavaScript	`SquareCloudAPIError`
Python	`SquareCloudAPIError`
Go	`*APIError`
Blob Storage	`SquareCloudBlobError`

升级

上面每个 API SDK 版本都是一次重写。请参阅迁移指南：JavaScript v5 → v6、Python v4 → v5、Go v2 → v3 和 Blob v3 → v4。 Square Cloud 持续改进其 SDK 并添加新语言。如果缺少你使用的语言，请告诉我们。

后续步骤

API 简介

用 curl 直接调用 REST API。

CLI 快速开始

在终端中部署和管理应用。

Blob API 快速入门

用 curl 向 Blob Storage 上传文件。

CLI

VS Code

SDKs

JavaScript、Python 和 Go 官方 SDK

选择你的 SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

概览

快速开始

各 SDK 的覆盖范围

错误参考

升级

后续步骤

API 简介

CLI 快速开始

Blob API 快速入门

​选择你的 SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

​概览

​快速开始

​各 SDK 的覆盖范围

​错误参考

​升级

​后续步骤

API 简介

CLI 快速开始

Blob API 快速入门

选择你的 SDK

概览

快速开始

各 SDK 的覆盖范围

错误参考

升级

后续步骤