このページは SDK を全面的に書き直した
squarecloud-api 5.0 を解説しています。v4 から移行する場合は、v4 → v5 移行ガイドをお読みください。要件
- Python 3.11 以降。
- API キー (API キーとスコープを参照)。
http.client、json、ssl だけです)、完全に型付けされています (py.typed)。レスポンスは、エディターや型チェッカーが理解できる TypedDict です。
インストール
- pip
- uv
- poetry
squarecloud-api としてインストールされ、squarecloud としてインポートします。インストールされているバージョンは squarecloud.__version__ で確認できます。
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.status_all()など) は、キーから見えるリソースだけを返します。 - 不明なキー、取り消されたキー、期限切れのキーは 401
ACCESS_DENIEDになります。
SQUARECLOUD_API_KEY からキーを読み取ります。サンプルを実行するターミナルで設定してください:
- macOS / Linux
- Windows (PowerShell)
クライアントの作成
SDK には、同じグループとメソッドを持つ 2 つのクライアントがあります:SquareCloudは同期型でスレッドセーフです。1 つのインスタンスを複数のスレッドで共有できます。各スレッドは自身のキープアライブ接続を再利用します。AsyncSquareCloudはawaitで使う同じ API です。各呼び出しは同期クライアントをasyncio.to_threadで実行するため、イベントループがブロックされることはありません。
- 同期
- 非同期
with / async with ブロックを抜けると、プールされた接続が閉じられます。ブロックを使わない場合は、使い終わったら client.close() を呼び出してください。close() はどちらのクライアントでも通常の (同期) メソッドです。
空のキーや空白だけのキーを渡すと、リクエストを送る前にコンストラクタで ValueError が送出されます。
非同期クライアント
AsyncSquareCloud と SquareCloud の違いは 3 点だけです:
- すべてのメソッドはコルーチンを返します:
await client.apps.status(app_id)。 close()は同期です。awaitを付けずに呼び出します。apps.realtime(app_id)はawaitしません。async forで消費するAsyncRealtimeを返します (リアルタイムを参照)。
asyncio.gather で呼び出しを並行して実行できます:
待機中のタスクをキャンセルしても、そのワーカースレッドですでに実行中のリクエストは停止しません。呼び出しはバックグラウンドで完了 (またはタイムアウト) します。
オプション
AsyncSquareCloud も同じオプションを受け取ります。
クライアントはキーを非公開のリクエストヘッダーにのみ保持します。
client.api_key 属性は存在せず、SDK のロガーがキーを書き出すこともありません。モジュール
パッケージがエクスポートするのは
SquareCloud、AsyncSquareCloud、SquareCloudAPIError、BASE_URL、HTTPTransport、Transport と Response のプロトコル、Realtime、AsyncRealtime、__version__ です。レスポンスの型 (App、RuntimeStats、Snapshot など) は squarecloud.types にあります:
規約
ID を先に渡し、プレーンなデータを受け取る
すべてのメソッドはリソース ID を第 1 引数に取り、プレーンなデータを返します。各レスポンスは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 が何も送らない場合は''になります。 - 一覧は 1 回の呼び出しで完全に返されます。ページネーションはありません。
- 省略可能な修飾引数はキーワード専用です (
status(app_id, raw=True)、commit(app_id, file, path="/src"))。唯一の例外はfiles.listの省略可能なpathで、位置引数としても渡せます。
Workspace のアプリ
すべてのapp_id は、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 文字列 (そのまま送信) または datetime (UTC で送信) を受け取ります。naive な datetime はローカル時刻として扱われて UTC に変換されるため、aware なもの (datetime.now(UTC)) を使うことをおすすめします。レスポンス内の日付は API が送ったまま (ISO 文字列、または API が使用している箇所では Unix ミリ秒) です。
タイムアウト
timeout は各ソケット操作 (接続と、すべての読み取り・書き込み) の上限です。データを送り続けるレスポンスは、合計で timeout より長くかかることがあります。
timeout に 0 以下を指定すると、120 秒の下限も含めてすべてのタイムアウトが無効になります。
送信した呼び出しはキャンセルできません。途中で停止できるストリームは apps.realtime() だけで、任意のスレッドから close() を呼び出します。長時間のアップロードでは、切れた接続を接続時に検出できるようデフォルトのタイムアウトを維持し、プログラムの他の部分を動かし続ける必要がある場合は、スレッド内または AsyncSquareCloud で実行してください。
アカウント
client.account.me() は、認証済みのユーザーと、キーから見えるアプリおよびデータベースを返します。
client.account.snapshots(scope=...) はアカウントのすべての snapshot を一覧します。Snapshot を参照してください。
プラットフォームのステータス
client.service.status() は公開されているプラットフォームのステータスを返します。このルートに有効なキーは不要ですが、クライアントには空でないキーが必要です。
unknown はチェック自体を実行できなかったことを意味し、障害の証拠ではありません。
高度な使い方
カスタムトランスポート
transport= は HTTP レイヤーを置き換えます。プロキシ、トレーシング、テストに使います。トランスポートは、次のシグネチャを持つ任意の呼び出し可能オブジェクトです:
返されるオブジェクトには
status、read()、readline()、close() が必要です。http.client.HTTPResponse はこれを満たします。リトライ、エラーのマッピング、{status, response} のアンラップはクライアント側に残るため、トランスポートはバイトを運ぶだけです。
HTTPTransport(timeout=30.0) はデフォルトのトランスポートです。スレッドとホストごとに 1 つのキープアライブ接続を使い、レスポンスは gzip 圧縮され (ストリームを除く)、独自のタイムアウトを持たない呼び出しの接続上限として timeout を使います。これをラップすることもできます:
client.close() はデフォルトのトランスポートの接続を閉じます。close() メソッドを持つカスタムトランスポートも閉じられます。
ロギング
SDK は各リクエストをsquarecloud ロガーに DEBUG レベルで記録します。記録するのはメソッド、パス、ステータスで、ボディやキーは決して記録しません。SDK は NullHandler を付けるだけなので、ロギングを設定するまでは何も出力されません:
次のステップ
アプリケーションの管理
ステータス、ライフサイクル、ログ、メトリクス。
エラー
エラークラス、リトライ、レート制限。
API 入門
ベース URL、認証、最初のリクエスト。
CLI クイックスタート
ターミナルからアプリを deploy して管理します。

