Cette page documente
github.com/squarecloudofc/sdk-api-go/v3 (v3.0.0), une réécriture du SDK. Vous venez de la v2 ? Lisez le guide de migration v2 → v3.Prérequis
- Go 1.22 ou plus récent.
- Une clé API (voir Clé API et scopes).
squarecloud.
Installation
Clé API et scopes
Créez une clé sur squarecloud.app/account/security. Le SDK l’envoie telle quelle dans l’en-têteAuthorization (sans préfixe Bearer).
Une clé peut être limitée à des scopes (apps:read, apps:deploy, apps:control, ai:chat, …) et à des applications ou bases de données précises :
- Un appel hors de ces limites renvoie une
*APIErroravec 403MISSING_SCOPEouRESOURCE_NOT_ALLOWED. - Les méthodes de liste (
Account.Me,Apps.StatusAll, …) ne renvoient que les ressources que la clé peut voir. - Une clé inconnue, révoquée ou expirée donne 401
ACCESS_DENIED.
SQUARECLOUD_API_KEY. Définissez-la dans le terminal où vous les exécutez :
- macOS / Linux
- Windows (PowerShell)
Créer le client
main.go dans un module (go mod init example.com/hello, puis le go get ci-dessus) et lancez go run .. Il affiche le nom de votre compte et le nombre d’applications que la clé peut voir :
squarecloud.New(apiKey, opts...) renvoie un *Client et jamais d’erreur. Un *Client peut être utilisé de façon concurrente sans risque : créez-le une fois et partagez-le entre les goroutines.
Comme New ne peut pas échouer, une clé vide ou composée uniquement d’espaces n’y est pas rejetée. À la place, chaque appel sauf Service.Status échoue localement avec INVALID_API_KEY (statut 0) avant toute requête. Ce code n’existe que dans le SDK Go.
Options
Passez les options àNew après la clé :
Le SDK n’écrit jamais de logs. Pour tracer les requêtes, encapsulez le
http.RoundTripper du client que vous passez à WithHTTPClient.
Exécuter les exemples
Les extraits des pages du SDK Go sont des fragments. Chacun s’exécute seul dans ce programme, qui déclare lesctx, c et appID qu’ils utilisent :
main, puis lancez goimports -w . pour ajouter les imports dont il a besoin (fmt, log, time, …). Installez-le avec go install golang.org/x/tools/cmd/goimports@latest, ou laissez l’extension Go de votre éditeur (gopls) ajouter les imports à l’enregistrement. Les pages qui ont besoin d’autres identifiants, comme une base de données ou un workspace, commencent par leur propre version de ce programme.
Modules
En plus de
New et des options With*, le paquet exporte les constantes DefaultBaseURL et Version, le type APIError avec une constante Code* par code d’erreur, des constantes typées pour les entrées énumérées (DatabaseRedis, GroupView, ResetPassword, SnapshotScopeDatabases, …) et une struct par forme de l’API, que vous pouvez utiliser dans votre propre code :
Conventions
Le contexte et l’identifiant d’abord, des données typées en retour
Chaque méthode prend d’abord uncontext.Context, puis l’identifiant de la ressource, et renvoie des structs simples (pas de méthodes, pas de cache). Les tags json sont les noms de champs de l’API (created_at, version_id, lastModified, joinedAt, netIO, …), la référence de l’API s’applique donc telle quelle : CreatedAt correspond à created_at, VersionID à version_id. Les champs que l’API ajoutera plus tard sont ignorés : ils ne cassent donc jamais le décodage.
- Les mutations ne renvoient qu’une
error, sauf si l’API renvoie des données (Envs.*,Deploys.SetWebhook,Deploys.LinkGithubApp,Databases.ResetCredentialset les méthodesCreate). - Un résultat de type chaîne vaut
""quand l’API n’en envoie pas. - Les champs que l’API peut envoyer à
nullsont des pointeurs : vérifiez qu’ils ne sont pasnilavant de les utiliser. - Les compteurs et les tailles en octets sont des
int64. - Les listes arrivent complètes en un seul appel : il n’y a pas de pagination.
Applications de workspace
ChaqueappID accepte aussi la forme composite <appId>-<workspaceId> pour agir sur une application partagée avec vous via un workspace. Workspaces.Get et Workspaces.List renvoient les identifiants bruts ; c’est à vous de construire l’identifiant composite :
Les identifiants sont encodés
Les identifiants dans le chemin de l’URL sont encodés en pourcentage. Un identifiant vide,. ou .. atteindrait une autre route : il échoue donc localement avec INVALID_ID (statut 0) avant tout envoi. Les routes de workspace envoient plutôt leurs identifiants dans le corps : là, INVALID_ID (400) vient du serveur.
Dates
Les argumentsstart et end (voir Réseau) sont des valeurs time.Time, envoyées au format RFC 3339 en UTC (secondes entières). Dans les réponses, les chaînes ISO 8601 de l’API sont décodées en time.Time, et les champs que l’API envoie en millisecondes Unix restent des nombres (Plan.Duration et Uptime en *int64, FileEntry.LastModified en *float64) : convertissez-les avec time.UnixMilli.
Timeouts
- L’échéance par défaut ne s’applique que lorsque
ctxn’a pas d’échéance. Une échéance surctxl’emporte toujours, qu’elle soit plus courte ou plus longue que la valeur par défaut, planchers compris. - Une seule échéance couvre tout l’appel : chaque tentative et les attentes entre les nouvelles tentatives.
WithTimeout(0)(ou toutd <= 0) désactive toutes les échéances par défaut, planchers de 2 minutes compris.
ctx : vous pouvez donc borner ou annuler n’importe quel appel :
ctx expire renvoie une *APIError avec TIMEOUT, et un appel dont le ctx est annulé renvoie NETWORK_ERROR, tous deux avec le statut 0. Ils encapsulent l’erreur du contexte, de sorte que errors.Is(err, context.DeadlineExceeded) et errors.Is(err, context.Canceled) fonctionnent. Une boucle temps réel renvoie plutôt le ctx.Err() brut.
Compte
c.Account.Me(ctx) renvoie l’utilisateur authentifié ainsi que les applications et bases de données que la clé peut voir.
c.Account.Snapshots(ctx, scope) liste tous les snapshots du compte : voir Snapshots.
Statut de la plateforme
c.Service.Status(ctx) renvoie le statut public de la plateforme. La route n’exige pas de clé, et c’est la seule méthode qui fonctionne aussi sur un client créé avec une clé vide.
unknown signifie que la vérification elle-même n’a pas pu s’exécuter : ce n’est pas la preuve d’une panne.
Prochaines étapes
Gérer les applications
Statut, cycle de vie, logs et métriques.
Erreurs
Classe d’erreur, nouvelles tentatives et limites de débit.
Introduction à l'API
URL de base, authentification et une première requête.
Démarrage rapide de la CLI
Déployez et gérez vos applications depuis le terminal.

