Client

要件

Go 1.24 以降
外部依存関係ゼロ — SDK は Go の標準ライブラリのみで構築されています
有効な API キー — Square Cloud ダッシュボードの My Account → Regenerate API/CLI KEY でリクエストできます

インストール

go get github.com/squarecloudofc/sdk-api-go/v2

モジュールは 2 つのパッケージを提供します:

Package	Import path	Contents
`rest`	`github.com/squarecloudofc/sdk-api-go/v2/rest`	HTTP クライアント、リソースインターフェース、リクエストオプション、エラー、SSE ストリーム
`squarecloud`	`github.com/squarecloudofc/sdk-api-go/v2/squarecloud`	すべてのリクエスト/レスポンス型と構造体

クライアントの初期化

package main

import (
	"fmt"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v2/rest"
)

func main() {
	client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
	defer client.Close()

	api := rest.New(client)

	user, err := api.SelfUser()
	if err != nil {
		panic(err)
	}
	fmt.Println(user.Name)
}

rest.NewClient(token, opts...) は基盤となる HTTP クライアントを構築し、rest.New(client) はそれをすべてのリソースを公開するインターフェースである rest.Rest にラップします。アイドル接続を解放するため、常に defer client.Close() を呼び出してください。

クライアント設定（`ConfigOpt`）

rest.NewClient はトークンの後にオプションの ConfigOpt を受け取ります:

Option	Default	Description
`rest.WithLogger(*slog.Logger)`	discarded	リクエスト/レスポンスのデバッグ用の構造化ロガー
`rest.WithHTTPClient(*http.Client)`	30s timeout	カスタム `*http.Client`（プロキシ、トランスポート、タイムアウト）
`rest.WithURL(string)`	`https://api.squarecloud.app/v2`	API のベース URL
`rest.WithUserAgent(string)`	SDK default	カスタム `User-Agent` ヘッダー

client := rest.NewClient(
	os.Getenv("SQUARECLOUD_API_KEY"),
	rest.WithLogger(slog.Default()),
	rest.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)

モジュール

rest.Rest はリソースドメインごとに 1 つのインターフェースを埋め込んでおり、加えてこのページで解説するユーザーおよびサービスのメソッドを備えています:

Interface	Coverage	Documentation
`Applications`	管理、アップロード、ファイル、環境変数、snapshot、デプロイ、ネットワーク、リアルタイム	アプリケーションの管理
`Databases`	作成、管理、認証情報、snapshot	Databases
`Workspaces`	作成、メンバー、共有アプリケーション	workspace

認証済みユーザーの取得

api.SelfUser() は、アカウント詳細と現在のプランを含む squarecloud.User を返します。

user, err := api.SelfUser()
if err != nil {
	panic(err)
}

fmt.Println(user.ID)       // "abcdef0123456789abcdef01"
fmt.Println(user.Name)     // "John Doe"
fmt.Println(user.Email)    // "john@example.com"
fmt.Println(user.Locale)   // "en-US"
fmt.Println(user.Plan.Name)             // 例: "standard"
fmt.Println(user.Plan.Duration)         // プランの期間、例: "monthly"
fmt.Println(user.Plan.Memory.Limit)     // MB
fmt.Println(user.Plan.Memory.Available) // MB
fmt.Println(user.Plan.Memory.Used)      // MB
fmt.Println(user.CreatedAt)

Field	Type	Description
`ID`	`string`	ユーザー ID（24 文字の 16 進数）
`Name`	`string`	表示名
`Email`	`string`	アカウントのメールアドレス
`Locale`	`string`	優先ロケール、例: `"en-US"`
`Plan`	`squarecloud.UserPlan`	`Name`、`Memory{Limit, Available, Used}`（MB）、`Duration`
`CreatedAt`	`string`	アカウント作成日

アプリケーションとデータベースの一覧取得

api.GetApplications() と api.GetDatabases() は /users/me エンドポイントを通して所有するすべてのリソースを一覧取得し、コンパクトな squarecloud.UserApplication / squarecloud.UserDatabase ディスクリプタを返します:

apps, err := api.GetApplications()
if err != nil {
	panic(err)
}
for _, app := range apps {
	fmt.Printf("%s (%s) — %dMB\n", app.Name, app.ID, app.RAM)
}

