> ## 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.

# Go SDK: v3 から v4 への移行

> Square Cloud Go SDK を v3 から v4 へアップグレード: /v4 のインポートパス、実行中の復元を報告する snapshot の Restore、期間を取る Metrics、409 RESTORE_IN_PROGRESS。

v4 は、2 つのシグネチャが変わるため破壊的変更を含むリリースです。snapshot の `Restore` は復元がまだ実行中かどうかを伝えるようになり、`Metrics` は期間の引数を取るようになりました。それ以外はすべて追加です: 2 つの新しい操作 (合計 69 個)、新しいフィールド、新しいエラーコード。

## 概要

| | v3 | v4 |
| - | - | - |
| モジュール | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| 操作 | 67 | 69。`Apps.Snapshots.RestoreState` と `Databases.Snapshots.RestoreState` を追加 |
| Snapshot の復元 | `Restore(ctx, id, name, versionID) error`。約 90 秒経っても実行中の復元に対して、完了したかのように `nil` を返していました | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`。復元の実行中は `Pending` が `true` で、`RestoreState` で追跡します |
| メトリクス | `Metrics(ctx, id)`。直近 24 時間のみ | `Metrics(ctx, id, rng)`。`rng` は `""` または `"24h"`、ピーク値を含む 1 時間ごとのポイントには `"7d"` |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | API が送信 | 非推奨: API はもう送信しません |
| Go のバージョンと依存関係 | Go 1.22、依存関係なし | 変更なし |

## インポートパス

変わるのはインポートパスだけです。`New` とすべての `Option` はシグネチャとデフォルトを維持し、デフォルトの `User-Agent` は `squarecloud-sdk-go/4.0.0` になります。

```diff theme={"system"}
-import "github.com/squarecloudofc/sdk-api-go/v3"
+import "github.com/squarecloudofc/sdk-api-go/v4"
```

```bash theme={"system"}
go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0
```

## 破壊的変更

以下のサンプルは、`error` を返す関数の中で実行します。

### Snapshot の復元

`Apps.Snapshots.Restore` と `Databases.Snapshots.Restore` は、`error` ではなく `(SnapshotRestored, error)` を返します。約 90 秒以上かかる復元は、呼び出しが戻った後も実行を続けます。v3 はその場合に `nil` を返していたため、呼び出し側はまだ実行中なのに「復元済み」と報告していました。v4 はその場合に `Pending: true` を返し、完了した復元には `Pending: false` を返します。

```go theme={"system"}
// v3
if err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID); err != nil {
	return err
}

// v4
res, err := c.Apps.Snapshots.Restore(ctx, appID, snap.Name, snap.VersionID)
if err != nil {
	return err
}
for res.Pending { // still running: follow it, never send the restore again
	time.Sleep(10 * time.Second)
	st, err := c.Apps.Snapshots.RestoreState(ctx, appID)
	if err != nil {
		return err
	}
	if st.State == "error" {
		return fmt.Errorf("restore failed: %s", st.Code)
	}
	res.Pending = st.State == "queued" || st.State == "running"
}
```

`RestoreState` は、復元の実行中は現在の `Step` とともに `queued` または `running` を報告し、終了後 1 時間は `Code` とともに `success` または `error` を報告します。その 1 時間が過ぎた後、または最近の復元がない場合は `none` を報告します。1 分あたり 30 回まで呼び出せます。[Snapshot](https://docs.squarecloud.app/ja/sdks/go/snapshots.md#復元の追跡) を参照してください。

### メトリクス

`Apps.Metrics` と `Databases.Metrics` は、最後の引数に期間を取ります。直近 24 時間を対象とする v3 の動作を維持するには `""` を渡します。

```go theme={"system"}
// v3
points, err := c.Apps.Metrics(ctx, appID)

