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

# SDK Go: migrazione da v3 a v4

> Aggiorna l'SDK Go dalla v3 alla v4: il percorso di import /v4, un Restore degli snapshot che segnala un ripristino in corso, Metrics con un range e 409 RESTORE_IN_PROGRESS.

La v4 è una release con breaking change perché cambiano due firme. `Restore` degli snapshot ora ti dice se il ripristino è ancora in corso, e `Metrics` accetta un range. Tutto il resto è un'aggiunta: due nuove operazioni, per un totale di 69, nuovi campi e nuovi codici di errore.

## In sintesi

| | v3 | v4 |
| - | - | - |
| Modulo | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| Operazioni | 67 | 69, con l'aggiunta di `Apps.Snapshots.RestoreState` e `Databases.Snapshots.RestoreState` |
| Ripristino degli snapshot | `Restore(ctx, id, name, versionID) error`. Un ripristino ancora in corso dopo circa 90 secondi restituiva `nil`, come se fosse terminato | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`. `Pending` è `true` finché il ripristino continua, e `RestoreState` lo segue |
| Metriche | `Metrics(ctx, id)`, solo per le ultime 24 ore | `Metrics(ctx, id, rng)`, dove `rng` è `""` o `"24h"`, oppure `"7d"` per punti orari con i picchi |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | Inviato dall'API | Deprecato: l'API non lo invia più |
| Versione di Go e dipendenze | Go 1.22, nessuna dipendenza | Invariate |

## Percorso di import

Cambia solo il percorso di import. `New` e ogni `Option` mantengono le loro firme e i loro valori predefiniti, e lo `User-Agent` predefinito diventa `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
```

## Breaking change

Gli esempi qui sotto vengono eseguiti all'interno di una funzione che restituisce un `error`.

### Ripristino degli snapshot

`Apps.Snapshots.Restore` e `Databases.Snapshots.Restore` restituiscono `(SnapshotRestored, error)` invece di `error`. Un ripristino che dura più di circa 90 secondi continua dopo il ritorno della chiamata. La v3 restituiva `nil` in quel caso, quindi chi chiamava segnalava "ripristinato" mentre era ancora in corso. La v4 restituisce `Pending: true` in quel caso, e `Pending: false` per un ripristino terminato.

```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` riporta `queued` o `running` mentre il ripristino è in corso, con lo `Step` attuale, poi `success` o `error`, con un `Code`, per 1 ora dopo la fine. Riporta `none` trascorsa quell'ora o quando non c'è stato un ripristino recente. Consente 30 chiamate al minuto. Vedi [Snapshot](https://docs.squarecloud.app/it/sdks/go/snapshots.md#seguire-un-ripristino).

### Metriche

`Apps.Metrics` e `Databases.Metrics` accettano un range come ultimo argomento. Passa `""` per mantenere il comportamento della v3, che copre le ultime 24 ore.

```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"` restituisce punti orari con la media dell'ora e i suoi picchi `CPUMax` e `RAMMax`, sui piani Pro ed Enterprise per le app da 512 MB o più. Gli altri piani e le app più piccole ricevono la risposta di 24 ore senza errori, quindi controlla i punti invece di dare per scontati 7 giorni. Qualsiasi altro range restituisce 400 `INVALID_PARAMETERS`. Per i database, `"7d"` richiede un piano Pro o Enterprise. Vedi [Metriche](https://docs.squarecloud.app/it/sdks/go/managing_application.md#metriche).

### `RESTORE_IN_PROGRESS` è 409

`RESTORE_IN_PROGRESS` è passato da 403 a 409 sull'eliminazione di app e database e sull'avvio e l'arresto dei database. È anche nuovo, come 409, sull'avvio, l'arresto e il riavvio delle app e su `Create` e `Restore` degli snapshot. Confronta solo il codice:

```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)
}
```

## Nuovi tipi e campi

| Tipo | Novità nella v4 |
| - | - |
| `SnapshotRestored` | Nuovo: `Pending bool`, restituito da `Restore` |
| `SnapshotRestoreState` | Nuovo: `State`, `Step` e `Code` (`string`), `StartedAt` e `FinishedAt` (`*int64`, ms Unix), restituito da `RestoreState` |
| `ServiceStatus` | `Incidents []ServiceIncident`, gli incidenti e le finestre di manutenzione aperti, e `Components []ServiceComponent`, le parti della piattaforma che non funzionano pienamente. `Status` può valere `"maintenance"`, e `"unknown"` significa che il controllo non è stato possibile |
| `MetricPoint` | `Disk []int64`, i byte letti e scritti dall'ultimo avvio, e `Storage *int64`, i byte su disco, entrambi `nil` su un punto senza una lettura. `CPUMax` e `RAMMax *float64`, i picchi orari, impostati solo con `"7d"` |
| `RuntimeStats`, `RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | `Errors []string`, fino a 3 messaggi che spiegano perché un record non è ancora attivo, e `Fallback bool`, che indica l'unico CNAME `_acme-challenge` che può sostituire tutti i record TXT dell'SSL |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxCompletionTokens int`, che ha la precedenza su `MaxTokens` |

