> ## 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 : migrer de la v3 à la v4

> Passez le SDK Go de la v3 à la v4 : le chemin d'import /v4, un Restore de snapshot qui signale une restauration en cours, Metrics avec une plage et 409 RESTORE_IN_PROGRESS.

La v4 est une version incompatible, car deux signatures changent. Le `Restore` des snapshots indique désormais si la restauration est toujours en cours, et `Metrics` prend une plage. Tout le reste vient s'ajouter : deux nouvelles opérations, soit 69 au total, de nouveaux champs et de nouveaux codes d'erreur.

## En un coup d'œil

| | v3 | v4 |
| - | - | - |
| Module | `github.com/squarecloudofc/sdk-api-go/v3` | `github.com/squarecloudofc/sdk-api-go/v4` |
| Opérations | 67 | 69, avec `Apps.Snapshots.RestoreState` et `Databases.Snapshots.RestoreState` en plus |
| Restauration de snapshot | `Restore(ctx, id, name, versionID) error`. Une restauration encore en cours après environ 90 secondes renvoyait `nil`, comme si elle était terminée | `Restore(ctx, id, name, versionID) (SnapshotRestored, error)`. `Pending` vaut `true` tant que la restauration continue, et `RestoreState` la suit |
| Métriques | `Metrics(ctx, id)`, uniquement pour les dernières 24 heures | `Metrics(ctx, id, rng)`, où `rng` vaut `""` ou `"24h"`, ou `"7d"` pour des points horaires avec pics |
| `RESTORE_IN_PROGRESS` | HTTP 403 | HTTP 409 |
| `CodeMetricsNotSupported` | Envoyée par l'API | Dépréciée : l'API ne l'envoie plus |
| Version de Go et dépendances | Go 1.22, aucune dépendance | Inchangé |

## Chemin d'import

Seul le chemin d'import change. `New` et chaque `Option` gardent leurs signatures et leurs valeurs par défaut, et le `User-Agent` par défaut devient `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
```

## Changements incompatibles

Les exemples ci-dessous s'exécutent dans une fonction qui renvoie une `error`.

### Restauration de snapshot

`Apps.Snapshots.Restore` et `Databases.Snapshots.Restore` renvoient `(SnapshotRestored, error)` au lieu de `error`. Une restauration qui dure plus d'environ 90 secondes continue de s'exécuter après le retour de l'appel. La v3 renvoyait `nil` dans ce cas, si bien que les appelants signalaient « restauré » alors qu'elle était toujours en cours. La v4 renvoie `Pending: true` dans ce cas, et `Pending: false` pour une restauration terminée.

```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` indique `queued` ou `running` pendant la restauration, avec l'étape en cours (`Step`), puis `success` ou `error`, avec un `Code`, pendant 1 heure après la fin. Elle indique `none` après cette heure ou s'il n'y a pas eu de restauration récente. Elle autorise 30 appels par minute. Voir [Snapshots](https://docs.squarecloud.app/fr/sdks/go/snapshots.md#suivre-une-restauration).

### Métriques

`Apps.Metrics` et `Databases.Metrics` prennent une plage comme dernier argument. Passez `""` pour garder le comportement de la v3, qui couvre les dernières 24 heures.

```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"` renvoie des points horaires avec la moyenne de l'heure et ses pics `CPUMax` et `RAMMax`, sur les plans Pro et Enterprise pour les applications de 512 Mo ou plus. Les autres plans et les applications plus petites reçoivent la réponse sur 24 heures sans erreur : vérifiez donc les points au lieu de supposer 7 jours. Toute autre plage renvoie 400 `INVALID_PARAMETERS`. Pour les bases de données, `"7d"` nécessite un plan Pro ou Enterprise. Voir [Métriques](https://docs.squarecloud.app/fr/sdks/go/managing_application.md#métriques).

### `RESTORE_IN_PROGRESS` passe à 409

`RESTORE_IN_PROGRESS` est passé de 403 à 409 sur la suppression des applications et des bases de données et sur le démarrage et l'arrêt des bases de données. Il apparaît aussi, en 409, sur le démarrage, l'arrêt et le redémarrage des applications et sur `Create` et `Restore` de snapshot. Identifiez-le par le code seul :

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

## Nouveaux types et champs

| Type | Nouveau dans la v4 |
| - | - |
| `SnapshotRestored` | Nouveau : `Pending bool`, renvoyé par `Restore` |
| `SnapshotRestoreState` | Nouveau : `State`, `Step` et `Code` (`string`), `StartedAt` et `FinishedAt` (`*int64`, ms Unix), renvoyé par `RestoreState` |
| `ServiceStatus` | `Incidents []ServiceIncident`, les incidents et les fenêtres de maintenance en cours, et `Components []ServiceComponent`, les parties de la plateforme qui ne fonctionnent pas pleinement. `Status` peut valoir `"maintenance"`, et `"unknown"` signifie que la vérification n'a pas pu s'exécuter |
| `MetricPoint` | `Disk []int64`, les octets lus et écrits depuis le dernier démarrage, et `Storage *int64`, les octets sur le disque, tous deux `nil` sur un point sans relevé. `CPUMax` et `RAMMax *float64`, les pics horaires, définis uniquement avec `"7d"` |
| `RuntimeStats`, `RuntimeStatsRaw` | `Restoring bool` |
| `DNSRecord` | `Errors []string`, jusqu'à 3 messages qui indiquent pourquoi un enregistrement n'est pas encore actif, et `Fallback bool`, qui marque l'unique CNAME `_acme-challenge` pouvant remplacer tous les enregistrements TXT SSL |
| `AnalyticsTimeBucket` | `BytesIn int64` |
| `ChatRequest` | `MaxCompletionTokens int`, qui l'emporte sur `MaxTokens` |

