Python SDK：快速上手与客户端

本页记录的是 squarecloud-api 5.0，这是 SDK 的一次重写。正从 v4 升级？请阅读 v4 → v5 迁移指南。

要求

Python 3.11 或更新版本。
一个 API 密钥（参见 API 密钥与作用域）。

该包没有运行时依赖（仅使用标准库：http.client、json、ssl），并且带有完整类型（py.typed）：响应是你的编辑器和类型检查器都能理解的 TypedDict。

安装

pip
uv
poetry

pip install squarecloud-api

uv add squarecloud-api

poetry add squarecloud-api

该包以 squarecloud-api 的名称安装，以 squarecloud 的名称导入。已安装的版本为 squarecloud.__version__。

API 密钥与作用域

在 squarecloud.app/account/security 创建密钥。SDK 会将其原样放入 Authorization 请求头发送（不带 Bearer 前缀）。密钥可以限制为特定的作用域（apps:read、apps:deploy、apps:control、ai:chat……）以及特定的应用或数据库：

超出这些限制的调用会抛出 SquareCloudAPIError，状态为 403，代码为 MISSING_SCOPE 或 RESOURCE_NOT_ALLOWED。
列表方法（account.me()、apps.status_all()……）只返回该密钥可见的资源。
未知、已撤销或已过期的密钥会返回 401 ACCESS_DENIED。

