> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # v6 への移行 > @squarecloud/api v5 から v6 への変更点: クラスの代わりにプレーンなデータ、第 1 引数に ID、単一のエラークラス、タイムアウトとリトライ。メソッドごとの対応表付き。 v6 は全面的な書き直しです。フラットな単一のクライアント、クラスの代わりにプレーンなデータ、第 1 引数に ID、そして単一のエラークラス。変更のほとんどは機械的に置き換えられます。 ## 概要 | v5 | v6 | | ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | メソッドを持つクラス (`app.start()`) | プレーンなデータ。メソッドはクライアント上にある (`api.apps.start(appId)`) | | `Collection` | `Array` | | `Date` を使った camelCase のクラスフィールド (`createdAt`、`modifiedAt`、`uptime`) | API のフィールドと値そのまま (`created_at` と `modified` は ISO 文字列、`uptime` はミリ秒) | | `Buffer` | `Uint8Array` (入力としては引き続き `Buffer` も受け付けます) | | 変更系は `Promise` を返す (常に `true`) | `Promise`、または API が返すデータ (`envs.*` → `EnvVars`、`deploys.setWebhook` → URL、`deploys.linkGithubApp` → `LinkedRepository`、`resetCredentials` → パスワード) | | `code` のみを持つ `SquareCloudAPIError extends TypeError` | `status`、`code`、`message` (サーバーのもの)、`method`、`path`、`cause` を持つ `extends Error` | | イベント (`userUpdate`、`statusUpdate`、`logsUpdate`、`snapshotsUpdate`) と `api.cache`/`app.cache` | 削除: 状態は自分で保持してください | | `api.api.request()` (生の `APIService`) | 削除: すべての操作にメソッドがあります | | タイムアウトなし、リトライなし | 試行ごとに 30 秒のタイムアウト、安全な失敗のみリトライ ([動作の変更](#動作の変更)を参照) | | Node.js >= 20 | Node.js >= 22、Deno、Bun、エッジ | | `@squarecloud/api-types` | 型は SDK に同梱 (`import type { App } from "@squarecloud/api"`) | ## 初期化とオプション | v5 | v6 | 備考 | | ------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `new SquareCloudAPI(key)` | `new SquareCloudAPI(key, { baseUrl?, timeoutMs?, maxRetries?, userAgent?, fetch? })` | 空のキーや空白だけのキーは `TypeError` をスローします。 | | `SquareCloudAPI.apiInfo` | `BASE_URL` と `{ baseUrl }` | `BASE_URL` = `https://api.squarecloud.app/v2`。 | | (なし) | `timeoutMs` (30000) | 試行ごと。保持される呼び出しと `ai.chat` は最低 120 秒待機します。`<= 0`、`Infinity`、`>= 2^31` を指定すると、下限も含めてすべてのタイムアウトが無効になります。 | | (なし) | `maxRetries` (2) | GET でのネットワークエラーと、記載された 503 コードのみ。429 は決してリトライしません。 | | (なし) | `userAgent` | ヘッダー全体を置き換えます (デフォルトは `squarecloud-sdk-js/`)。 | | (なし) | `fetch` | カスタム `fetch` (プロキシ、トレーシング、テスト)。 | ## メソッドごとの対応 | v5 | v6 | 備考 | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `api.user.get()` → `User` | `api.account.me()` | `{ user, applications, databases }` を返します。 | | `user.plan.expiresIn` | `new Date(user.plan.duration)` | タイムスタンプ。`null` は失効しないことを意味します。 | | `api.user.snapshots(scope)` | `api.account.snapshots({ scope })` | | | `api.service.status()` | `api.service.status()` | 新しい形式: `status`、`message`、`services`、`dependencies` など。 | | `api.applications.get()` | `(await api.account.me()).applications` | | | `api.applications.get(id)` / `fetch(id)` / `app.fetch()` | `api.apps.get(id)` | workspace で共有されたアプリも取得できます。 | | `app.isWebsite()` | `Boolean((await api.apps.get(id)).domain)` | | | `api.applications.create(file)` | `api.apps.create(file, { signal })` | パス、`Blob`/`File`、`Uint8Array` のいずれか。タイムアウトなし。 | | `api.applications.statusAll()` | `api.apps.statusAll({ workspaceId? })` | プレーンな `{ id, running, cpu?, ram? }` オブジェクト (v5 では `cpu`/`ram` が `usage` の下にネストされていました)。 | | `statusAll()[i].fetch()` (`SimpleApplicationStatus`、`SimpleDatabaseStatus`) | `api.apps.status(id)` / `api.databases.status(id)` | | | `api.applications.domains()` / `loadBalancers()` | `api.apps.domains()` / `api.apps.loadBalancers()` | | | `app.getStatus()` | `api.apps.status(id, { raw? })` | `cpu`、`ram`、`storage`、`network` はトップレベルにあります (v5 では `usage` の下にネスト)。`uptime` は `Date` ではなく、起動時刻のミリ秒タイムスタンプです (停止中は `null`)。 | | `app.getLogs()` | `api.apps.logs(id)` | | | `app.getMetrics()` | `api.apps.metrics(id)` | 新しいポイントから順に並びます。 | | `app.realtime()` → 生の `Response` | `api.apps.realtime(id, { signal })` | パース済みイベントの非同期イテラブル。 | | `app.start()` / `stop()` / `restart()` / `delete()` | `api.apps.start(id)` / `stop(id)` / `restart(id)` / `delete(id)` | | | `app.commit(file, fileName)` | `api.apps.commit(id, file, { path?, filename?, signal? })` | | | `app.files.list(path)` | `api.apps.files.list(id, path?)` | 存在しないディレクトリは 404 `FILE_NOT_FOUND` をスローします (以前は空のリストでした)。 | | `app.files.read(path)` → `Buffer \| undefined` | `api.apps.files.read(id, path)` → `Uint8Array` | base64 でリクエストしてデコードします (v5 はバイト配列を読み取っていました)。API が内容を送らない場合は空のバイト列になり、`undefined` にはなりません。 | | `app.files.create(file, fileName, dir)` | ``api.apps.files.write(id, `${dir}/${fileName}`, content)`` | 文字列は**内容**です (プレーンテキストとして送信)。v5 ではローカルパスとして読み取っていました。バイト列は base64 で送信されます。空の内容は空のファイルを作成します。 | | `app.files.edit(file, path)` | `api.apps.files.write(id, path, content)` | `write` と同じ送信形式: 文字列はテキスト、バイト列は base64。 | | `app.files.move(path, newPath)` / `delete(path)` | `api.apps.files.move(id, path, to)` / `delete(id, path)` | | | `app.envs.list()` | `api.apps.envs.get(id)` | | | `app.envs.set(envs)` / `replace(envs)` / `delete(keys)` | `api.apps.envs.set(id, envs)` / `replace(id, envs)` / `delete(id, keys)` | それぞれ変更後の変数を返します。 | | `app.snapshots.list()` | `api.apps.snapshots.list(id)` | 各項目に `name`、`runtime`、`origin`、`version_id`、署名付きダウンロード `url` が追加され、すべて API が送ったままの値です。 | | `app.snapshots.create()` | `api.apps.snapshots.create(id)` | 202 の場合は `{ pending: true }` (v5 ではスローしていました)、それ以外は `{ pending: false, url, key }`。 | | `app.snapshots.download()` → `Buffer` | `const s = await api.apps.snapshots.create(id)` のあと `if (!s.pending) await api.downloadSnapshot(s.url)` | `ReadableStream` で、何もバッファリングされません。保留中 (202) の snapshot にはまだ URL がありません: v5 ではスローしていました。 | | `snapshot.url` / `snapshot.download()` | `snapshot.url` / `api.downloadSnapshot(snapshot.url)` | API 自身の署名付き URL (v5 は呼び出し元の ID から誤った URL を組み立てていました)。 | | `app.snapshots.restore({ snapshotId, versionId })` | `api.apps.snapshots.restore(id, name, versionId)` | 一覧で取得した snapshot の `name` と `version_id` を渡します。エラーについては [Snapshot](/ja/sdks/js/snapshots#snapshot-の復元) を参照してください。 | | `app.deploys.integrateGithubWebhook(token)` | `api.apps.deploys.setWebhook(id, token)` | webhook URL を返します (`"@"` で削除した場合は `""`)。 | | `app.deploys.linkGithubApp({ repositoryName, repositoryBranch })` | `api.apps.deploys.linkGithubApp(id, repository, branch)` | 位置引数。`{ id, full_name, branch }` を返します。API キーが使えるようになりました (スコープ `apps:deploy`)。v5 ではセッション JWT が必要でした。 | | `app.deploys.unlinkGithubApp()` → `boolean` | `api.apps.deploys.unlinkGithubApp(id)` | `void` で解決されます (以前は `boolean`)。何も連携されていない場合は `400 GIT_NOT_CONFIGURED`。 | | `app.deploys.list()` → `Deployment[][]` | `api.apps.deploys.list(id)` → `DeployEvent[][]` | 失敗した deploy は `code` (詳細がある場合は `message` も) を伴う `state: "error"` で終わります。`source` は常に `"git"` です。 | | `app.deploys.current()` | `api.apps.deploys.current(id)` → `DeployCurrent` | 何も設定されていない場合は `{}`。 | | `app.deploys.webhookURL()` | `(await api.apps.deploys.current(id)).webhook` | | | `app.network` (`WebsiteApplication` のみ) | `api.apps.network` | 任意のアプリ ID を受け付けます。Web 以外のアプリは API が拒否します。 | | `network.setCustomDomain(domain)` | `api.apps.network.setDomain(id, domain)` | | | `network.analytics({ start, end, contentType, ... })` | `api.apps.network.analytics(id, start, end, { content_type, ... })` | 空の期間では `null`。 | | `network.errors({ start, end, include4xx })` | `api.apps.network.errors(id, start, end, { include_4xx })` | 空の期間では `null`。 | | `network.logs({ start, end })` / `performance({ start, end })` | `api.apps.network.logs(id, start, end)` / `performance(id, start, end)` | | | `network.dns()` / `purgeCache()` | `api.apps.network.dns(id)` / `purgeCache(id)` | | | `api.databases.fetch(id)` / `db.fetch()` | `api.databases.get(id)` | | | `api.databases.create(options)` / `statusAll()` | 変更なし | `statusAll()` はプレーンな `{ id, running, cpu?, ram? }` オブジェクトを返します。 | | `db.getStatus()` / `getMetrics()` | `api.databases.status(id, { raw? })` / `metrics(id)` | `ram` は使用中の RAM です (例: `"120.4MB"`、`raw` の場合は数値)。メトリクスは新しい順に並びます。 | | `db.start()` / `stop()` / `update(changes)` / `delete()` | `api.databases.start(id)` / `stop(id)` / `update(id, changes)` / `delete(id)` | | | `db.credentials.certificate()` | `api.databases.certificate(id)` | | | `db.credentials.reset(type)` | `api.databases.resetCredentials(id, type)` | 新しいパスワード (`"certificate"` の場合は `""`)。 | | `db.snapshots.list()` / `create()` / `download()` | `api.databases.snapshots.list(id)` / `create(id)` / `api.downloadSnapshot(url)` | `download()` はアプリと同様: `create(id)` のあと、保留中でなければ `downloadSnapshot(s.url)`。 | | `db.snapshots.restore(snapshotId, versionId)` | `api.databases.snapshots.restore(id, name, versionId)` | 一覧で取得した snapshot の `name` と `version_id` を渡します。 | | `api.workspaces.list()` / `fetch(id)` / `workspace.fetch()` | `api.workspaces.list()` / `get(id)` | | | `api.workspaces.create({ name })` | `api.workspaces.create(name)` | `WorkspaceCreated` (`{ id, name }`) を返します。 | | `api.workspaces.delete(id)` / `workspace.delete()` | `api.workspaces.delete(id)` | | | `api.workspaces.leave(id)` / `workspace.leave()` | `api.workspaces.leave(id)` | | | `api.workspaces.generateInviteCode()` | `api.workspaces.members.inviteCode()` | | | `workspace.members.add(code, group)` | `api.workspaces.members.add(workspaceId, code, group)` | | | `workspace.members.update(memberId, group)` / `remove(memberId)` | `api.workspaces.members.update(workspaceId, memberId, group)` / `remove(workspaceId, memberId)` | | | `workspace.applications.add(appId)` / `remove(appId)` | `api.workspaces.apps.add(workspaceId, appId)` / `remove(workspaceId, appId)` | | | (なし) | `api.ai.chat(request)`、`api.downloadSnapshot(url)`、`BASE_URL` | 新規。 | ## 型 型は SDK に同梱され、API のフィールド名を反映しています。`@squarecloud/api-types` と v5 のクラスからの主な名称変更: | v5 | v6 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `Application`、`WebsiteApplication`、`BaseApplication` | `App` (`api.apps.get()`)、`AppSummary` (`account.me()`)、`AppCreated` | | `ApplicationStatus`、`SimpleApplicationStatus`、`SimpleDatabaseStatus` | `RuntimeStats` (`{ raw: true }` の場合は `RuntimeStats`)、`StatusListItem` | | `User` | `Account` (`{ user, applications, databases }`)、`User`、`Plan` | | `Snapshot`、`DatabaseSnapshot` | `Snapshot`、`SnapshotCreated` | | `Deployment`、`DeploymentState` | `DeployEvent`、`DeployCurrent` (`DeployRepository` を含む)、`LinkedRepository` | | ネットワークのクエリオブジェクト | `AnalyticsFilters` (オプションのフィルター。`start` と `end` は引数) | | `Workspace` | `Workspace`、`WorkspaceCreated`、`WorkspaceGroup` | | `APIErrorCode` (ランタイムオブジェクト) | `ErrorCode` (型のみでランタイムコストなし。API の契約に含まれるすべてのコード) | | `APIEndpoint`、`APIEndpoints`、`APIMethod`、`APIRequestArgs`、`APIRequestOptions`、`APIResponse`、`QueryOrBody`、`ClientEvents`、`TypedEventEmitter`、`CollectionConstructor` | 削除 (リクエストの内部処理、イベント、`Collection`) | ## エラー ```ts theme={"system"} // v5 catch (e) { if (e.code === "RATE_LIMIT_EXCEEDED") ... } // v6 catch (e) { if (e instanceof SquareCloudAPIError && e.status === 429) { console.log(e.code, e.message); // KEEP_CALM "Please wait 5 seconds..." or RATE_LIMITED } } ``` * 合成コード (`RATE_LIMIT_EXCEEDED`、`PAYLOAD_TOO_LARGE`、`SERVER_UNAVAILABLE`、`UNKNOWN_ERROR_`) は廃止されました。API の実際のコード (`RATE_LIMITED`、`KEEP_CALM`、`DAILY_SNAPSHOTS_LIMIT_REACHED`、`FILE_TOO_LARGE` など) がそのまま表れます。 * レスポンスがない場合: `NETWORK_ERROR` (原因は `cause` に入ります) または `TIMEOUT` で、`status: 0`。コードのないボディは、実際の `status` とメッセージ `HTTP ` を持つ `UNKNOWN_ERROR` になります。 * API のエラーに対して `instanceof TypeError` は true ではなくなりました。 * 期限切れのキーは、不明なキーと同様に 401 `ACCESS_DENIED` になります。 * `ai.chat()` のエラーは、認証とレート制限も含めて、小文字の OpenAI コード (`access_denied`、`rate_limit_exceeded` など) を持ちます。 * 拒否された `start`/`stop`/`restart` は、コードのみを持つ 409 です: `CONTAINER_ALREADY_STARTED`、`CONTAINER_ALREADY_STOPPED`、`CONTAINER_TEMPORARILY_SUSPENDED`、`CONTAINER_NOT_FOUND`、`CONTAINER_INSUFFICIENT_DISK_SPACE`、`CONTAINER_NETWORK_CONFLICT`、`ACTION_FAILED`。 ## 動作の変更 * 呼び出しがタイムアウトするようになりました: デフォルトで試行ごとに 30 秒 (v5 にはタイムアウトがありませんでした)、サーバーが接続を保持する呼び出しでは最低 120 秒。無効にするには `timeoutMs: 0` を設定します。 * `files.write()` は文字列を内容として扱い、プレーンテキストとして送信します。バイト列は base64 でバイナリセーフに送信され、空の内容は空のファイルを作成します (Python SDK および Go SDK と同じ送信形式)。`files.read()` は base64 をリクエストしてデコードします。 * 存在しないディレクトリに対する `files.list()` は、`[]` を返す代わりに 404 `FILE_NOT_FOUND` をスローします。 * `snapshots.create()` は、202 の場合にスローする代わりに `{ pending: true }` を返します。 * 文字列の結果が `undefined` になることはありません: API が何も送らない場合、`setWebhook` と `resetCredentials("certificate")` は `""` を返し、`deploys.current()` は `{}` を返します。 * `realtime()` は、接続が切れた場合と `REALTIME_RECONNECT` の場合に再接続します (連続 3 回まで、オープンは 5.5 秒に最大 1 回)。 * リトライ: GET でのネットワークエラーと 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY` (および GET での `DATABASE_UNAVAILABLE`) を、バックオフ付きでリトライします。429 は決してリトライしません。`DATABASE_UNAVAILABLE` は変更が適用された後に返されることがあるため、冪等な変更は自分でリトライしてください。 * 空、`.`、`..` の ID はローカルで `INVALID_ID` として失敗します。 * `undefined`、`""`、`false` のクエリ値は送信されません。