Skip to main content
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

Le module n’a aucune dépendance en dehors de la bibliothèque standard de Go et est distribué sous licence MIT (la v2 était sous AGPL-3.0). Son nom de paquet est 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ête Authorization (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 *APIError avec 403 MISSING_SCOPE ou RESOURCE_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.
Gardez la clé hors de votre code source et des binaires que vous distribuez. Lisez-la depuis l’environnement ou un gestionnaire de secrets.
Les exemples lisent la clé depuis la variable d’environnement SQUARECLOUD_API_KEY. Définissez-la dans le terminal où vous les exécutez :

Créer le client

Enregistrez-le sous le nom 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é :
Ne définissez pas Timeout sur le *http.Client que vous passez à WithHTTPClient. Ce timeout couvre aussi la lecture du corps : il couperait donc les flux temps réel et les téléchargements de snapshots. Utilisez plutôt les contextes, WithTimeout et les timeouts de http.Transport.
Le SDK n’écrit jamais de logs. Pour tracer les requêtes, encapsulez le http.RoundTripper du client que vous passez à WithHTTPClient.
La clé API est stockée dans un champ non exporté du client. fmt affiche les champs non exportés : n’affichez donc pas le client avec %v ou %+v.

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 les ctx, c et appID qu’ils utilisent :
Collez un extrait à la fois dans 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 un context.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.ResetCredentials et les méthodes Create).
  • Un résultat de type chaîne vaut "" quand l’API n’en envoie pas.
  • Les champs que l’API peut envoyer à null sont des pointeurs : vérifiez qu’ils ne sont pas nil avant 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.
Les groupes de ressources sont de simples champs de struct, vous pouvez donc conserver des valeurs de méthode :

Applications de workspace

Chaque appID 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 arguments start 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 ctx n’a pas d’échéance. Une échéance sur ctx l’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 tout d <= 0) désactive toutes les échéances par défaut, planchers de 2 minutes compris.
Chaque méthode prend un ctx : vous pouvez donc borner ou annuler n’importe quel appel :
Un appel dont le 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.