不要把密钥写在源代码中：请从环境变量（os.environ["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 提供两个客户端，拥有相同的分组和方法：

SquareCloud 是同步的，并且是线程安全的：可以在多个线程之间共享同一个实例。每个线程会复用自己的 keep-alive 连接。
AsyncSquareCloud 是相同的 API，只是需要 await。每次调用都会在 asyncio.to_thread 中运行同步客户端，因此事件循环永远不会被阻塞。

同步
异步

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")

import asyncio
import os

from squarecloud import AsyncSquareCloud


async def main() -> None:
    async with AsyncSquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client:
        me = await client.account.me()
        print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps")


asyncio.run(main())

两个示例都会打印你的账户名称，以及该密钥可以看到的应用数量：

Hi Jane, you have 3 apps

离开 with / async with 代码块时会关闭连接池中的连接。如果不使用代码块，请在用完后调用 client.close()。close() 在两个客户端上都是普通的（同步）方法。空密钥或仅含空白字符的密钥会在构造函数中抛出 ValueError，早于任何请求。

异步客户端

AsyncSquareCloud 与 SquareCloud 只有三处不同：

每个方法都返回一个协程：await client.apps.status(app_id)。
close() 是同步的：调用时不要加 await。
apps.realtime(app_id) 不需要 await：它返回一个 AsyncRealtime，你可以用 async for 来消费它（参见实时）。

由于每次调用都在工作线程中运行，你可以使用 asyncio.gather 并发执行多个调用：

apps, databases = await asyncio.gather(
    client.apps.status_all(),
    client.databases.status_all(),
)

取消一个正在等待的任务并不会停止已在其工作线程中运行的请求：该调用仍会在后台完成（或超时）。

选项

import os

from squarecloud import BASE_URL, SquareCloud

client = SquareCloud(
    os.environ["SQUARECLOUD_API_KEY"],
    base_url=BASE_URL,  # "https://api.squarecloud.app/v2" (default)
    timeout=30.0,
    max_retries=2,
    user_agent="my-bot/1.0",
    transport=None,  # a custom transport (proxy, tracing, tests)
)

这些选项只能以关键字形式传入，AsyncSquareCloud 接受相同的选项。

选项	默认值	说明
`base_url`	`https://api.squarecloud.app/v2`	API 基础 URL。末尾的 `/` 会被去除。也以 `BASE_URL` 导出。
`timeout`	`30.0`	每次套接字操作（连接以及每次读或写）的秒数，而不是整个请求的时长。参见超时。
`max_retries`	`2`	仅针对安全失败的重试次数（最多 3 次尝试）。负值视为 `0`。参见重试。
`user_agent`	`squarecloud-sdk-py/<version>`	替换整个 `User-Agent` 请求头。
`transport`	`HTTPTransport(timeout)`	用于代理、追踪或测试的自定义传输层。参见高级。

客户端只将密钥保存在其私有的请求头中：不存在 client.api_key 属性，SDK 的日志记录器也绝不会写出它。

模块

属性	涵盖内容	页面
`client.account`	`me()`、`snapshots(scope=)`	账户和 Snapshots
`client.service`	`status()`	平台状态
`client.apps`	获取、删除、状态、生命周期、日志、指标、域名、负载均衡器	管理应用
`client.apps.create` / `commit`	上传	Commit 与上传
`client.apps.files`	文件管理器	管理文件
`client.apps.envs`	环境变量	环境变量
`client.apps.deploys`	Webhook 和 GitHub App deploy	Deploys
`client.apps.network`	分析、日志、DNS、自定义域名、缓存	网络
`client.apps.realtime`	实时日志和状态	实时
`client.apps.snapshots` / `client.databases.snapshots` / `client.download_snapshot`	备份	Snapshots
`client.databases`	托管数据库	数据库
`client.workspaces`	Workspace、成员和共享应用	Workspaces
`client.ai`	`chat()`	AI

该包导出 SquareCloud、AsyncSquareCloud、SquareCloudAPIError、BASE_URL、HTTPTransport、Transport 和 Response 协议、Realtime、AsyncRealtime 以及 __version__。响应类型（App、RuntimeStats、Snapshot……）位于 squarecloud.types 中：

from squarecloud.types import App, Snapshot

约定

ID 在前，返回纯数据

每个方法都以资源 ID 作为第一个参数，并返回纯数据：每个响应都是一个 TypedDict，在运行时就是普通的 dict（没有类，没有缓存），因此 API 日后新增的字段也会被保留。字段名与 API 自身一致（created_at、version_id、lastModified、joinedAt、netIO……），因此 API 参考可直接适用。

变更操作返回 None，除非 API 返回数据（envs.*、deploys.set_webhook、deploys.link_github_app、databases.reset_credentials 以及各 create 方法）。
字符串结果绝不会是 None：当 API 未返回时为 ''。
列表一次调用即完整返回：没有分页。
可选修饰参数只能以关键字形式传入（status(app_id, raw=True)、commit(app_id, file, path="/src")）。唯一的例外是 files.list 的可选参数 path，它也可以按位置传入。

方法都是普通的绑定方法，因此你可以保存对它们的引用：

restart = client.apps.restart
logs = client.apps.logs

restart(app_id)
print(logs(app_id))

Workspace 应用

每个 app_id 也接受组合形式 <appId>-<workspaceId>，用于操作通过 workspace 与你共享的应用。workspaces.get() 和 workspaces.list() 返回原始 ID；组合 ID 需要你自行构建：

client.apps.restart(f"{app_id}-{workspace_id}")

ID 会被编码

URL 路径中的 ID 会进行百分号编码。空的、. 或 .. 的 ID 会到达不同的路由，因此会在发送任何内容之前于本地以 INVALID_ID（状态 0）失败。Workspace 路由则将 ID 放在请求体中发送：在那里，INVALID_ID（400）来自服务器。

日期

start 和 end 参数（参见网络）接受 ISO 8601 字符串（原样发送）或 datetime（以 UTC 发送）。naive（不带时区的）datetime 会被视为本地时间并转换为 UTC，因此建议使用带时区的 datetime（datetime.now(UTC)）。响应中的日期保持 API 发送时的原样（ISO 字符串，或在 API 使用时为 Unix 毫秒）。

超时

timeout 限制的是每次套接字操作：连接以及每一次读或写。一个持续发送数据的响应，其总耗时可能超过 timeout。

调用	超时
其他所有调用	每次套接字操作 `timeout`（30 秒）
服务器保持连接的调用：应用的 `start`/`stop`/`restart`、数据库的 `start`/`stop`、`databases.create`、snapshot 的 `create`/`restore`、`ai.chat`	至少 120 秒（更大的 `timeout` 优先）
上传（`apps.create`、`apps.commit`）以及超过 1 MiB 的 `files.write`	连接建立后无超时（连接本身仍受 `timeout` 限制）
`download_snapshot`	每次读取 `timeout`，而不是整个下载过程
`apps.realtime`	仅在响应头到达之前

timeout 为 0 或更小时，会禁用所有超时，包括 120 秒的下限。调用一旦发送就无法取消：唯一可以中途停止的流是 apps.realtime()，可从任意线程调用 close()。对于耗时较长的上传，请保留默认超时，以便在连接时检测到失效的连接；如果程序的其余部分必须继续运行，请在线程中或使用 AsyncSquareCloud 执行上传。

账户

client.account.me() 返回已认证的用户，以及该密钥可见的应用和数据库。

from datetime import datetime

me = client.account.me()
user = me["user"]

print(user["id"], user["name"], user["email"], user["plan"]["name"])
print(user["plan"]["memory"])  # {'limit', 'available', 'used'} in MB

duration = user["plan"]["duration"]
print(datetime.fromtimestamp(duration / 1000) if duration else "never expires")

字段	说明
`user`	`id`、`name`、`email`、`locale`、`created_at` 和 `plan`（`name`、`memory`、`duration`：套餐到期时的 Unix 毫秒时间，永不到期时为 `None`）
`applications`	`{ id, name, desc?, ram, lang, domain?, custom?, cluster, created_at }` 列表
`databases`	`{ id, name, ram, type, cluster, created_at }` 列表

client.account.snapshots(scope=...) 列出账户的所有 snapshot：参见 Snapshots。

平台状态

client.service.status() 返回公开的平台状态。该路由不需要有效密钥，但客户端仍要求提供一个非空密钥。

status = client.service.status()

print(status["status"])  # "online" | "degraded" | "unknown"
print(status["message"])

for name, service in status.get("services", {}).items():
    print(name, service["status"])  # "operational" | "degraded" | "outage" | "maintenance" | "unknown"

unknown 表示检查本身无法运行：这并不代表发生了故障。

高级

自定义传输层

transport= 会替换 HTTP 层。可用于代理、追踪或测试。传输层是任何具有如下签名的可调用对象：

transport(method, url, headers, body, timeout, stream) -> Response

参数	说明
`method`、`url`、`headers`	请求本身。`headers` 已包含 `Authorization`（绝不会发送到 snapshot 下载主机）、`User-Agent`，以及上传时的 `Content-Length`
`body`	`bytes`、由 `bytes` 块组成的可迭代对象（上传，流式发送）或 `None`
`timeout`	每次套接字操作的超时秒数，对保持连接的调用已相应提高。上传、超过 1 MiB 的 `files.write` 和实时流为 `None`：请自行限制它们的连接时间
`stream`	当调用方以增量方式读取响应体（实时、snapshot 下载），并可能从另一个线程调用 `close()` 来中止时为 `True`

返回的对象需要具备 status、read()、readline() 和 close()：http.client.HTTPResponse 即满足要求。重试、错误映射以及 {status, response} 的解包都保留在客户端中，因此传输层只负责搬运字节。 HTTPTransport(timeout=30.0) 是默认传输层：每个线程和主机一个 keep-alive 连接，响应使用 gzip 压缩（流除外），并将 timeout 作为那些没有自身超时的调用的连接上限。你可以对它进行包装：

import os
import time

from squarecloud import HTTPTransport, SquareCloud

default = HTTPTransport()


def timed(method, url, headers, body, timeout, stream):
    started = time.perf_counter()
    response = default(method, url, headers, body, timeout, stream)
    print(method, url, response.status, f"{time.perf_counter() - started:.3f}s")
    return response


client = SquareCloud(os.environ["SQUARECLOUD_API_KEY"], transport=timed)

client.close() 会关闭默认传输层的连接。具有 close() 方法的自定义传输层也会被关闭。

日志记录

SDK 会在 squarecloud 日志记录器上以 DEBUG 级别记录每个请求：方法、路径和状态，绝不记录请求体或密钥。它只挂载了一个 NullHandler，因此在你配置日志之前不会输出任何内容：

import logging

logging.basicConfig()
logging.getLogger("squarecloud").setLevel(logging.DEBUG)

后续步骤

管理应用

状态、生命周期、日志和指标。

错误

错误类、重试和速率限制。

API 简介

基础 URL、身份验证和第一个请求。

CLI 快速开始

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

CLI

VS Code

SDKs

Python SDK：快速上手与客户端

要求

安装

API 密钥与作用域

创建客户端

异步客户端

选项

模块

约定

ID 在前，返回纯数据

Workspace 应用

ID 会被编码

日期

超时

账户

平台状态

高级

自定义传输层

日志记录

后续步骤

管理应用

错误

API 简介

CLI 快速开始

​要求

​安装

​API 密钥与作用域

​创建客户端

​异步客户端

​选项

​模块

​约定

​ID 在前，返回纯数据

​Workspace 应用

​ID 会被编码

​日期

​超时

​账户

​平台状态

​高级

​自定义传输层

​日志记录

​后续步骤

管理应用

错误

API 简介

CLI 快速开始

要求

安装

API 密钥与作用域

创建客户端

异步客户端

选项

模块

约定

ID 在前，返回纯数据

Workspace 应用

ID 会被编码

日期

超时

账户

平台状态

高级

自定义传输层

日志记录

后续步骤