Les nouveaux champs ne cassent que les littéraux de struct de ces types qui omettent les noms de champs. Utilisez les noms de champs.

## Erreurs

* Nouvelles constantes : `CodeAIWeeklyLimitReached`, `CodeEnvBusy` (409), `CodeGitBranchDeleted` et `CodeGitRefNotSupported` (envoyées uniquement aux webhooks de push GitHub), `CodeRestoreInterrupted`, `CodeSnapshotsUnavailable` (503), `CodeSnapshotCorrupt`, `CodeSnapshotInProgress` (409), `CodeSnapshotRestoreProcessing` (signalée par `SnapshotRestored.Pending`, jamais comme une erreur), `CodeWriteFailed` et `CodeWrongHost` (421, jamais renvoyée aux appels de ce SDK).
* `CodeMetricsNotSupported` est dépréciée mais conservée.
* Une restauration peut échouer avec d'autres codes que `SNAPSHOT_RESTORE_FAILED`. Voir [Snapshots](https://docs.squarecloud.app/fr/sdks/go/snapshots.md#restaurer-un-snapshot) pour la liste complète.
* Le SDK ne réessaie aucun des nouveaux codes. `SNAPSHOTS_UNAVAILABLE` vous demande d'attendre environ 30 secondes et `CLUSTER_MAINTENANCE_TRY_LATER` dure plusieurs minutes, deux durées plus longues que les attentes entre les nouvelles tentatives. C'est à vous de décider quoi faire d'un 409 d'une ressource occupée.
* Les erreurs propres au SDK, `INVALID_API_KEY`, `INVALID_ID` et `FILE_TOO_LARGE`, ont de nouveaux messages qui disent ce qui n'a pas fonctionné et comment y remédier. Comparez `Code`, pas `Message`.

Voir [Erreurs](https://docs.squarecloud.app/fr/sdks/go/errors.md) pour la référence complète.

## Changements de comportement

* **Les liens de snapshot expirent au bout de 1 heure.** Ils duraient auparavant 30 jours : téléchargez donc juste après avoir listé ou créé un snapshot. Seul `Create` peut renvoyer une `URL` et une `Key` vides, avec `Pending: false`, quand la clé API n'a pas `snapshots:read`.
* **Listes de snapshots :** `Account.Snapshots`, `Apps.Snapshots.List` et `Databases.Snapshots.List` renvoient 503 `SNAPSHOTS_UNAVAILABLE` au lieu d'une liste vide quand le stockage des snapshots ne peut pas répondre.
* **Métriques :** les applications de moins de 512 Mo ont désormais des métriques, avec un point toutes les 10 minutes, là où elles recevaient 400 `METRICS_NOT_SUPPORTED`.
* **Variables d'environnement :** `Envs.Set`, `Envs.Replace` et `Envs.Delete` renvoient 409 `ENV_BUSY` quand une autre écriture est en cours. Avec une clé API sans `envs:read`, `Envs.Set` ne renvoie que les variables que vous avez envoyées, et non l'ensemble complet, et `Envs.Delete` renvoie un ensemble vide.
* **Fichiers :** `Files.Read` et `Files.Write` peuvent renvoyer 400 `READ_FAILED` et `WRITE_FAILED`, et `Commit` peut renvoyer 403 `BLOCKED_PATH`.
* **Envois en parallèle :** l'API limite le nombre de gros envois qu'un compte peut effectuer en même temps. Dépasser la limite renvoie 429 `RATE_LIMITED`, que le SDK ne réessaie jamais.
* **IA :** un 429 de `AI.Chat` peut être `weekly_limit_reached`.
* **User-Agent :** `squarecloud-sdk-go/4.0.0`.

## Liste de contrôle

**1. Changez le chemin d'import**

Importez `github.com/squarecloudofc/sdk-api-go/v4` partout et lancez `go get github.com/squarecloudofc/sdk-api-go/v4@v4.0.0`.

**2. Suivez les restaurations en attente**

Remplacez `err := c.Apps.Snapshots.Restore(...)` par `res, err := ...`. Quand `res.Pending` vaut `true`, interrogez `RestoreState`, par exemple toutes les 10 secondes, jusqu'à ce que `State` vaille `success` ou `error`. Ne relancez jamais la restauration.

**3. Passez une plage à Metrics**

Ajoutez `""`, `"24h"` ou `"7d"` comme dernier argument de `Apps.Metrics` et `Databases.Metrics`.

**4. Identifiez le 409 RESTORE\_IN\_PROGRESS**

Testez `409` là où vous testiez `403`, ou testez le code seul.

**5. Gérez le 503 SNAPSHOTS\_UNAVAILABLE**

Gérez-le sur les listes de snapshots, au lieu d'interpréter une liste vide comme « aucun snapshot ».

**6. Comparez les codes, pas les messages**

Vérifiez `Code` partout où vous compariez le `Message` de `INVALID_API_KEY`, `INVALID_ID` ou `FILE_TOO_LARGE`.

## Prochaines étapes

> [card] [Client](https://docs.squarecloud.app/fr/sdks/go/client.md)
>
> Installez le SDK et créez un client.

> [card] [Snapshots](https://docs.squarecloud.app/fr/sdks/go/snapshots.md)
>
> Créez, restaurez et suivez des snapshots.

> [card] [Erreurs](https://docs.squarecloud.app/fr/sdks/go/errors.md)
>
> Classe d'erreur, nouvelles tentatives et limites de débit.


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