> ## 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. # Migrer vers la v3 > Ce qui a changé entre le SDK Go v2 et v3 : un seul paquet, un *Client concret, ctx en premier argument, des groupes de ressources, un seul type d'erreur, des timeouts et des nouvelles tentatives. Un tableau méthode par méthode. La v3 est une version incompatible. Elle utilise un seul paquet, un `*Client` concret, `ctx` en premier argument partout et des groupes de ressources, et elle corrige tous les bugs connus de la v2. Elle couvre les 67 opérations de l'API actuelle. ## En un coup d'œil | | v2 | v3 | | -------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | Module | `.../v2` (paquets `rest` + `squarecloud`) | `github.com/squarecloudofc/sdk-api-go/v3` (un seul paquet) | | Client | `rest.New(rest.NewClient(key, ...))` (interface) | `squarecloud.New(key, ...Option)` (`*Client`) | | Appels | `api.GetApplicationStatus(id, rest.WithContext(ctx))` | `c.Apps.Status(ctx, id)` | | Erreurs | `*rest.APIError` avec `StatusCode`, erreurs réseau non typées | `*squarecloud.APIError` avec `Status`, `Code`, `Message`, `Method`, `Path` pour tout | | Timeouts | `http.Client` avec un `Timeout` fixe de 30 s sur tout | Par appel via `ctx` ; `WithTimeout` ; flux sans limite | | Nouvelles tentatives | Aucune | Erreurs réseau sur GET et 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY`/`DATABASE_UNAVAILABLE` (`WithMaxRetries`) | | Logs | `WithLogger` (fuite de secrets) | Aucun | | Go | 1.24 | 1.22 ou plus récent | | Licence | AGPL-3.0 | MIT | ## Construction et options ```diff theme={"system"} -import ( - "github.com/squarecloudofc/sdk-api-go/v2/rest" - "github.com/squarecloudofc/sdk-api-go/v2/squarecloud" -) -client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger)) -api := rest.New(client) -defer client.Close() +import "github.com/squarecloudofc/sdk-api-go/v3" + +c := squarecloud.New(token, squarecloud.WithUserAgent(ua)) ``` ```bash theme={"system"} go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0 ``` | v2 | v3 | | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Paquets `rest` + `squarecloud` | Un seul paquet `squarecloud` (module `.../v3`) | | `rest.NewClient(token, opts...)` + `rest.New(client)` | `squarecloud.New(token, opts...)` | | `rest.Rest` (interface) | `*squarecloud.Client` (struct concrète). Pour le simuler, déclarez votre propre petite interface ou utilisez `httptest` | | `rest.ConfigOpt` | `squarecloud.Option` | | `rest.WithHTTPClient(hc)` | `squarecloud.WithHTTPClient(hc)`. Ne définissez pas `hc.Timeout` : il couperait les flux temps réel et les téléchargements | | `rest.WithURL(u)` | `squarecloud.WithBaseURL(u)` (inclut toujours `/v2`) | | `rest.WithUserAgent(ua)` | `squarecloud.WithUserAgent(ua)` | | `rest.WithLogger(l)` | Supprimé : le SDK n'écrit jamais de logs (la v2 divulguait des secrets dans les logs de débogage). Encapsulez `hc.Transport` pour tracer | | `client.Close()`, `client.HTTPClient()` | Supprimés : conservez votre propre `*http.Client` et appelez `CloseIdleConnections` dessus | | `rest.APIURL`, `rest.APIVersion`, `rest.Endpoint*` | Supprimés ; `squarecloud.DefaultBaseURL` est une constante | | (aucun) | `squarecloud.WithMaxRetries(n)` (nouveau ; par défaut 2) | | Timeout fixe de 30 s du `http.Client` | `squarecloud.WithTimeout(d)` (nouveau ; par défaut 30 s, `d <= 0` désactive toutes les échéances par défaut) | Options par requête : | v2 | v3 | | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `rest.WithContext(ctx)` | `ctx` est le premier argument de chaque méthode | | `rest.WithToken(token)` (par ex. pour valider une clé à la connexion) | Créez un client jetable : `squarecloud.New(token).Account.Me(ctx)` (peu coûteux, aucune connexion n'est conservée) | | `rest.WithQueryParam("path", dir)` sur un commit | `c.Apps.Commit(ctx, id, r, dir, "")` | | `rest.WithQueryParam(filter, v)` sur les analytics | `c.Apps.Network.Analytics(ctx, id, start, end, squarecloud.AnalyticsFilters{...})` avec `Country`, `IP`, `Path`, `Status`, `OS`, `Browser`, `Protocol`, `Referer`, `Provider`, `ContentType`, `Bot` | | `rest.WithQueryParam("include_4xx", "true")` | `c.Apps.Network.Errors(ctx, id, start, end, true)` | | `rest.WithQueryParam("workspaceId", ws)` sur le statut de la liste | `c.Apps.StatusAll(ctx, ws)` | | `rest.WithHeader`, `rest.RequestOpt`, `rest.RequestConfig`, `rest.DefaultRequestConfig` | Supprimés | ## Méthode par méthode `api` est le `rest.Rest` de la v2, `c` le `*squarecloud.Client` de la v3. | v2 | v3 | Remarques | | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api.SelfUser()` | `me, err := c.Account.Me(ctx)`, puis `me.User` | Renvoie `Account` | | `api.GetApplications()` | `c.Account.Me(ctx)`, puis `me.Applications` (`[]AppSummary`) | | | `api.GetDatabases()` | `c.Account.Me(ctx)`, puis `me.Databases` (`[]DatabaseSummary`) | | | `api.UserSnapshots(scope)` | `c.Account.Snapshots(ctx, scope)` | | | `api.ServiceStatus()` | `c.Service.Status(ctx)` | Nouveau modèle, voir [Types](#types) | | `api.PostApplications(r)` → `*ApplicationUploaded` | `c.Apps.Create(ctx, r)` → `AppCreated` (une valeur) | La v2 mettait le zip en mémoire tampon et nommait la partie `upload.zip` ; la v3 le diffuse en flux et nomme la partie d'après un `*os.File` (son nom de base), à défaut `app.zip`. `Subdomain` a disparu : lisez `Domain`, l'hôte complet (`my-app.squareweb.app`), `""` pour les applications non web | | `api.GetApplication(id)` | `c.Apps.Get(ctx, id)` | | | `api.DeleteApplication(id)` | `c.Apps.Delete(ctx, id)` | | | `api.PostApplicationSignal(id, squarecloud.ApplicationSignalStart/Stop/Restart)` | `c.Apps.Start(ctx, id)` / `c.Apps.Stop(ctx, id)` / `c.Apps.Restart(ctx, id)` | | | `api.PostApplicationCommit(id, r, rest.WithQueryParam("path", p))` | `c.Apps.Commit(ctx, id, r, p, filename)` | La v2 nommait toujours la partie `commit.zip` ; la v3 utilise `filename`, à défaut le nom propre d'un `*os.File` : un fichier unique qui n'est pas un zip arrive donc désormais sous son propre nom au lieu d'échouer en tant que zip | | `api.GetApplicationStatus(id)` | `c.Apps.Status(ctx, id)` | | | `api.GetApplicationStatusRaw(id)` | `c.Apps.StatusRaw(ctx, id)` | | | `api.GetApplicationListStatus()` | `c.Apps.StatusAll(ctx, "")` | Renvoie `[]StatusListItem` | | `api.GetApplicationLogs(id)` → `ApplicationLogs` | `c.Apps.Logs(ctx, id)` → `string` | | | `api.GetApplicationMetrics(id)` | `c.Apps.Metrics(ctx, id)` | Les points arrivent du plus récent au plus ancien, comme l'API les envoie | | `api.ApplicationRealtime(id, rest.WithContext(ctx))` | `c.Apps.Realtime(ctx, id)` | Renvoie `*Realtime` ; voir [Changements de comportement](#changements-de-comportement) | | `api.GetApplicationDomains()` | `c.Apps.Domains(ctx)` | | | `api.GetLoadBalancers()` | `c.Apps.LoadBalancers(ctx)` | | | `api.GetApplicationEnvs(id)` | `c.Apps.Envs.Get(ctx, id)` | | | `api.SetApplicationEnvs(id, envs)` | `c.Apps.Envs.Set(ctx, id, envs)` | | | `api.ReplaceApplicationEnvs(id, envs)` | `c.Apps.Envs.Replace(ctx, id, envs)` | | | `api.DeleteApplicationEnvs(id, keys)` → `error` | `c.Apps.Envs.Delete(ctx, id, keys...)` → `(EnvVars, error)` (les variables restantes) | | | `api.GetApplicationFiles(id, path)` → `[]FileInfo` | `c.Apps.Files.List(ctx, id, path)` → `[]FileEntry` | Un répertoire manquant donne désormais 404 `FILE_NOT_FOUND` (c'était une liste vide) ; un chemin protégé donne 403 `BLOCKED_PATH` | | `api.ReadApplicationFile(id, path)` → `FileContent` | `c.Apps.Files.Read(ctx, id, path)` → `[]byte` | Demandé en base64 puis décodé ; un fichier de plus de 10 Mo donne 413 `FILE_TOO_LARGE` | | `api.PutApplicationFile(id, path, b)` → `(FileWritten, error)` | `c.Apps.Files.Write(ctx, id, path, b)` → `error`. Supprimez toute vérification de `written` : le succès est une erreur `nil` | Le contenu est toujours envoyé encodé en base64, les fichiers binaires sont donc sans risque ; un contenu vide écrit un fichier vide | | `api.MoveApplicationFile(id, from, to)` | `c.Apps.Files.Move(ctx, id, path, to)` | | | `api.DeleteApplicationFile(id, path)` | `c.Apps.Files.Delete(ctx, id, path)` | Fonctionne désormais (toujours 400 en v2) | | `api.GetApplicationSnapshots(id)` | `c.Apps.Snapshots.List(ctx, id)` | Chaque `Snapshot` porte désormais `VersionID` et `URL` (lien de téléchargement signé) fournis par l'API | | `api.CreateApplicationSnapshot(id)` | `c.Apps.Snapshots.Create(ctx, id)` | Vérifiez `.Pending` (202) avant d'utiliser `.URL` | | `api.RestoreApplicationSnapshot(id, snapID, verID)` | `c.Apps.Snapshots.Restore(ctx, id, snap.Name, snap.VersionID)` | `VersionID` est un champ envoyé par l'API : plus rien n'a besoin d'être extrait de `Key`. Voir [Snapshots](/fr/sdks/go/snapshots#restaurer-un-snapshot) pour les erreurs | | `api.GetApplicationDeployments(id)` | `c.Apps.Deploys.List(ctx, id)` | | | `api.GetApplicationCurrentDeployment(id)` | `c.Apps.Deploys.Current(ctx, id)` | | | `api.PostApplicationDeployWebhook(id, token)` → `GithubWebhook` | `c.Apps.Deploys.SetWebhook(ctx, id, token)` → `string` | | | `api.LinkApplicationGithubApp(id, repo, branch)` → `GithubAppLink` | `c.Apps.Deploys.LinkGithubApp(ctx, id, repo, branch)` → `LinkedRepository` | Les clés API fonctionnent désormais (scope `apps:deploy`) ; l'enveloppe `repository` a disparu ; un compte sans GitHub connecté donne 403 `GITHUB_NOT_CONNECTED` | | `api.UnlinkApplicationGithubApp(id)` | `c.Apps.Deploys.UnlinkGithubApp(ctx, id)` | 400 `GIT_NOT_CONFIGURED` sans liaison | | `api.GetApplicationDNS(id)` | `c.Apps.Network.DNS(ctx, id)` | | | `api.SetApplicationCustomDomain(id, d)` | `c.Apps.Network.SetDomain(ctx, id, d)` | | | `api.GetApplicationAnalytics(id, s, e, opts...)` | `c.Apps.Network.Analytics(ctx, id, s, e, squarecloud.AnalyticsFilters{...})` | Renvoie `*NetworkAnalytics`, `nil` pour une fenêtre sans trafic | | `api.GetApplicationNetworkErrors(id, s, e, opts...)` | `c.Apps.Network.Errors(ctx, id, s, e, include4xx)` | Renvoie `*NetworkErrors`, `nil` si vide | | `api.GetApplicationNetworkLogs(id, s, e)` | `c.Apps.Network.Logs(ctx, id, s, e)` | | | `api.GetApplicationNetworkPerformance(id, s, e)` | `c.Apps.Network.Performance(ctx, id, s, e)` | Renvoie `*NetworkPerformance`, `nil` si vide | | `api.PurgeApplicationCache(id)` | `c.Apps.Network.PurgeCache(ctx, id)` | | | `api.CreateDatabase(opts)` | `c.Databases.Create(ctx, squarecloud.DatabaseCreate{...})` | | | `api.GetDatabase(id)` | `c.Databases.Get(ctx, id)` | | | `api.UpdateDatabase(id, opts)` | `c.Databases.Update(ctx, id, squarecloud.DatabaseUpdate{...})` | | | `api.DeleteDatabase(id)` | `c.Databases.Delete(ctx, id)` | | | `api.StartDatabase(id)` / `api.StopDatabase(id)` | `c.Databases.Start(ctx, id)` / `c.Databases.Stop(ctx, id)` | | | `api.GetDatabaseStatus(id)` / `api.GetDatabaseStatusRaw(id)` | `c.Databases.Status(ctx, id)` / `c.Databases.StatusRaw(ctx, id)` | | | `api.GetDatabaseListStatus()` | `c.Databases.StatusAll(ctx)` | Renvoie `[]StatusListItem` | | `api.GetDatabaseMetrics(id)` | `c.Databases.Metrics(ctx, id)` | | | `api.GetDatabaseCertificate(id)` → `DatabaseCertificate` | `c.Databases.Certificate(ctx, id)` → `string` (PEM en base64) | | | `api.ResetDatabaseCredentials(id, t)` → `DatabasePasswordReset` | `c.Databases.ResetCredentials(ctx, id, t)` → `string` | Le nouveau mot de passe, `""` pour le renouvellement du certificat | | `api.GetDatabaseSnapshots` / `CreateDatabaseSnapshot` / `RestoreDatabaseSnapshot` | `c.Databases.Snapshots.List` / `Create` / `Restore` | Comme pour les applications : restaurez avec `snap.Name` et `snap.VersionID` | | `api.GetWorkspaces()` | `c.Workspaces.List(ctx)` | | | `api.GetWorkspace(id)` | `c.Workspaces.Get(ctx, id)` | | | `api.CreateWorkspace(name)` | `c.Workspaces.Create(ctx, name)` | | | `api.DeleteWorkspace(id)` | `c.Workspaces.Delete(ctx, id)` | | | `api.LeaveWorkspace(id)` | `c.Workspaces.Leave(ctx, id)` | | | `api.AddWorkspaceMember(ws, code, group)` | `c.Workspaces.Members.Add(ctx, ws, code, group)` | | | `api.UpdateWorkspaceMember(ws, member, group)` | `c.Workspaces.Members.Update(ctx, ws, member, group)` | | | `api.RemoveWorkspaceMember(ws, member)` | `c.Workspaces.Members.Remove(ctx, ws, member)` | | | `api.GetWorkspaceInviteCode()` → `WorkspaceInviteCode` | `c.Workspaces.Members.InviteCode(ctx)` → `string` | | | `api.AddWorkspaceApplication(ws, app)` / `RemoveWorkspaceApplication` | `c.Workspaces.Apps.Add(ctx, ws, app)` / `Remove` | | | Télécharger vous-même l'URL d'un snapshot (`http.Get`) | `c.DownloadSnapshot(ctx, url, w)` | Diffuse en flux vers n'importe quel `io.Writer` ; n'envoie jamais la clé | | `rest.IsRateLimit(err)` | `errors.As(err, &apiErr) && apiErr.Status == 429` | Supprimé | | `rest.ErrorCode(err)` | `errors.As(err, &apiErr)`, puis `apiErr.Code` | Supprimé | | `client.Request(...)`, `client.Stream(...)` (`rest.Client`) | Les méthodes typées ci-dessus | Supprimés : chaque opération a sa propre méthode | | `rest.NewApplications(client)`, `rest.NewDatabases(client)`, `rest.NewWorkspaces(client)` | `squarecloud.New(key)`, puis les champs `c.Apps`, `c.Databases`, `c.Workspaces` | Supprimés | | `rest.Applications`, `rest.Databases`, `rest.Workspaces` (interfaces) | `squarecloud.AppsAPI`, `DatabasesAPI`, `WorkspacesAPI` (les types de ces champs) | Supprimées ; déclarez votre propre interface pour simuler | | `rest.Config`, `rest.DefaultConfig()`, `(*rest.Config).Apply(opts)` | `squarecloud.New(key, opts...)` avec `WithHTTPClient`, `WithBaseURL`, `WithUserAgent` | Supprimés (utilisez `Option` ; il n'y a pas de logger) | | `(*rest.RequestConfig).Apply(opts)` | Passez `ctx` et des arguments typés | Supprimé | | `(*rest.RealtimeStream).Next()` / `Close()` | `(*squarecloud.Realtime).Next()` / `Close()` | `Next` renvoie `io.EOF` après `REALTIME_DISCONNECTED` | | (aucun) | `c.AI.Chat(ctx, squarecloud.ChatRequest{...})` | Nouveau | ## Types | v2 (`squarecloud.`) | v3 (`squarecloud.`) | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `User` (issu de `SelfUser`) | `User` (dans `Account`, le résultat de `Account.Me`) | | `UserPlan`, `UserPlanMemory` | `Plan`, `PlanMemory`. `Plan.Duration` est l'expiration en **millisecondes** Unix (`*int64`, `nil` s'il n'expire jamais) : convertissez-la avec `time.UnixMilli`, pas `time.Unix` | | `UserApplication`, `UserDatabase` (`Type string`) | `AppSummary`, `DatabaseSummary` (`Type DatabaseType`) | | `Application` | `App` | | `ApplicationUploaded` (`CPU int`), `ApplicationLanguage` | `AppCreated` (`CPU float64`), `AppLanguage` | | `ApplicationStatus`, `DatabaseStatus` | `RuntimeStats` (partagé) | | `ApplicationStatusRaw`, `DatabaseStatusRaw` | `RuntimeStatsRaw` | | `ApplicationStatusNetwork`, `ApplicationStatusNetworkRaw` | `StatsNetwork`, `StatsNetworkRaw` | | `ApplicationStatusListItem`, `DatabaseStatusListItem` | `StatusListItem` | | `ApplicationLogs` | `string` | | `ApplicationSignal*` | Supprimés (utilisez `Start`/`Stop`/`Restart`) | | `FileInfo` (`Type FileType`, `LastModified int64`), constantes `FileType*` | `FileEntry` (`Type string`, `LastModified *float64`) : `"file"`/`"directory"` ; l'API envoie des ms Unix fractionnaires, ou `null` | | `FileContent`, `ByteArray` | `[]byte` | | `FileWritten` | Supprimé (champ non documenté) | | `Deployment` (`State DeploymentState`) | `DeployEvent` (`State`, `Source`, `Code`, `Message` en `string`). `Source` est nouveau, toujours `"git"` ; un événement `"error"` porte `Code`, par ex. `CLONE_FAILED`, et parfois `Message` | | `DeploymentState*` (`DeploymentStateError` = `"error"`) | Constantes de chaîne `Deploy*` (`DeployPending`, `DeployClone`, `DeployCommit`, `DeployRestarting`, `DeploySuccess`, `DeployError` = `"error"`) | | `DeploymentFiles`, `DeploymentCurrent`, `DeploymentGithubApp` | `DeployFiles`, `DeployCurrent`, `DeployRepository` | | `GithubWebhook` | `string` | | `GithubAppLink`, `GithubAppRepository` | `LinkedRepository` avec `ID`, `FullName`, `Branch` (renvoyé directement, sans enveloppe `Repository`) | | `Snapshot` | `Snapshot` + `VersionID`, `URL`, `Runtime`, `Origin` (tous les champs envoyés par l'API) | | `SnapshotCreated` | `SnapshotCreated` + `Pending` | | `DatabaseType` avec `DatabaseTypeMongo`, `DatabaseTypeMySQL`, `DatabaseTypeRedis`, `DatabaseTypePostgres` | `DatabaseType` (inchangé) avec `DatabaseMongo`, `DatabaseMySQL`, `DatabaseRedis`, `DatabasePostgres` (constantes renommées) | | `DatabaseCreateOptions`, `DatabaseUpdateOptions` | `DatabaseCreate`, `DatabaseUpdate` | | `DatabaseCreated` (`CPU int`, `Certificate string`) | `DatabaseCreated` (`CPU float64`, `Certificate *string`, `nil` quand l'API n'en envoie pas) | | `DatabaseResetType`, `DatabaseResetPassword`, `DatabaseResetCertificate` | `DatabaseReset`, `ResetPassword`, `ResetCertificate` | | `DatabaseCertificate`, `DatabasePasswordReset` | `string` | | `WorkspaceMemberGroup`, `WorkspaceGroup*` | En entrée : `WorkspaceGroup` (`GroupAdmin`, `GroupMaintain`, `GroupManager`, `GroupView`) ; `WorkspaceMember.Group` est une `string` (peut valoir `"owner"`) | | `WorkspaceMember` (`Name string`) | `WorkspaceMember` (`Name *string`, `nil` quand l'API envoie `null`). Les identifiants de workspace font 32 ou 40 caractères hexadécimaux | | `WorkspaceInviteCode` | `string` | | `ServiceStatus` (`Status`, `Message`) | `ServiceStatus` (`Status`, `Message`, `CheckedAt`, `Stale`, `Services`, `Dependencies`). `Status` vaut désormais par ex. `"online"` ; les entrées sont des `ServiceEntry` | | `rest.RealtimeStream` | `*squarecloud.Realtime` (`Next`, `Close`) | | `RealtimeEvent` (`Event`, `Data`) | `RealtimeEvent` (`Event`, `Data`, `ID`, `Stream`, `Line`, `Status`) | | Options de requête sur les analytics | `AnalyticsFilters` (sans `Start`/`End` : ce sont des arguments) | | `NetworkErrorsSummaryClass` (`Class4xx`, `Class5xx`) | `NetworkErrorsSummary.ByClass`, une `map[string]int64` avec les clés `"4xx"` et `"5xx"` | | `NetworkErrorsByStatus`, `NetworkErrorsTimeseries`, `NetworkErrorsTopPath`, `NetworkErrorsByMethod` | `NetworkErrorsStatus`, `NetworkErrorsBucket`, `NetworkErrorsPath`, `NetworkErrorsMethod` | | `NetworkLatency`, `NetworkPerformance*` | `Percentiles` (`P50`/`P95`/`P99` sont des `*float64`, `nil` pour une fenêtre sans requêtes), `PerformanceSummary`, `PerformanceBucket`, `PerformanceRegion` (pays et colos ; `P50`/`P95` `*float64`, `City`/`Country` `*string`), `PerformancePath` (`P95`/`P99` `*float64`) | | `RealtimeStatus` | `RealtimeStatus.CPULimit` est un nombre de cœurs (par ex. `1`, `0.5`) | | Valeurs de fournisseur des analytics | `"NAME (ASN)"` (par ex. `"GOOGLE (15169)"`) ; `AnalyticsFilters.Provider` prend exactement cette valeur | | `AppDomainType*` | `AppDomain.Type` est une `string` | | `APIResponse[T]` | Supprimé (interne) | | Tailles et compteurs en `int` (`FileInfo.Size`, `Snapshot.Size`, `Visits`/`Requests` des analytics, totaux et maps des erreurs réseau, `Requests` des performances) | `int64` | ## Erreurs `rest.APIError` (`StatusCode`, `Code`, `Message`) devient `squarecloud.APIError` (`Status`, `Code`, `Message`, `Method`, `Path`) : renommez `StatusCode` en `Status`. `rest.ErrorCode(err)` et `rest.IsRateLimit(err)` ont été supprimés : utilisez `errors.As` et vérifiez `Code` ou `Status == 429`. ```go theme={"system"} // v2 if rest.IsRateLimit(err) { ... } // v3 var apiErr *squarecloud.APIError if errors.As(err, &apiErr) && apiErr.Status == 429 { fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED } ``` * Les échecs réseau sont désormais des `*APIError` avec `Status` `0`, `Code` `NETWORK_ERROR` ou `TIMEOUT` et le texte de la cause comme `Message`, et ils encapsulent la cause (`errors.Is(err, context.Canceled)` fonctionne). * Il en va de même pour les vérifications locales (`Status` `0` : `INVALID_ID`, `FILE_TOO_LARGE`, `INVALID_API_KEY`) et pour un corps 2xx qui n'est pas du JSON (`UNKNOWN_ERROR`, `Invalid JSON in HTTP response`). * Un corps 2xx indiquant `"status": "error"` est désormais une erreur (la v2 le signalait comme un succès). Les refus du cluster lors du démarrage ou de l'arrêt des applications et des bases de données arrivent en 409 `CONTAINER_ALREADY_STARTED`, `CONTAINER_ALREADY_STOPPED`, `CONTAINER_TEMPORARILY_SUSPENDED`, `CONTAINER_NOT_FOUND`, `CONTAINER_INSUFFICIENT_DISK_SPACE`, `CONTAINER_NETWORK_CONFLICT` ou `ACTION_FAILED`, sans message. Le SDK renvoie une réponse « déjà » comme une erreur : traitez-la vous-même comme un succès si nécessaire. * Une réponse sans code a le `Code` `UNKNOWN_ERROR`. * Une clé API expirée donne 401 `ACCESS_DENIED`, comme une clé inconnue. * Il existe une constante `Code*` pour chaque code documenté par l'API. L'API envoie désormais 429 `RATE_LIMITED` (`CodeRateLimited`) là où elle envoyait `RATE_LIMIT` et `RATE_LIMIT_EXCEEDED` ; `CodeRateLimit` et `CodeRateLimitExceeded` restent, dépréciées. * Chaque erreur de `AI.Chat` a la forme OpenAI avec un code en minuscules (`access_denied`, `rate_limit_exceeded`, `server_overloaded`, ...), que `Code` reprend tel quel. * `Error()` produit `squarecloud: : HTTP : ` (v2 : `squarecloud: (, HTTP )`). Basez-vous sur les champs, pas sur le texte. Voir [Erreurs](/fr/sdks/go/errors) pour la référence complète. ## Changements de comportement * **Clé API vide :** `New("")` (ou une clé composée uniquement d'espaces) renvoie toujours un client (il ne peut pas renvoyer d'erreur), mais chaque appel sauf `Service.Status` échoue localement avec `INVALID_API_KEY`. * **Snapshot 202 :** la v2 renvoyait une `*APIError` avec `StatusCode` 202. La v3 renvoie un `SnapshotCreated` avec `Pending: true` et une erreur `nil`. * **Temps réel :** `Next` renvoie désormais un `RealtimeEvent`. Faites un switch sur `ev.Event` (`system`, `status`, `logs`, `error`, `message`). Pour les logs, affichez `ev.Line` (l'octet `\u0001`/`\u0002` est retiré ; `ev.Data` reste la trame brute) et utilisez `ev.Stream` pour stdout/stderr. Pour le statut, utilisez `ev.Status` : jamais `nil` sur un événement de statut, fusionné superficiellement entre les trames et les reconnexions. Après `REALTIME_DISCONNECTED`, `Next` renvoie `io.EOF`. Le flux ne s'arrête plus au bout de 30 s, les reconnexions attendent au moins 5,5 s après l'ouverture précédente, et l'ouverture est bornée par le timeout du client jusqu'à l'arrivée des en-têtes. Voir [Temps réel](/fr/sdks/go/realtime). * **Timeouts :** la v2 utilisait un timeout fixe de 30 s du `http.Client` pour tout. La v3 n'applique une échéance par défaut que lorsque `ctx` n'en a pas : le timeout du client (`WithTimeout`, 30 s) pour la plupart des appels ; au moins 2 minutes pour start/stop/restart, la création de base de données, la création et la restauration de snapshot et `AI.Chat` ; aucune pour les envois, les écritures de fichiers de plus de 1 MiB de contenu et les téléchargements de snapshots. `WithTimeout(0)` les désactive toutes. * **Fenêtres réseau vides :** `Analytics`, `Errors` et `Performance` renvoient des pointeurs `nil` lorsque la fenêtre n'a pas de trafic. * **En-têtes :** chaque requête à l'API envoie `Accept: application/json` (`text/event-stream` pour le temps réel). Le `User-Agent` par défaut est passé de `Square GO` à `squarecloud-sdk-go/3.0.0` (`WithUserAgent` le remplace toujours). * **Identifiants :** chaque identifiant est désormais encodé en pourcentage comme un seul segment de chemin (la v2 le collait tel quel dans le chemin), et un identifiant vide, `.` ou `..` échoue localement avec `INVALID_ID`. * **Écriture de fichiers :** la v2 envoyait toujours le contenu sous forme de chaîne, ce qui corrompait les fichiers binaires, et ne pouvait pas écrire de fichier vide. La v3 envoie toujours le contenu encodé en base64 : chaque octet est donc conservé, un contenu vide écrit un fichier vide, et un contenu de plus de 10 Mo échoue localement avec `FILE_TOO_LARGE`. L'API répond 400 `INVALID_CONTENT` pour un contenu qu'elle ne peut pas décoder. * **Lecture de fichiers :** la v3 demande toujours du base64 et le décode, au lieu du tableau d'octets JSON que lisait la v2 (déprécié par l'API). Un fichier de plus de 10 Mo donne 413 `FILE_TOO_LARGE`. * **Liste de fichiers :** lister un répertoire inexistant donne 404 `FILE_NOT_FOUND` ; c'était auparavant une liste vide. * **Snapshots :** les entrées de la liste portent `VersionID` et `URL` fournis par l'API ; rien n'est extrait de `Key`. * **Nouvelles tentatives :** nouveau. Les erreurs réseau sur GET, les 503 `UPLOAD_BUSY`/`ANALYTICS_BUSY` et le 503 `DATABASE_UNAVAILABLE` sur GET sont réessayés deux fois par défaut ; `WithMaxRetries(0)` rétablit le comportement de la v2. `DATABASE_UNAVAILABLE` peut arriver après le début d'une mutation : le SDK ne le réessaie donc jamais sur les autres méthodes ; réessayez vous-même une mutation idempotente si vous le souhaitez. Voir [Nouvelles tentatives](/fr/sdks/go/errors#nouvelles-tentatives). * **Version de Go :** le minimum est passé de Go 1.24 à Go 1.22.