> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # v3 への移行 > Go SDK v2 から v3 への変更点: 単一のパッケージ、具象型の *Client、第 1 引数の ctx、リソースグループ、単一のエラー型、タイムアウトとリトライ。メソッドごとの対応表付き。 v3 は破壊的変更を含むリリースです。単一のパッケージ、具象型の `*Client`、すべての箇所で第 1 引数となる `ctx`、そしてリソースグループを採用し、v2 の既知のバグをすべて修正しています。現在の API の 67 個の操作をすべてカバーしています。 ## 概要 | | v2 | v3 | | ------ | ----------------------------------------------------- | -------------------------------------------------------------------------------------------- | | モジュール | `.../v2` (`rest` + `squarecloud` パッケージ) | `github.com/squarecloudofc/sdk-api-go/v3` (単一のパッケージ) | | クライアント | `rest.New(rest.NewClient(key, ...))` (インターフェース) | `squarecloud.New(key, ...Option)` (`*Client`) | | 呼び出し | `api.GetApplicationStatus(id, rest.WithContext(ctx))` | `c.Apps.Status(ctx, id)` | | エラー | `StatusCode` を持つ `*rest.APIError`。ネットワークエラーは型なし | すべてに対して `Status`、`Code`、`Message`、`Method`、`Path` を持つ `*squarecloud.APIError` | | タイムアウト | すべてに固定の 30 秒の `Timeout` を持つ `http.Client` | `ctx` による呼び出しごとの設定、`WithTimeout`、ストリームは無制限 | | リトライ | なし | GET のネットワークエラーと 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY`/`DATABASE_UNAVAILABLE` (`WithMaxRetries`) | | ログ出力 | `WithLogger` (シークレットが漏洩していた) | なし | | Go | 1.24 | 1.22 以降 | | ライセンス | AGPL-3.0 | MIT | ## 初期化とオプション ```diff theme={"system"} -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)) ``` ```bash theme={"system"} go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0 ``` | v2 | v3 | | ----------------------------------------------------- | --------------------------------------------------------------------------------------- | | `rest` + `squarecloud` パッケージ | 単一のパッケージ `squarecloud` (モジュール `.../v3`) | | `rest.NewClient(token, opts...)` + `rest.New(client)` | `squarecloud.New(token, opts...)` | | `rest.Rest` (インターフェース) | `*squarecloud.Client` (具象型の構造体)。モックするには、独自の小さなインターフェースを宣言するか `httptest` を使います | | `rest.ConfigOpt` | `squarecloud.Option` | | `rest.WithHTTPClient(hc)` | `squarecloud.WithHTTPClient(hc)`。`hc.Timeout` は設定しないでください。リアルタイムのストリームやダウンロードが途中で切断されます | | `rest.WithURL(u)` | `squarecloud.WithBaseURL(u)` (引き続き `/v2` を含みます) | | `rest.WithUserAgent(ua)` | `squarecloud.WithUserAgent(ua)` | | `rest.WithLogger(l)` | 削除: SDK はログを一切出力しません (v2 はデバッグログにシークレットを漏洩していました)。トレースするには `hc.Transport` をラップします | | `client.Close()`, `client.HTTPClient()` | 削除: 独自の `*http.Client` を保持し、その `CloseIdleConnections` を呼び出します | | `rest.APIURL`, `rest.APIVersion`, `rest.Endpoint*` | 削除。`squarecloud.DefaultBaseURL` は定数です | | (なし) | `squarecloud.WithMaxRetries(n)` (新規。デフォルトは 2) | | 固定の 30 秒の `http.Client` タイムアウト | `squarecloud.WithTimeout(d)` (新規。デフォルトは 30 秒で、`d <= 0` はすべてのデフォルトの期限を無効にします) | リクエストごとのオプション: | v2 | v3 | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rest.WithContext(ctx)` | `ctx` はすべてのメソッドの第 1 引数です | | `rest.WithToken(token)` (例: ログイン時のキーの検証) | 使い捨てのクライアントを作成します: `squarecloud.New(token).Account.Me(ctx)` (軽量で、接続は保持されません) | | commit での `rest.WithQueryParam("path", dir)` | `c.Apps.Commit(ctx, id, r, dir, "")` | | アナリティクスでの `rest.WithQueryParam(filter, v)` | `Country`、`IP`、`Path`、`Status`、`OS`、`Browser`、`Protocol`、`Referer`、`Provider`、`ContentType`、`Bot` を持つ `c.Apps.Network.Analytics(ctx, id, start, end, squarecloud.AnalyticsFilters{...})` | | `rest.WithQueryParam("include_4xx", "true")` | `c.Apps.Network.Errors(ctx, id, start, end, true)` | | 一覧ステータスでの `rest.WithQueryParam("workspaceId", ws)` | `c.Apps.StatusAll(ctx, ws)` | | `rest.WithHeader`, `rest.RequestOpt`, `rest.RequestConfig`, `rest.DefaultRequestConfig` | 削除 | ## メソッドごとの対応 `api` は v2 の `rest.Rest`、`c` は v3 の `*squarecloud.Client` です。 | v2 | v3 | 備考 | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api.SelfUser()` | `me, err := c.Account.Me(ctx)`、その後 `me.User` | `Account` を返します | | `api.GetApplications()` | `c.Account.Me(ctx)`、その後 `me.Applications` (`[]AppSummary`) | | | `api.GetDatabases()` | `c.Account.Me(ctx)`、その後 `me.Databases` (`[]DatabaseSummary`) | | | `api.UserSnapshots(scope)` | `c.Account.Snapshots(ctx, scope)` | | | `api.ServiceStatus()` | `c.Service.Status(ctx)` | 新しいモデル。[型](#型)を参照 | | `api.PostApplications(r)` → `*ApplicationUploaded` | `c.Apps.Create(ctx, r)` → `AppCreated` (値) | v2 は zip をメモリにバッファし、パートを `upload.zip` と名付けていました。v3 はストリーミングし、パートを `*os.File` の名前 (ベース名)、なければ `app.zip` と名付けます。`Subdomain` はなくなりました。完全なホスト (`my-app.squareweb.app`) である `Domain` を参照してください。Web 以外のアプリでは `""` です | | `api.GetApplication(id)` | `c.Apps.Get(ctx, id)` | | | `api.DeleteApplication(id)` | `c.Apps.Delete(ctx, id)` | | | `api.PostApplicationSignal(id, squarecloud.ApplicationSignalStart/Stop/Restart)` | `c.Apps.Start(ctx, id)` / `c.Apps.Stop(ctx, id)` / `c.Apps.Restart(ctx, id)` | | | `api.PostApplicationCommit(id, r, rest.WithQueryParam("path", p))` | `c.Apps.Commit(ctx, id, r, p, filename)` | v2 は常にパートを `commit.zip` と名付けていました。v3 は `filename`、なければ `*os.File` 自身の名前を使うため、zip ではない単一のファイルは zip として失敗するのではなく、そのファイル名で配置されるようになりました | | `api.GetApplicationStatus(id)` | `c.Apps.Status(ctx, id)` | | | `api.GetApplicationStatusRaw(id)` | `c.Apps.StatusRaw(ctx, id)` | | | `api.GetApplicationListStatus()` | `c.Apps.StatusAll(ctx, "")` | `[]StatusListItem` を返します | | `api.GetApplicationLogs(id)` → `ApplicationLogs` | `c.Apps.Logs(ctx, id)` → `string` | | | `api.GetApplicationMetrics(id)` | `c.Apps.Metrics(ctx, id)` | ポイントは API が送るとおり、新しい順で返されます | | `api.ApplicationRealtime(id, rest.WithContext(ctx))` | `c.Apps.Realtime(ctx, id)` | `*Realtime` を返します。[動作の変更](#動作の変更)を参照 | | `api.GetApplicationDomains()` | `c.Apps.Domains(ctx)` | | | `api.GetLoadBalancers()` | `c.Apps.LoadBalancers(ctx)` | | | `api.GetApplicationEnvs(id)` | `c.Apps.Envs.Get(ctx, id)` | | | `api.SetApplicationEnvs(id, envs)` | `c.Apps.Envs.Set(ctx, id, envs)` | | | `api.ReplaceApplicationEnvs(id, envs)` | `c.Apps.Envs.Replace(ctx, id, envs)` | | | `api.DeleteApplicationEnvs(id, keys)` → `error` | `c.Apps.Envs.Delete(ctx, id, keys...)` → `(EnvVars, error)` (残りの変数) | | | `api.GetApplicationFiles(id, path)` → `[]FileInfo` | `c.Apps.Files.List(ctx, id, path)` → `[]FileEntry` | 存在しないディレクトリは 404 `FILE_NOT_FOUND` になりました (以前は空のリスト)。保護されたパスは 403 `BLOCKED_PATH` です | | `api.ReadApplicationFile(id, path)` → `FileContent` | `c.Apps.Files.Read(ctx, id, path)` → `[]byte` | base64 で要求してデコードします。10 MB を超えるファイルは 413 `FILE_TOO_LARGE` です | | `api.PutApplicationFile(id, path, b)` → `(FileWritten, error)` | `c.Apps.Files.Write(ctx, id, path, b)` → `error`。`written` のチェックは削除してください。成功は `nil` のエラーで表されます | 内容は常に base64 エンコードで送信されるため、バイナリファイルも安全です。空の内容では空のファイルが書き込まれます | | `api.MoveApplicationFile(id, from, to)` | `c.Apps.Files.Move(ctx, id, path, to)` | | | `api.DeleteApplicationFile(id, path)` | `c.Apps.Files.Delete(ctx, id, path)` | 動作するようになりました (v2 では常に 400) | | `api.GetApplicationSnapshots(id)` | `c.Apps.Snapshots.List(ctx, id)` | 各 `Snapshot` は、API から送られる `VersionID` と `URL` (署名付きのダウンロードリンク) を持つようになりました | | `api.CreateApplicationSnapshot(id)` | `c.Apps.Snapshots.Create(ctx, id)` | `.URL` を使う前に `.Pending` (202) を確認してください | | `api.RestoreApplicationSnapshot(id, snapID, verID)` | `c.Apps.Snapshots.Restore(ctx, id, snap.Name, snap.VersionID)` | `VersionID` は API が送るフィールドなので、`Key` から解析する必要はもうありません。エラーについては [Snapshot](/ja/sdks/go/snapshots#snapshot-の復元) を参照 | | `api.GetApplicationDeployments(id)` | `c.Apps.Deploys.List(ctx, id)` | | | `api.GetApplicationCurrentDeployment(id)` | `c.Apps.Deploys.Current(ctx, id)` | | | `api.PostApplicationDeployWebhook(id, token)` → `GithubWebhook` | `c.Apps.Deploys.SetWebhook(ctx, id, token)` → `string` | | | `api.LinkApplicationGithubApp(id, repo, branch)` → `GithubAppLink` | `c.Apps.Deploys.LinkGithubApp(ctx, id, repo, branch)` → `LinkedRepository` | API キーで動作するようになりました (スコープ `apps:deploy`)。`repository` ラッパーはなくなりました。GitHub が接続されていないアカウントは 403 `GITHUB_NOT_CONNECTED` です | | `api.UnlinkApplicationGithubApp(id)` | `c.Apps.Deploys.UnlinkGithubApp(ctx, id)` | 連携がない場合は 400 `GIT_NOT_CONFIGURED` | | `api.GetApplicationDNS(id)` | `c.Apps.Network.DNS(ctx, id)` | | | `api.SetApplicationCustomDomain(id, d)` | `c.Apps.Network.SetDomain(ctx, id, d)` | | | `api.GetApplicationAnalytics(id, s, e, opts...)` | `c.Apps.Network.Analytics(ctx, id, s, e, squarecloud.AnalyticsFilters{...})` | `*NetworkAnalytics` を返します。トラフィックのない期間では `nil` | | `api.GetApplicationNetworkErrors(id, s, e, opts...)` | `c.Apps.Network.Errors(ctx, id, s, e, include4xx)` | `*NetworkErrors` を返します。空の場合は `nil` | | `api.GetApplicationNetworkLogs(id, s, e)` | `c.Apps.Network.Logs(ctx, id, s, e)` | | | `api.GetApplicationNetworkPerformance(id, s, e)` | `c.Apps.Network.Performance(ctx, id, s, e)` | `*NetworkPerformance` を返します。空の場合は `nil` | | `api.PurgeApplicationCache(id)` | `c.Apps.Network.PurgeCache(ctx, id)` | | | `api.CreateDatabase(opts)` | `c.Databases.Create(ctx, squarecloud.DatabaseCreate{...})` | | | `api.GetDatabase(id)` | `c.Databases.Get(ctx, id)` | | | `api.UpdateDatabase(id, opts)` | `c.Databases.Update(ctx, id, squarecloud.DatabaseUpdate{...})` | | | `api.DeleteDatabase(id)` | `c.Databases.Delete(ctx, id)` | | | `api.StartDatabase(id)` / `api.StopDatabase(id)` | `c.Databases.Start(ctx, id)` / `c.Databases.Stop(ctx, id)` | | | `api.GetDatabaseStatus(id)` / `api.GetDatabaseStatusRaw(id)` | `c.Databases.Status(ctx, id)` / `c.Databases.StatusRaw(ctx, id)` | | | `api.GetDatabaseListStatus()` | `c.Databases.StatusAll(ctx)` | `[]StatusListItem` を返します | | `api.GetDatabaseMetrics(id)` | `c.Databases.Metrics(ctx, id)` | | | `api.GetDatabaseCertificate(id)` → `DatabaseCertificate` | `c.Databases.Certificate(ctx, id)` → `string` (base64 PEM) | | | `api.ResetDatabaseCredentials(id, t)` → `DatabasePasswordReset` | `c.Databases.ResetCredentials(ctx, id, t)` → `string` | 新しいパスワード。証明書のリセットでは `""` | | `api.GetDatabaseSnapshots` / `CreateDatabaseSnapshot` / `RestoreDatabaseSnapshot` | `c.Databases.Snapshots.List` / `Create` / `Restore` | アプリと同様に、`snap.Name` と `snap.VersionID` で復元します | | `api.GetWorkspaces()` | `c.Workspaces.List(ctx)` | | | `api.GetWorkspace(id)` | `c.Workspaces.Get(ctx, id)` | | | `api.CreateWorkspace(name)` | `c.Workspaces.Create(ctx, name)` | | | `api.DeleteWorkspace(id)` | `c.Workspaces.Delete(ctx, id)` | | | `api.LeaveWorkspace(id)` | `c.Workspaces.Leave(ctx, id)` | | | `api.AddWorkspaceMember(ws, code, group)` | `c.Workspaces.Members.Add(ctx, ws, code, group)` | | | `api.UpdateWorkspaceMember(ws, member, group)` | `c.Workspaces.Members.Update(ctx, ws, member, group)` | | | `api.RemoveWorkspaceMember(ws, member)` | `c.Workspaces.Members.Remove(ctx, ws, member)` | | | `api.GetWorkspaceInviteCode()` → `WorkspaceInviteCode` | `c.Workspaces.Members.InviteCode(ctx)` → `string` | | | `api.AddWorkspaceApplication(ws, app)` / `RemoveWorkspaceApplication` | `c.Workspaces.Apps.Add(ctx, ws, app)` / `Remove` | | | snapshot の URL を自分でダウンロード (`http.Get`) | `c.DownloadSnapshot(ctx, url, w)` | 任意の `io.Writer` にストリーミングします。キーは決して送信されません | | `rest.IsRateLimit(err)` | `errors.As(err, &apiErr) && apiErr.Status == 429` | 削除 | | `rest.ErrorCode(err)` | `errors.As(err, &apiErr)`、その後 `apiErr.Code` | 削除 | | `client.Request(...)`, `client.Stream(...)` (`rest.Client`) | 上記の型付きメソッド | 削除: すべての操作に専用のメソッドがあります | | `rest.NewApplications(client)`, `rest.NewDatabases(client)`, `rest.NewWorkspaces(client)` | `squarecloud.New(key)`、その後 `c.Apps`、`c.Databases`、`c.Workspaces` フィールド | 削除 | | `rest.Applications`, `rest.Databases`, `rest.Workspaces` (インターフェース) | `squarecloud.AppsAPI`, `DatabasesAPI`, `WorkspacesAPI` (それらのフィールドの型) | 削除。モックするには独自のインターフェースを宣言します | | `rest.Config`, `rest.DefaultConfig()`, `(*rest.Config).Apply(opts)` | `WithHTTPClient`、`WithBaseURL`、`WithUserAgent` を指定した `squarecloud.New(key, opts...)` | 削除 (`Option` を使用。ロガーはありません) | | `(*rest.RequestConfig).Apply(opts)` | `ctx` と型付きの引数を渡します | 削除 | | `(*rest.RealtimeStream).Next()` / `Close()` | `(*squarecloud.Realtime).Next()` / `Close()` | `Next` は `REALTIME_DISCONNECTED` の後に `io.EOF` を返します | | (なし) | `c.AI.Chat(ctx, squarecloud.ChatRequest{...})` | 新規 | ## 型 | v2 (`squarecloud.`) | v3 (`squarecloud.`) | | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `User` (`SelfUser` から) | `User` (`Account.Me` の結果である `Account` の中) | | `UserPlan`, `UserPlanMemory` | `Plan`, `PlanMemory`。`Plan.Duration` は Unix **ミリ秒**での有効期限です (`*int64`。失効しない場合は `nil`)。`time.Unix` ではなく `time.UnixMilli` で変換してください | | `UserApplication`, `UserDatabase` (`Type string`) | `AppSummary`, `DatabaseSummary` (`Type DatabaseType`) | | `Application` | `App` | | `ApplicationUploaded` (`CPU int`), `ApplicationLanguage` | `AppCreated` (`CPU float64`), `AppLanguage` | | `ApplicationStatus`, `DatabaseStatus` | `RuntimeStats` (共通) | | `ApplicationStatusRaw`, `DatabaseStatusRaw` | `RuntimeStatsRaw` | | `ApplicationStatusNetwork`, `ApplicationStatusNetworkRaw` | `StatsNetwork`, `StatsNetworkRaw` | | `ApplicationStatusListItem`, `DatabaseStatusListItem` | `StatusListItem` | | `ApplicationLogs` | `string` | | `ApplicationSignal*` | 削除 (`Start`/`Stop`/`Restart` を使用) | | `FileInfo` (`Type FileType`, `LastModified int64`), `FileType*` 定数 | `FileEntry` (`Type string`, `LastModified *float64`): `"file"`/`"directory"`。API は小数を含む Unix ミリ秒、または `null` を送ります | | `FileContent`, `ByteArray` | `[]byte` | | `FileWritten` | 削除 (ドキュメント化されていないフィールド) | | `Deployment` (`State DeploymentState`) | `DeployEvent` (`State`、`Source`、`Code`、`Message` は `string`)。`Source` は新規で、常に `"git"` です。`"error"` イベントは `Code` (例: `CLONE_FAILED`) を持ち、`Message` を持つこともあります | | `DeploymentState*` (`DeploymentStateError` = `"error"`) | `Deploy*` 文字列定数 (`DeployPending`、`DeployClone`、`DeployCommit`、`DeployRestarting`、`DeploySuccess`、`DeployError` = `"error"`) | | `DeploymentFiles`, `DeploymentCurrent`, `DeploymentGithubApp` | `DeployFiles`, `DeployCurrent`, `DeployRepository` | | `GithubWebhook` | `string` | | `GithubAppLink`, `GithubAppRepository` | `ID`、`FullName`、`Branch` を持つ `LinkedRepository` (`Repository` ラッパーなしで直接返されます) | | `Snapshot` | `Snapshot` + `VersionID`、`URL`、`Runtime`、`Origin` (API が送るすべてのフィールド) | | `SnapshotCreated` | `SnapshotCreated` + `Pending` | | `DatabaseTypeMongo`、`DatabaseTypeMySQL`、`DatabaseTypeRedis`、`DatabaseTypePostgres` を持つ `DatabaseType` | `DatabaseMongo`、`DatabaseMySQL`、`DatabaseRedis`、`DatabasePostgres` を持つ `DatabaseType` (型は変更なし、定数は名前を変更) | | `DatabaseCreateOptions`, `DatabaseUpdateOptions` | `DatabaseCreate`, `DatabaseUpdate` | | `DatabaseCreated` (`CPU int`, `Certificate string`) | `DatabaseCreated` (`CPU float64`, `Certificate *string`。API が何も送らない場合は `nil`) | | `DatabaseResetType`, `DatabaseResetPassword`, `DatabaseResetCertificate` | `DatabaseReset`, `ResetPassword`, `ResetCertificate` | | `DatabaseCertificate`, `DatabasePasswordReset` | `string` | | `WorkspaceMemberGroup`, `WorkspaceGroup*` | 入力: `WorkspaceGroup` (`GroupAdmin`、`GroupMaintain`、`GroupManager`、`GroupView`)。`WorkspaceMember.Group` は `string` です (`"owner"` の場合があります) | | `WorkspaceMember` (`Name string`) | `WorkspaceMember` (`Name *string`。API が `null` を送った場合は `nil`)。Workspace の ID は 16 進数 32 文字または 40 文字です | | `WorkspaceInviteCode` | `string` | | `ServiceStatus` (`Status`, `Message`) | `ServiceStatus` (`Status`、`Message`、`CheckedAt`、`Stale`、`Services`、`Dependencies`)。`Status` は `"online"` などの値になりました。各エントリは `ServiceEntry` です | | `rest.RealtimeStream` | `*squarecloud.Realtime` (`Next`, `Close`) | | `RealtimeEvent` (`Event`, `Data`) | `RealtimeEvent` (`Event`, `Data`, `ID`, `Stream`, `Line`, `Status`) | | アナリティクスのクエリオプション | `AnalyticsFilters` (`Start`/`End` はなし: 引数として渡します) | | `NetworkErrorsSummaryClass` (`Class4xx`, `Class5xx`) | `NetworkErrorsSummary.ByClass`。キー `"4xx"` と `"5xx"` を持つ `map[string]int64` | | `NetworkErrorsByStatus`, `NetworkErrorsTimeseries`, `NetworkErrorsTopPath`, `NetworkErrorsByMethod` | `NetworkErrorsStatus`, `NetworkErrorsBucket`, `NetworkErrorsPath`, `NetworkErrorsMethod` | | `NetworkLatency`, `NetworkPerformance*` | `Percentiles` (`P50`/`P95`/`P99` は `*float64` で、リクエストのない期間では `nil`)、`PerformanceSummary`、`PerformanceBucket`、`PerformanceRegion` (国とコロケーション。`P50`/`P95` は `*float64`、`City`/`Country` は `*string`)、`PerformancePath` (`P95`/`P99` は `*float64`) | | `RealtimeStatus` | `RealtimeStatus.CPULimit` はコア数です (例: `1`、`0.5`) | | アナリティクスのプロバイダーの値 | `"NAME (ASN)"` (例: `"GOOGLE (15169)"`)。`AnalyticsFilters.Provider` はその値をそのまま受け取ります | | `AppDomainType*` | `AppDomain.Type` は `string` です | | `APIResponse[T]` | 削除 (内部用) | | `int` のサイズとカウンター (`FileInfo.Size`、`Snapshot.Size`、アナリティクスの `Visits`/`Requests`、ネットワークエラーの合計とマップ、パフォーマンスの `Requests`) | `int64` | ## エラー `rest.APIError` (`StatusCode`, `Code`, `Message`) は `squarecloud.APIError` (`Status`, `Code`, `Message`, `Method`, `Path`) になります。`StatusCode` を `Status` に名前変更してください。`rest.ErrorCode(err)` と `rest.IsRateLimit(err)` は削除されました。`errors.As` を使い、`Code` または `Status == 429` を確認してください。 ```go theme={"system"} // 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 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: : HTTP : ` を出力します (v2: `squarecloud: (, HTTP )`)。テキストではなく、フィールドで判定してください。 完全なリファレンスは[エラー](/ja/sdks/go/errors)を参照してください。 ## 動作の変更 * **空の 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 秒待ち、接続を開く処理はヘッダーが届くまでクライアントのタイムアウトで制限されます。[リアルタイム](/ja/sdks/go/realtime)を参照してください。 * **タイムアウト:** 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 はほかのメソッドでは決してリトライしません。必要であれば、冪等な変更は自分でリトライしてください。[リトライ](/ja/sdks/go/errors#リトライ)を参照してください。 * **Go のバージョン:** 最小バージョンが Go 1.24 から Go 1.22 に下がりました。