メインコンテンツへスキップ
v4 は、2 つのシグネチャが変わるため破壊的変更を含むリリースです。snapshot の 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 のストレージが応答できない場合、空のリストではなく 503 SNAPSHOTS_UNAVAILABLE を返します。
  • メトリクス: 以前は 400 METRICS_NOT_SUPPORTED を受け取っていた 512 MB 未満のアプリにも、10 分ごとに 1 ポイントのメトリクスが提供されるようになりました。
  • 環境変数: Envs.Set、Envs.Replace、Envs.Delete は、別の書き込みが進行中の場合に 409 ENV_BUSY を返します。API キーに envs:read がない場合、Envs.Set は全体のセットではなく送信した変数だけを返し、Envs.Delete は空のセットを返します。
  • ファイル: Files.Read と Files.Write は 400 READ_FAILED と WRITE_FAILED を、Commit は 403 BLOCKED_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 を作成、復元、追跡します。

エラー

エラークラス、リトライ、レート制限。