Restore は復元がまだ実行中かどうかを伝えるようになり、Metrics は期間の引数を取るようになりました。それ以外はすべて追加です: 2 つの新しい操作 (合計 69 個)、新しいフィールド、新しいエラーコード。
概要
インポートパス
変わるのはインポートパスだけです。New とすべての Option はシグネチャとデフォルトを維持し、デフォルトの User-Agent は squarecloud-sdk-go/4.0.0 になります。
破壊的変更
以下のサンプルは、error を返す関数の中で実行します。
Snapshot の復元
Apps.Snapshots.Restore と Databases.Snapshots.Restore は、error ではなく (SnapshotRestored, error) を返します。約 90 秒以上かかる復元は、呼び出しが戻った後も実行を続けます。v3 はその場合に nil を返していたため、呼び出し側はまだ実行中なのに「復元済み」と報告していました。v4 はその場合に Pending: true を返し、完了した復元には Pending: false を返します。
RestoreState は、復元の実行中は現在の Step とともに queued または running を報告し、終了後 1 時間は Code とともに success または error を報告します。その 1 時間が過ぎた後、または最近の復元がない場合は none を報告します。1 分あたり 30 回まで呼び出せます。Snapshot を参照してください。
メトリクス
Apps.Metrics と Databases.Metrics は、最後の引数に期間を取ります。直近 24 時間を対象とする v3 の動作を維持するには "" を渡します。
"7d" は、Pro と Enterprise プランの 512 MB 以上のアプリで、その時間の平均値とピーク値 CPUMax、RAMMax を含む 1 時間ごとのポイントを返します。その他のプランや小さなアプリではエラーにならずに 24 時間分の結果が返されるため、7 日間と決めつけずにポイントを確認してください。それ以外の期間は 400 INVALID_PARAMETERS を返します。データベースでは、"7d" に Pro または Enterprise プランが必要です。メトリクスを参照してください。
RESTORE_IN_PROGRESS は 409 に
アプリとデータベースの削除、データベースの起動と停止では、RESTORE_IN_PROGRESS が 403 から 409 に変わりました。アプリの起動、停止、再起動、snapshot の Create と Restore でも、409 として新たに返されます。コードだけで判定してください:
新しい型とフィールド
新しいフィールドが壊すのは、これらの型の構造体リテラルのうち、フィールド名を省略したものだけです。フィールド名を使ってください。
エラー
- 新しい定数:
CodeAIWeeklyLimitReached、CodeEnvBusy(409)、CodeGitBranchDeletedとCodeGitRefNotSupported(GitHub の push webhook にのみ送信されます)、CodeRestoreInterrupted、CodeSnapshotsUnavailable(503)、CodeSnapshotCorrupt、CodeSnapshotInProgress(409)、CodeSnapshotRestoreProcessing(エラーではなくSnapshotRestored.Pendingとして報告されます)、CodeWriteFailed、CodeWrongHost(421。この SDK の呼び出しに返されることはありません)。 CodeMetricsNotSupportedは非推奨ですが、残されています。- 復元は
SNAPSHOT_RESTORE_FAILED以外のコードでも失敗することがあります。完全な一覧は Snapshot を参照してください。 - SDK は新しいコードをどれもリトライしません。
SNAPSHOTS_UNAVAILABLEは約 30 秒待つよう求め、CLUSTER_MAINTENANCE_TRY_LATERは数分間続くため、どちらもリトライの待機時間より長くなります。使用中のリソースによる 409 をどう扱うかは、あなたが決めます。 - SDK 独自のエラー
INVALID_API_KEY、INVALID_ID、FILE_TOO_LARGEには、何が問題でどう直せばよいかを説明する新しいメッセージが付きました。MessageではなくCodeを比較してください。
動作の変更
- Snapshot のリンクは 1 時間で失効します。 以前は 30 日間有効だったため、snapshot を一覧または作成したらすぐにダウンロードしてください。API キーに
snapshots:readがない場合に、Pending: falseで空のURLとKeyを返すことがあるのはCreateだけです。 - Snapshot の一覧 (
Account.Snapshots、Apps.Snapshots.List、Databases.Snapshots.List) は、snapshot のストレージが応答できない場合、空のリストではなく 503SNAPSHOTS_UNAVAILABLEを返します。 - メトリクス: 以前は 400
METRICS_NOT_SUPPORTEDを受け取っていた 512 MB 未満のアプリにも、10 分ごとに 1 ポイントのメトリクスが提供されるようになりました。 - 環境変数:
Envs.Set、Envs.Replace、Envs.Deleteは、別の書き込みが進行中の場合に 409ENV_BUSYを返します。API キーにenvs:readがない場合、Envs.Setは全体のセットではなく送信した変数だけを返し、Envs.Deleteは空のセットを返します。 - ファイル:
Files.ReadとFiles.Writeは 400READ_FAILEDとWRITE_FAILEDを、Commitは 403BLOCKED_PATHを返すことがあります。 - 並列アップロード: API は、1 つのアカウントが同時に送信できる大きなアップロードの数を制限しています。上限を超えると 429
RATE_LIMITEDが返され、SDK はこれを決してリトライしません。 - AI:
AI.Chatの 429 はweekly_limit_reachedの場合があります。 - User-Agent は
squarecloud-sdk-go/4.0.0です。
チェックリスト
1
インポートパスを変更する
すべての箇所で
github.com/squarecloudofc/sdk-api-go/v4 をインポートし、go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0 を実行します。2
保留中の復元を追跡する
err := c.Apps.Snapshots.Restore(...) を res, err := ... に置き換えます。res.Pending が true の場合は、State が success または error になるまで、たとえば 10 秒ごとに RestoreState をポーリングします。復元を再度送信しないでください。3
Metrics に期間を渡す
Apps.Metrics と Databases.Metrics の最後の引数に ""、"24h"、"7d" のいずれかを追加します。4
409 RESTORE_IN_PROGRESS で判定する
403 で判定していた箇所を 409 に変えるか、コードだけで判定します。5
503 SNAPSHOTS_UNAVAILABLE を処理する
空のリストを「snapshot なし」と解釈するのではなく、snapshot の一覧でこのエラーを処理します。
6
メッセージではなくコードを比較する
INVALID_API_KEY、INVALID_ID、FILE_TOO_LARGE の Message を比較していた箇所では、Code を確認します。次のステップ
クライアント
SDK をインストールしてクライアントを作成します。
Snapshot
snapshot を作成、復元、追跡します。
エラー
エラークラス、リトライ、レート制限。

