Passer au contenu principal
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

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.

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

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

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 :

Nouveaux types et champs

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

Client

Installez le SDK et créez un client.

Snapshots

Créez, restaurez et suivez des snapshots.

Erreurs

Classe d’erreur, nouvelles tentatives et limites de débit.