v3 への移行

​

概要

​

初期化とオプション

-import (
-	"github.com/squarecloudofc/sdk-api-go/v2/rest"
-	"github.com/squarecloudofc/sdk-api-go/v2/squarecloud"
-)
-client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger))
-api := rest.New(client)
-defer client.Close()
+import "github.com/squarecloudofc/sdk-api-go/v3"
+
+c := squarecloud.New(token, squarecloud.WithUserAgent(ua))

go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0

​

メソッドごとの対応

​

型

​

エラー

// v2
if rest.IsRateLimit(err) { ... }

// v3
var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Status == 429 {
	fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED
}

• ネットワークの失敗は、Status が 0、Code が NETWORK_ERROR または TIMEOUT、Message が原因のテキストである *APIError になり、原因にアンラップされます (errors.Is(err, context.Canceled) が機能します)。
• ローカルのチェック (Status 0: INVALID_ID、FILE_TOO_LARGE、INVALID_API_KEY) と、JSON ではない 2xx のボディ (UNKNOWN_ERROR、Invalid JSON in HTTP <status> response) も同様です。
• "status": "error" を含む 2xx のボディはエラーになりました (v2 は成功として報告していました)。アプリとデータベースの start/stop に対するクラスターの拒否は、メッセージなしの 409 CONTAINER_ALREADY_STARTED、CONTAINER_ALREADY_STOPPED、CONTAINER_TEMPORARILY_SUSPENDED、CONTAINER_NOT_FOUND、CONTAINER_INSUFFICIENT_DISK_SPACE、CONTAINER_NETWORK_CONFLICT または ACTION_FAILED として届きます。SDK は「すでに〜済み」の応答をエラーとして返すので、必要であれば自分で成功として扱ってください。
• コードのないレスポンスは、Code が UNKNOWN_ERROR になります。
• 期限切れの API キーは、不明なキーと同様に 401 ACCESS_DENIED です。
• API がドキュメント化しているすべてのコードに Code* 定数があります。API は、以前 RATE_LIMIT と RATE_LIMIT_EXCEEDED を送っていた箇所で 429 RATE_LIMITED (CodeRateLimited) を送るようになりました。CodeRateLimit と CodeRateLimitExceeded は非推奨として残っています。
• AI.Chat のエラーはすべて OpenAI の形式で、小文字のコード (access_denied、rate_limit_exceeded、server_overloaded など) を持ち、Code にはそれがそのまま入ります。
• Error() は squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> を出力します (v2: squarecloud: <message> (<CODE>, HTTP <status>))。テキストではなく、フィールドで判定してください。

​

動作の変更

• 空の API キー: New("") (または空白だけのキー) は引き続きクライアントを返します (エラーを返せないため) が、Service.Status 以外のすべての呼び出しがローカルで INVALID_API_KEY として失敗します。
• Snapshot の 202: v2 は StatusCode 202 の *APIError を返していました。v3 は Pending: true の SnapshotCreated と nil のエラーを返します。
• リアルタイム: Next は RealtimeEvent を返すようになりました。ev.Event (system、status、logs、error、message) で分岐してください。ログには ev.Line を出力し (\u0001/\u0002 のバイトは取り除かれます。ev.Data は生のフレームのままです)、stdout/stderr の判別には ev.Stream を使います。ステータスには ev.Status を使います。status イベントでは決して nil にならず、フレームと再接続をまたいでシャローマージされます。REALTIME_DISCONNECTED の後、Next は io.EOF を返します。ストリームが 30 秒後に切断されることはなくなり、再接続は前回の接続から最低 5.5 秒待ち、接続を開く処理はヘッダーが届くまでクライアントのタイムアウトで制限されます。リアルタイムを参照してください。
• タイムアウト: v2 はすべてに固定の 30 秒の http.Client タイムアウトを使っていました。v3 は ctx に期限がない場合にのみデフォルトの期限を適用します。ほとんどの呼び出しにはクライアントのタイムアウト (WithTimeout、30 秒)、start/stop/restart、データベースの作成、snapshot の作成/復元、AI.Chat には最低 2 分、アップロード、1 MiB を超える内容のファイル書き込み、snapshot のダウンロードには期限なしです。WithTimeout(0) でそれらすべてが無効になります。
• 空のネットワーク期間: Analytics、Errors、Performance は、期間にトラフィックがない場合 nil ポインタを返します。
• ヘッダー: すべての API リクエストは Accept: application/json (リアルタイムでは text/event-stream) を送信します。デフォルトの User-Agent は Square GO から squarecloud-sdk-go/3.0.0 に変わりました (WithUserAgent で引き続き上書きできます)。
• ID: すべての ID は 1 つのパスセグメントとしてパーセントエンコードされるようになり (v2 はそのままパスに埋め込んでいました)、空、.、.. の ID はローカルで INVALID_ID として失敗します。
• ファイルの書き込み: v2 は常に内容を文字列として送信していたため、バイナリファイルが破損し、空のファイルを書き込めませんでした。v3 は常に内容を base64 エンコードで送信するため、すべてのバイトがそのまま往復し、空の内容では空のファイルが書き込まれ、10 MB を超える内容はローカルで FILE_TOO_LARGE として失敗します。デコードできない内容に対して、API は 400 INVALID_CONTENT を返します。
• ファイルの読み取り: v3 は、v2 が読み取っていた JSON のバイト配列 (API では非推奨) ではなく、常に base64 を要求してデコードします。10 MB を超えるファイルは 413 FILE_TOO_LARGE です。
• ファイルの一覧: 存在しないディレクトリの一覧は 404 FILE_NOT_FOUND になります。以前は空のリストでした。
• Snapshot: 一覧のエントリは API から送られる VersionID と URL を持ちます。Key から何かを解析することはありません。
• リトライ: 新機能です。GET のネットワークエラー、503 UPLOAD_BUSY/ANALYTICS_BUSY、そして GET での 503 DATABASE_UNAVAILABLE は、デフォルトで 2 回リトライされます。WithMaxRetries(0) で v2 の動作に戻ります。DATABASE_UNAVAILABLE は変更が開始された後に返されることがあるため、SDK はほかのメソッドでは決してリトライしません。必要であれば、冪等な変更は自分でリトライしてください。リトライを参照してください。
• Go のバージョン: 最小バージョンが Go 1.24 から Go 1.22 に下がりました。