// v4
points, err := c.Apps.Metrics(ctx, appID, "") // "" or "24h": the last 24 hours
```

`"7d"` は、Pro と Enterprise プランの 512 MB 以上のアプリで、その時間の平均値とピーク値 `CPUMax`、`RAMMax` を含む 1 時間ごとのポイントを返します。その他のプランや小さなアプリではエラーにならずに 24 時間分の結果が返されるため、7 日間と決めつけずにポイントを確認してください。それ以外の期間は 400 `INVALID_PARAMETERS` を返します。データベースでは、`"7d"` に Pro または Enterprise プランが必要です。[メトリクス](https://docs.squarecloud.app/ja/sdks/go/managing_application.md#メトリクス)を参照してください。

### `RESTORE_IN_PROGRESS` は 409 に

アプリとデータベースの削除、データベースの起動と停止では、`RESTORE_IN_PROGRESS` が 403 から 409 に変わりました。アプリの起動、停止、再起動、snapshot の `Create` と `Restore` でも、409 として新たに返されます。コードだけで判定してください:

```go theme={"system"}
var apiErr *squarecloud.APIError

// v3
if errors.As(err, &apiErr) && apiErr.Status == 403 && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running
}

// v4
if errors.As(err, &apiErr) && apiErr.Code == squarecloud.CodeRestoreInProgress {
	// a snapshot restore is running (HTTP 409)
}
```

## 新しい型とフィールド

| 型 | v4 での追加 |
| - | - |
| `SnapshotRestored` | 新規: `Pending bool`。`Restore` が返します |
| `SnapshotRestoreState` | 新規: `State`、`Step`、`Code` (`string`)、`StartedAt` と `FinishedAt` (`*int64`、Unix ミリ秒)。`RestoreState` が返します |
| `ServiceStatus` | 進行中のインシデントとメンテナンスを表す `Incidents []ServiceIncident` と、完全には機能していないプラットフォームの部分を表す `Components []ServiceComponent`。`Status` は `"maintenance"` になることがあり、`"unknown"` はチェックを実行できなかったことを意味します |
| `MetricPoint` | 最後の起動以降に読み取り・書き込みしたバイト数の `Disk []int64` と、ディスク上のバイト数の `Storage *int64`。どちらも計測値のないポイントでは `nil` です。1 時間ごとのピーク値の `CPUMax` と `RAMMax *float64` は、`"7d"` の場合のみ設定されます |
| `RuntimeStats`, `RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | レコードがまだ有効になっていない理由を説明する最大 3 つのメッセージの `Errors []string` と、すべての SSL 用 TXT レコードの代わりになる 1 つの `_acme-challenge` CNAME を示す `Fallback bool` |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxTokens` より優先される `MaxCompletionTokens int` |

新しいフィールドが壊すのは、これらの型の構造体リテラルのうち、フィールド名を省略したものだけです。フィールド名を使ってください。

## エラー

* 新しい定数: `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](https://docs.squarecloud.app/ja/sdks/go/snapshots.md#snapshot-の復元) を参照してください。
* SDK は新しいコードをどれもリトライしません。`SNAPSHOTS_UNAVAILABLE` は約 30 秒待つよう求め、`CLUSTER_MAINTENANCE_TRY_LATER` は数分間続くため、どちらもリトライの待機時間より長くなります。使用中のリソースによる 409 をどう扱うかは、あなたが決めます。
* SDK 独自のエラー `INVALID_API_KEY`、`INVALID_ID`、`FILE_TOO_LARGE` には、何が問題でどう直せばよいかを説明する新しいメッセージが付きました。`Message` ではなく `Code` を比較してください。

完全なリファレンスは[エラー](https://docs.squarecloud.app/ja/sdks/go/errors.md)を参照してください。

## 動作の変更

* **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` を確認します。

## 次のステップ

> [card] [クライアント](https://docs.squarecloud.app/ja/sdks/go/client.md)
>
> SDK をインストールしてクライアントを作成します。

> [card] [Snapshot](https://docs.squarecloud.app/ja/sdks/go/snapshots.md)
>
> snapshot を作成、復元、追跡します。

> [card] [エラー](https://docs.squarecloud.app/ja/sdks/go/errors.md)
>
> エラークラス、リトライ、レート制限。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.