Skip to main content
このページは SDK を全面的に書き直した github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0) を解説しています。v2 から移行する場合は、v2 → v3 移行ガイドをお読みください。

要件

このモジュールは Go 標準ライブラリ以外に依存関係がなく、MIT ライセンスで提供されています (v2 は AGPL-3.0 でした)。パッケージ名は 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 からキーを読み取ります。サンプルを実行するターミナルで設定してください:

クライアントの作成

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 に渡します:
WithHTTPClient に渡す *http.Client に Timeout を設定しないでください。そのタイムアウトはボディの読み取りにも適用されるため、リアルタイムのストリームや snapshot のダウンロードが途中で切断されてしまいます。代わりに context、WithTimeout、http.Transport のタイムアウトを使ってください。
SDK はログを一切出力しません。リクエストをトレースするには、WithHTTPClient に渡すクライアントの http.RoundTripper をラップしてください。
API キーはクライアントの非公開フィールドに保存されます。fmt は非公開フィールドも出力するため、クライアントを %v や %+v で出力しないでください。

サンプルの実行

Go SDK の各ページのスニペットはコードの断片です。どれもこのプログラムの中で単独で動作します。このプログラムは、スニペットが使う ctx、c、appID を宣言しています:
スニペットは 1 つずつ 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 して管理します。