跳转到主要内容
本页记录的是 @squarecloud/api v4。如果你正从 v3 升级，请先阅读 v3 → v4 迁移指南。

​
要求

​
安装

npm install @squarecloud/api

​
实例化客户端

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);

​
构造函数

参数类型是否必填说明
apiKeystring是你的 Square Cloud API 密钥。如果它不是字符串，客户端会抛出异常。

​
模块

客户端通过专用模块暴露整个 v2 平台。每个模块都是 SquareCloudAPI 实例的一个属性。
属性模块文档
api.user已认证用户、套餐、拥有的应用和数据库本页
api.applications列出、获取、上传和检查应用管理应用
api.databases创建、获取和管理数据库数据库
api.workspaces创建、列出和管理 workspaceWorkspaces
api.service聚合平台状态本页
api.cache由 SDK 事件填充的内存缓存本页

​
获取已认证用户

api.user.get() 返回一个 User 实例，其中包含账户详情、当前套餐、拥有的应用和拥有的数据库。 
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "John Doe"
console.log(user.email);       // "john@example.com"
console.log(user.locale);      // "en-US"
console.log(user.plan.name);   // "free" | "standard" | ...
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>
user.applications 和 user.databases 是 Collection 实例（Map 的子类）。可以像操作任何 Map 一样遍历它们： 
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}

​
获取单个应用

使用 api.applications.fetch(id) 来检索一个数据完整的 Application（当应用带有网站域名时，则为 WebsiteApplication）。 
const app = await api.applications.fetch("abc123def456abc123def456");

console.log(app.id, app.name, app.cluster, app.createdAt);

if (app.isWebsite()) {
    // narrowed to WebsiteApplication — `.network` is available
    await app.network.purgeCache();
}
旧版的 api.applications.get(id) 重载仍然存在，但它返回较轻量的 BaseApplication，仅为向后兼容而保留。在 v4 中请优先使用 .fetch()。

​
列出 snapshot 历史（账户级）

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
关于 snapshot 载荷的详情，请参阅 Snapshots。

​
平台状态

api.service.status() 暴露聚合后的平台健康状况（与公开状态页展示的数据相同）。 
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // human-readable summary
与大多数 v2 端点不同，此路由不会将其载荷包裹在标准的 { status, response } 信封中。

​
客户端缓存

客户端维护一个内存缓存，SDK 会在你发起调用时使其保持同步： 
api.cache.user;   // last fetched User
// each application instance also exposes app.cache.status / .logs / .snapshots
SDK 会发出你可以订阅的类型化事件： 
api.on("userUpdate", (previous, current) => {
    console.log("user changed:", current.name);
});

api.on("statusUpdate", (application, previous, current) => {
    console.log(`${application.name} → ${current.status}`);
});

api.on("logsUpdate", (application, previous, current) => {
    console.log(`new logs for ${application.name}`);
});

api.on("snapshotsUpdate", (application, previous, current) => {
    console.log(`${current.length} snapshots for ${application.name}`);
});

​
错误处理

失败的请求会抛出 SquareCloudAPIError。该错误暴露一个稳定的 code 属性，你可以对其进行 switch 判断以区分不同的失败模式。 
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const app = await api.applications.fetch("invalid-id");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        console.error(err.code);    // e.g. "APP_NOT_FOUND"
        console.error(err.message);
    }
}