このページは SDK を全面的に書き直した
github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0) を解説しています。v2 から移行する場合は、v2 → v3 移行ガイドをお読みください。要件
- Go 1.22 以降。
- API キー (API キーとスコープを参照)。
squarecloud です。
インストール
API キーとスコープ
squarecloud.app/account/security でキーを作成します。SDK はキーをAuthorization ヘッダーにそのまま送信します (Bearer プレフィックスは付きません)。
キーはスコープ (apps:read、apps:deploy、apps:control、ai:chat など) や、特定のアプリ・データベースに制限できます:
- その制限を超える呼び出しは、403
MISSING_SCOPEまたはRESOURCE_NOT_ALLOWEDの*APIErrorを返します。 - 一覧系のメソッド (
Account.Me、Apps.StatusAllなど) は、キーから見えるリソースだけを返します。 - 不明なキー、取り消されたキー、期限切れのキーは 401
ACCESS_DENIEDになります。
SQUARECLOUD_API_KEY からキーを読み取ります。サンプルを実行するターミナルで設定してください:
- macOS / Linux
- Windows (PowerShell)
クライアントの作成
main.go としてモジュール内に保存し (go mod init example.com/hello の後、上の go get を実行)、go run . で実行します。アカウント名とキーから見えるアプリの数が出力されます:
squarecloud.New(apiKey, opts...) は *Client を返し、エラーを返すことはありません。*Client は並行して使用しても安全です。一度だけ作成し、goroutine 間で共有してください。
New は失敗しないため、空のキーや空白だけのキーもそこでは拒否されません。代わりに、Service.Status 以外のすべての呼び出しが、リクエストを送る前にローカルで INVALID_API_KEY (ステータス 0) として失敗します。このコードは Go SDK にのみ存在します。
オプション
オプションはキーの後にNew に渡します:
SDK はログを一切出力しません。リクエストをトレースするには、
WithHTTPClient に渡すクライアントの http.RoundTripper をラップしてください。
サンプルの実行
Go SDK の各ページのスニペットはコードの断片です。どれもこのプログラムの中で単独で動作します。このプログラムは、スニペットが使うctx、c、appID を宣言しています:
main に貼り付け、goimports -w . を実行して必要なインポート (fmt、log、time など) を追加してください。goimports は go install golang.org/x/tools/cmd/goimports@latest でインストールできます。エディターの Go 拡張機能 (gopls) に保存時にインポートを追加させることもできます。データベースや workspace など、ほかの ID が必要なページでは、そのページ用のこのプログラムから始めます。
モジュール
New と With* オプションのほかに、パッケージは DefaultBaseURL と Version の定数、エラーコードごとに 1 つの Code* 定数を持つ APIError 型、列挙型の入力に対する型付き定数 (DatabaseRedis、GroupView、ResetPassword、SnapshotScopeDatabases など)、そして API の形状ごとに 1 つの構造体をエクスポートしており、自分のコードで利用できます:
規約
context と ID を先に渡し、型付きのデータを受け取る
すべてのメソッドは第 1 引数にcontext.Context、その次にリソース ID を取り、プレーンな構造体 (メソッドもキャッシュもありません) を返します。json タグは API のフィールド名 (created_at、version_id、lastModified、joinedAt、netIO など) そのままなので、API リファレンスをそのまま適用できます。CreatedAt は created_at、VersionID は version_id です。API が後から追加したフィールドは無視されるため、デコードが壊れることはありません。
- 変更系のメソッドは
errorだけを返します。ただし API がデータを返す場合 (Envs.*、Deploys.SetWebhook、Deploys.LinkGithubApp、Databases.ResetCredentialsとCreate系のメソッド) は除きます。 - API が何も送らない場合、文字列の結果は
""になります。 - API が
nullとして送る可能性のあるフィールドはポインタです。使用する前にnilかどうかを確認してください。 - カウンターとバイトサイズは
int64です。 - 一覧は 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 の引数 (ネットワークを参照) は time.Time の値で、UTC の RFC 3339 (秒単位) として送信されます。レスポンスでは、API の ISO 8601 文字列は time.Time にデコードされ、API が Unix ミリ秒で送るフィールドは数値のままです (Plan.Duration と Uptime は *int64、FileEntry.LastModified は *float64)。time.UnixMilli で変換してください。
タイムアウト
- デフォルトの期限は
ctxに期限がない場合にのみ適用されます。ctxの期限は、デフォルトより短くても長くても、下限を含めて常に優先されます。 - 1 つの期限が呼び出し全体を対象とします。すべての試行と、リトライ間の待機時間も含まれます。
WithTimeout(0)(またはd <= 0の任意の値) を指定すると、2 分の下限も含めてすべてのデフォルトの期限が無効になります。
ctx を受け取るので、どの呼び出しでも期限を設けたりキャンセルしたりできます:
ctx の期限が切れた呼び出しは TIMEOUT の *APIError を返し、ctx がキャンセルされた呼び出しは NETWORK_ERROR を返します。どちらもステータスは 0 です。これらは context のエラーにアンラップされるため、errors.Is(err, context.DeadlineExceeded) と errors.Is(err, context.Canceled) が機能します。リアルタイムのループは、代わりに素の ctx.Err() を返します。
アカウント
c.Account.Me(ctx) は、認証済みのユーザーと、キーから見えるアプリおよびデータベースを返します。
c.Account.Snapshots(ctx, scope) はアカウントのすべての snapshot を一覧します。Snapshot を参照してください。
プラットフォームのステータス
c.Service.Status(ctx) は公開されているプラットフォームのステータスを返します。このルートにキーは不要で、空のキーで作成したクライアントでも動作する唯一のメソッドです。
unknown はチェック自体を実行できなかったことを意味し、障害の証拠ではありません。
次のステップ
アプリケーションの管理
ステータス、ライフサイクル、ログ、メトリクス。
エラー
エラークラス、リトライ、レート制限。
API 入門
ベース URL、認証、最初のリクエスト。
CLI クイックスタート
ターミナルからアプリを deploy して管理します。

