Skip to main content
このページは SDK を全面的に書き直した @squarecloud/api v6 を解説しています。v5 から移行する場合は、v5 → v6 移行ガイドをお読みください。

要件

  • Node.js 22 以降、Deno、Bun、またはエッジランタイム。SDK が必要とするのは fetch、FormData、Blob、Web Streams だけです。
  • API キー (API キーとスコープを参照)。
パッケージには ESM ビルドと CommonJS ビルドが含まれ、ランタイム依存関係はなく、独自の TypeScript 型も同梱されています。@squarecloud/api-types はもう必要ありません。

インストール

API キーとスコープ

squarecloud.app/account/security でキーを作成します。SDK はキーを Authorization ヘッダーにそのまま送信します (Bearer プレフィックスは付きません)。 キーはスコープ (apps:read、apps:deploy、apps:control、ai:chat など) や、特定のアプリ・データベースに制限できます:
  • その制限を超える呼び出しは、403 MISSING_SCOPE または RESOURCE_NOT_ALLOWED の SquareCloudAPIError をスローします。
  • 一覧系のメソッド (account.me()、apps.statusAll() など) は、キーから見えるリソースだけを返します。
  • 不明なキー、取り消されたキー、期限切れのキーは 401 ACCESS_DENIED になります。
キーはサーバー側に保管してください。SDK はブラウザでも動作しますが、そうするとすべての訪問者にキーが公開されてしまいます。
サンプルは環境変数 SQUARECLOUD_API_KEY からキーを読み取ります。サンプルを実行するターミナルで設定してください:

クライアントの作成

最初のサンプルは、アカウント名とキーから見えるアプリの数を出力します:
空のキーや空白だけのキーを渡すと、リクエストを送る前にコンストラクタで TypeError がスローされます。

オプション

API キーはクライアントオブジェクトの通常のプロパティとして保持されます。クライアントを console.log したりシリアライズしたりしないでください。

モジュール

ランタイムでエクスポートされるのは SquareCloudAPI、SquareCloudAPIError、BASE_URL だけです。その他のエクスポート (App、RuntimeStats、ErrorCode など) はすべて型です:

規約

ID を先に渡し、プレーンなデータを受け取る

すべてのメソッドはリソース ID を第 1 引数に取り、プレーンなデータを返します (クラスもキャッシュもありません)。フィールド名は API のもの (created_at、version_id、lastModified、joinedAt、netIO など) そのままなので、API リファレンスをそのまま適用できます。
  • 変更系のメソッドは void で解決されます。ただし API がデータを返す場合 (envs.*、deploys.setWebhook、deploys.linkGithubApp、databases.resetCredentials と create 系のメソッド) は除きます。
  • 文字列の結果が undefined になることはありません。API が何も送らない場合は "" になります。
  • 一覧は 1 回の呼び出しで完全に返されます。ページネーションはありません。
メソッドはアロー関数なので、分割代入して使えます:

Workspace のアプリ

すべての appId は、workspace を通じて共有されたアプリを操作するための複合形式 <appId>-<workspaceId> も受け付けます。workspaces.get() と workspaces.list() は素の ID を返すので、複合 ID は自分で組み立てます:

ID はエンコードされる

URL パス内の ID はパーセントエンコードされます。空、.、.. の ID は別のルートに届いてしまうため、何も送信する前にローカルで INVALID_ID (ステータス 0) として失敗します。Workspace のルートは ID をボディで送信するため、そこでの INVALID_ID (400) はサーバーから返されます。

日付

start と end の引数 (ネットワークを参照) は ISO 8601 文字列または Date を受け取ります。レスポンス内の日付は API が送ったまま (ISO 文字列、または API が使用している箇所では Unix ミリ秒) です。

タイムアウト

timeoutMs に 0 以下、Infinity、または >= 2^31 を指定すると、120 秒の下限も含めてすべてのタイムアウトが無効になります。 AbortSignal を受け取るメソッドは apps.create、apps.commit、files.write、apps.realtime、downloadSnapshot の 5 つだけです。
中断された呼び出しは、SquareCloudAPIError ではなくシグナルの reason で reject されます。中断された realtime() のループは単に終了します。

アカウント

api.account.me() は、認証済みのユーザーと、キーから見えるアプリおよびデータベースを返します。
api.account.snapshots({ scope }) はアカウントのすべての snapshot を一覧します。Snapshot を参照してください。

プラットフォームのステータス

api.service.status() は公開されているプラットフォームのステータスを返します。このルートに有効なキーは不要ですが、クライアントには空でないキーが必要です。
unknown はチェック自体を実行できなかったことを意味し、障害の証拠ではありません。

次のステップ

アプリケーションの管理

ステータス、ライフサイクル、ログ、メトリクス。

エラー

エラークラス、リトライ、レート制限。

API 入門

ベース URL、認証、最初のリクエスト。

CLI クイックスタート

ターミナルからアプリを deploy して管理します。