I nuovi campi rompono solo i literal struct di questi tipi che omettono i nomi dei campi. Usa i nomi dei campi.

## Errori

* Nuove costanti: `CodeAIWeeklyLimitReached`, `CodeEnvBusy` (409), `CodeGitBranchDeleted` e `CodeGitRefNotSupported` (inviati solo ai webhook di push di GitHub), `CodeRestoreInterrupted`, `CodeSnapshotsUnavailable` (503), `CodeSnapshotCorrupt`, `CodeSnapshotInProgress` (409), `CodeSnapshotRestoreProcessing` (riportato come `SnapshotRestored.Pending`, mai come errore), `CodeWriteFailed` e `CodeWrongHost` (421, mai restituito alle chiamate di questo SDK).
* `CodeMetricsNotSupported` è deprecato ma resta.
* Un ripristino può fallire con più codici oltre a `SNAPSHOT_RESTORE_FAILED`. Vedi [Snapshot](https://docs.squarecloud.app/it/sdks/go/snapshots.md#ripristinare-uno-snapshot) per l'elenco completo.
* L'SDK non ripete nessuno dei nuovi codici. `SNAPSHOTS_UNAVAILABLE` chiede di attendere circa 30 secondi e `CLUSTER_MAINTENANCE_TRY_LATER` dura alcuni minuti, entrambi più a lungo delle attese dei retry. Un 409 di una risorsa occupata lo gestisci tu.
* Gli errori propri dell'SDK, `INVALID_API_KEY`, `INVALID_ID` e `FILE_TOO_LARGE`, hanno nuovi messaggi che dicono cosa è andato storto e come risolverlo. Confronta `Code`, non `Message`.

Vedi [Errori](https://docs.squarecloud.app/it/sdks/go/errors.md) per il riferimento completo.

## Cambiamenti di comportamento

* **I link degli snapshot scadono dopo 1 ora.** Prima duravano 30 giorni, quindi scarica subito dopo aver elencato o creato uno snapshot. Solo `Create` può restituire `URL` e `Key` vuoti, con `Pending: false`, quando la chiave API non ha `snapshots:read`.
* **Gli elenchi di snapshot** (`Account.Snapshots`, `Apps.Snapshots.List` e `Databases.Snapshots.List`) restituiscono 503 `SNAPSHOTS_UNAVAILABLE` invece di un elenco vuoto quando lo storage degli snapshot non riesce a rispondere.
* **Metriche.** Le app sotto i 512 MB ora hanno le metriche, con un punto ogni 10 minuti, dove prima ricevevano 400 `METRICS_NOT_SUPPORTED`.
* **Variabili d'ambiente.** `Envs.Set`, `Envs.Replace` e `Envs.Delete` restituiscono 409 `ENV_BUSY` quando è in corso un'altra scrittura. Con una chiave API priva di `envs:read`, `Envs.Set` restituisce solo le variabili che hai inviato, non l'insieme completo, e `Envs.Delete` restituisce un insieme vuoto.
* **File.** `Files.Read` e `Files.Write` possono restituire 400 `READ_FAILED` e `WRITE_FAILED`, e `Commit` può restituire 403 `BLOCKED_PATH`.
* **Upload in parallelo.** L'API limita quanti upload grandi un account può inviare contemporaneamente. Superare il limite restituisce 429 `RATE_LIMITED`, che l'SDK non ripete mai.
* **AI.** Un 429 da `AI.Chat` può essere `weekly_limit_reached`.
* **User-Agent** è `squarecloud-sdk-go/4.0.0`.

## Checklist

**1. Cambia il percorso di import**

Importa `github.com/squarecloudofc/sdk-api-go/v4` ovunque ed esegui `go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0`.

**2. Segui i ripristini in sospeso**

Sostituisci `err := c.Apps.Snapshots.Restore(...)` con `res, err := ...`. Quando `res.Pending` è `true`, interroga `RestoreState`, ad esempio ogni 10 secondi, finché `State` non è `success` o `error`. Non inviare mai di nuovo il ripristino.

**3. Passa un range a Metrics**

Aggiungi `""`, `"24h"` o `"7d"` come ultimo argomento di `Apps.Metrics` e `Databases.Metrics`.

**4. Confronta 409 RESTORE\_IN\_PROGRESS**

Confronta `409` dove confrontavi `403`, oppure confronta solo il codice.

**5. Gestisci 503 SNAPSHOTS\_UNAVAILABLE**

Gestiscilo sugli elenchi di snapshot, invece di leggere un elenco vuoto come "nessuno snapshot".

**6. Confronta i codici, non i messaggi**

Controlla `Code` ovunque confrontavi il `Message` di `INVALID_API_KEY`, `INVALID_ID` o `FILE_TOO_LARGE`.

## Prossimi passi

> [card] [Client](https://docs.squarecloud.app/it/sdks/go/client.md)
>
> Installa l'SDK e crea un client.

> [card] [Snapshot](https://docs.squarecloud.app/it/sdks/go/snapshots.md)
>
> Crea, ripristina e segui gli snapshot.

> [card] [Errori](https://docs.squarecloud.app/it/sdks/go/errors.md)
>
> Classe di errore, retry e rate limit.


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