メインコンテンツへスキップ
このページは @squarecloud/api v4 を解説しています。v3 からのアップグレードの場合は、まず v3 → v4 移行ガイド をお読みください。

​
要件

​
インストール

npm install @squarecloud/api

​
クライアントの初期化

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

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

​
コンストラクタ

ParameterTypeRequiredDescription
apiKeystringYesSquare Cloud の API キー。文字列でない場合、クライアントは例外をスローします。

​
モジュール

クライアントは v2 プラットフォーム全体を専用のモジュールを通して公開します。各モジュールは SquareCloudAPI インスタンスのプロパティです。
PropertyModuleDocumentation
api.user認証済みユーザー、プラン、所有するアプリとデータベースこのページ
api.applicationsアプリケーションの一覧取得、取得、アップロード、検査アプリケーションの管理
api.databasesデータベースの作成、取得、管理Databases
api.workspacesworkspace の作成、一覧取得、管理Workspaces
api.serviceプラットフォームステータスの集約このページ
api.cacheSDK イベントによって設定されるインメモリキャッシュこのページ

​
認証済みユーザーの取得

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()) {
    // WebsiteApplication に絞り込まれる — `.network` が利用可能
    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); // 人間が読める要約
ほとんどの v2 エンドポイントとは異なり、このルートはペイロードを標準の { status, response } エンベロープで ラップしません。

​
クライアントキャッシュ

クライアントは、呼び出しを行うたびに SDK が同期を保つインメモリキャッシュを維持します: 
api.cache.user;   // 最後に取得した User
// 各アプリケーションインスタンスも 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 をスローします。このエラーは、失敗モードを判別するために switch できる安定した code プロパティを公開します。 
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);    // 例: "APP_NOT_FOUND"
        console.error(err.message);
    }
}