dbs, err := api.GetDatabases()
if err != nil {
	panic(err)
}
for _, db := range dbs {
	fmt.Printf("%s (%s)\n", db.Name, db.ID)
}

単一リソースの完全なレコードを取得するには GetApplication / GetDatabase を使用します — アプリケーションの管理と Databases を参照してください。

snapshot 履歴の一覧取得（アカウント全体）

api.UserSnapshots(scope) は、指定したドメインについて所有するすべての snapshot を返します:

appSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeApplications)
if err != nil {
	panic(err)
}

dbSnapshots, err := api.UserSnapshots(squarecloud.SnapshotScopeDatabases)
if err != nil {
	panic(err)
}

snapshot ペイロードの詳細については Snapshots を参照してください。

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

api.ServiceStatus() は、集約されたプラットフォームの健全性（公開ステータスページに表示されるものと同じデータ）を公開します。

status, err := api.ServiceStatus()
if err != nil {
	panic(err)
}

fmt.Println(status.Status)  // "ok" | "degraded" | "down"
fmt.Println(status.Message) // 人間が読める要約

ほとんどの v2 エンドポイントとは異なり、このルートはペイロードを標準の { status, code, response } エンベロープで ラップしません — { status, message } を直接返します。

リクエストオプション

すべてのメソッドは、末尾に ...rest.RequestOpt を受け取り、個々のリクエストをカスタマイズできます:

Option	Description
`rest.WithContext(ctx)`	キャンセルやデッドラインのために `context.Context` を付与する
`rest.WithQueryParam(key, value)`	クエリパラメータを追加する
`rest.WithHeader(key, value)`	リクエストヘッダーを設定する
`rest.WithToken(token)`	このリクエストに限り認証トークンを上書きする

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

user, err := api.SelfUser(rest.WithContext(ctx))
if err != nil {
	panic(err)
}

エラーハンドリング

2xx 以外のレスポンスはすべて、StatusCode、Code、Message を公開する *rest.APIError として返されます。慣用的な errors.As でアンラップしてください:

app, err := api.GetApplication("invalid-id")
if err != nil {
	var apiErr *rest.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode) // 例: 404
		fmt.Println(apiErr.Code)       // 例: "APP_NOT_FOUND"
		fmt.Println(apiErr.Message)
	}
	return
}

よくあるチェックを簡単にする 2 つのヘルパーがあります:

rest.ErrorCode(err) string — API のエラーコードを返します（エラーが *rest.APIError でない場合は ""）
rest.IsRateLimit(err) bool — エラーがレートリミット系のコード（KEEP_CALM、RATE_LIMIT、RATE_LIMIT_EXCEEDED、RATELIMIT、DELAY_NOW）のいずれかであるかを報告します

if err != nil {
	if rest.IsRateLimit(err) {
		time.Sleep(5 * time.Second)
		// リトライする...
	}

	switch rest.ErrorCode(err) {
	case "APP_NOT_FOUND":
		fmt.Println("application does not exist")
	case "ACCESS_DENIED":
		fmt.Println("invalid API key")
	}
}

エラーコードは @squarecloud/api-types で使われているものと同一です — JS SDK リファレンスの完全なコード表を参照してください。

サービス

Runtimes

プラットフォーム

トラブルシューティング

CLI

SDKs

Changelog

要件

インストール

クライアントの初期化

クライアント設定（`ConfigOpt`）

モジュール

認証済みユーザーの取得

アプリケーションとデータベースの一覧取得

snapshot 履歴の一覧取得（アカウント全体）

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

リクエストオプション

エラーハンドリング

​要件

​インストール

​クライアントの初期化

​クライアント設定（ConfigOpt）

​モジュール

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

​アプリケーションとデータベースの一覧取得

​snapshot 履歴の一覧取得（アカウント全体）

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

​リクエストオプション

​エラーハンドリング

要件

インストール

クライアントの初期化

クライアント設定（`ConfigOpt`）

モジュール

認証済みユーザーの取得

アプリケーションとデータベースの一覧取得

snapshot 履歴の一覧取得（アカウント全体）

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

リクエストオプション

エラーハンドリング