SDK ufficiali per JavaScript, Python e Go

Scegli il tuo SDK

Tutti gli SDK sono open source e disponibili su GitHub. Hanno zero dipendenze a runtime e restituiscono i dati dell’API così come sono, nomi dei campi compresi.

JavaScript

@squarecloud/api v6. App, database, workspace, deploy, rete, realtime, snapshot e AI, su Node.js, Deno, Bun e runtime edge.

Python

squarecloud-api v5. La stessa copertura, con un client sincrono e uno asincrono, usando solo la libreria standard.

Go

sdk-api-go v3. La stessa copertura, con context in ogni chiamata e un unico tipo di errore.

Blob Storage (JavaScript)

@squarecloud/blob v4. Upload fino a 10 GiB, oggetti privati, link, condivisioni, regole e gateway S3, su Node.js e nel browser.

In sintesi

SDK	Pacchetto	Versione	Runtime	Installazione
JavaScript	`@squarecloud/api`	6.0.0	Node.js 22+, Deno, Bun, edge	`npm install @squarecloud/api`
Python	`squarecloud-api` (import `squarecloud`)	5.0.0	Python 3.11+	`pip install squarecloud-api`
Go	`github.com/squarecloudofc/sdk-api-go/v3`	3.0.0	Go 1.22+	`go get github.com/squarecloudofc/sdk-api-go/v3`
Blob Storage	`@squarecloud/blob`	4.0.0	Node.js 20+ e browser	`npm install @squarecloud/blob`

Quickstart

Fai la tua prima chiamata in pochi minuti. Ogni programma qui sotto stampa il nome del tuo account e quante app può vedere la tua chiave API.

Crea una chiave API

Crea una chiave nelle impostazioni di sicurezza del tuo account. Trattala come una password: tienila fuori dal codice sorgente.

Imposta la variabile d'ambiente SQUARECLOUD_API_KEY

Gli esempi leggono la chiave da SQUARECLOUD_API_KEY. Impostala nel terminale in cui li esegui:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

Installa l'SDK e fai la prima chiamata

JavaScript
Python
Go

npm install @squarecloud/api

index.mjs

import { SquareCloudAPI } from "@squarecloud/api";

const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);
const { user, applications } = await api.account.me();

console.log(`Hi ${user.name}, you have ${applications.length} apps`);

node index.mjs

pip install squarecloud-api

main.py

import os

from squarecloud import SquareCloud

with SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client:
    me = client.account.me()
    print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps")

python main.py

go mod init example.com/hello
go get github.com/squarecloudofc/sdk-api-go/v3

main.go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

func main() {
	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

	me, err := c.Account.Me(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications))
}

go run .

Controlla l'output

Il programma stampa il nome del tuo account e il numero di app che la chiave può vedere:

Hi Jane, you have 3 apps

Un errore 401 ACCESS_DENIED significa che la chiave è errata, revocata o scaduta. Se la variabile non è impostata, il programma si ferma prima di inviare qualsiasi cosa.

Cosa copre ciascun SDK

Gli SDK JavaScript, Python e Go coprono l’intera API di Square Cloud: le stesse 67 operazioni, più il download dei file di snapshot. Condividono la stessa struttura delle pagine, gli stessi esempi e lo stesso comportamento:

un’unica classe di errore, con lo status HTTP e il codice di errore dell’API;
un timeout di 30 secondi, e almeno 120 secondi per le chiamate che il server tiene aperte;
retry solo per i fallimenti sicuri da ripetere, mai per un 429;
id <appId>-<workspaceId> per agire sulle app condivise tramite un workspace.

L’SDK di Blob Storage copre l’API Blob e il gateway S3. È un pacchetto separato con client, credenziali e codici di errore propri.

Riferimenti degli errori

Ogni pagina degli SDK sugli errori descrive la sua classe di errore, i retry e i rate limit. I codici di errore invece provengono dall’API: il riferimento degli errori dell’API li elenca tutti, e il riferimento degli errori dell’API Blob elenca i codici di Blob Storage.

SDK	Errori, retry e rate limit
JavaScript	`SquareCloudAPIError`
Python	`SquareCloudAPIError`
Go	`*APIError`
Blob Storage	`SquareCloudBlobError`

Aggiornamento

Ogni release degli SDK dell’API qui sopra è una riscrittura. Consulta le guide alla migrazione: JavaScript v5 → v6, Python v4 → v5, Go v2 → v3 e Blob v3 → v4. Square Cloud continua a migliorare i suoi SDK e ad aggiungere nuovi linguaggi. Se il tuo manca, faccelo sapere.

Prossimi passi

Introduzione all'API

Chiama l’API REST direttamente, con curl.

Quickstart della CLI

Fai il deploy e gestisci le app dal terminale.

Quickstart dell'API Blob

Carica un file su Blob Storage con curl.

CLI

VS Code

SDKs

SDK ufficiali per JavaScript, Python e Go

Scegli il tuo SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

In sintesi

Quickstart

Cosa copre ciascun SDK

Riferimenti degli errori

Aggiornamento

Prossimi passi

Introduzione all'API

Quickstart della CLI

Quickstart dell'API Blob

​Scegli il tuo SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

​In sintesi

​Quickstart

​Cosa copre ciascun SDK

​Riferimenti degli errori

​Aggiornamento

​Prossimi passi

Introduzione all'API

Quickstart della CLI

Quickstart dell'API Blob

Scegli il tuo SDK

In sintesi

Quickstart

Cosa copre ciascun SDK

Riferimenti degli errori

Aggiornamento

Prossimi passi