Vai al contenuto principale
Questa pagina documenta @squarecloud/api v4. Se stai effettuando l’upgrade da v3, leggi prima la guida alla migrazione v3 → v4.

​
Requisiti

​
Installazione

npm install @squarecloud/api

​
Istanziare il client

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

const api = new SquareCloudAPI(process.env.SQUARE_API_KEY!);

​
Costruttore

ParametroTipoObbligatorioDescrizione
apiKeystringSìLa tua chiave API di Square Cloud. Il client solleverà un’eccezione se questo valore non è una stringa.

​
Moduli

Il client espone l’intera piattaforma v2 tramite moduli dedicati. Ogni modulo è una proprietà dell’istanza SquareCloudAPI.
ProprietàModuloDocumentazione
api.userUtente autenticato, piano, app e database possedutiQuesta pagina
api.applicationsElenca, recupera, carica e ispeziona le applicazioniGestire le applicazioni
api.databasesCrea, recupera e gestisci i databaseDatabase
api.workspacesCrea, elenca e gestisci i workspaceWorkspace
api.serviceStato aggregato della piattaformaQuesta pagina
api.cacheCache in memoria popolata dagli eventi dell’SDKQuesta pagina

​
Ottenere l’utente autenticato

api.user.get() restituisce un’istanza User che contiene i dettagli dell’account, il piano attuale, le applicazioni possedute e i database posseduti. 
const user = await api.user.get();

console.log(user.id);          // "abcdef0123456789abcdef01"
console.log(user.name);        // "John Doe"
console.log(user.email);       // "john@example.com"
console.log(user.locale);      // "en-US"
console.log(user.plan.name);   // "free" | "standard" | ...
console.log(user.createdAt);   // Date

console.log(user.applications); // Collection<string, BaseApplication>
console.log(user.databases);    // Collection<string, Database>
user.applications e user.databases sono istanze Collection (una sottoclasse di Map). Iterale come qualsiasi Map: 
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}

​
Recuperare una singola applicazione

Usa api.applications.fetch(id) per recuperare un’Application completamente popolata (o WebsiteApplication, quando l’app ha un dominio del sito web). 
const app = await api.applications.fetch("abc123def456abc123def456");

console.log(app.id, app.name, app.cluster, app.createdAt);

if (app.isWebsite()) {
    // narrowed to WebsiteApplication — `.network` is available
    await app.network.purgeCache();
}
L’overload legacy api.applications.get(id) esiste ancora, ma restituisce la più leggera BaseApplication ed è mantenuto solo per retrocompatibilità. Preferisci .fetch() per v4.

​
Elencare la cronologia degli snapshot (a livello di account)

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
Consulta Snapshots per i dettagli sui payload degli snapshot.

​
Stato della piattaforma

api.service.status() espone lo stato di salute aggregato della piattaforma (gli stessi dati mostrati nella pagina di stato pubblica). 
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // human-readable summary
A differenza della maggior parte degli endpoint v2, questa route non avvolge il suo payload nella busta standard { status, response }.

​
Cache del client

Il client mantiene una cache in memoria che l’SDK tiene sincronizzata man mano che effettui chiamate: 
api.cache.user;   // last fetched User
// each application instance also exposes app.cache.status / .logs / .snapshots
L’SDK emette eventi tipizzati a cui puoi iscriverti: 
api.on("userUpdate", (previous, current) => {
    console.log("user changed:", current.name);
});

api.on("statusUpdate", (application, previous, current) => {
    console.log(`${application.name} → ${current.status}`);
});

api.on("logsUpdate", (application, previous, current) => {
    console.log(`new logs for ${application.name}`);
});

api.on("snapshotsUpdate", (application, previous, current) => {
    console.log(`${current.length} snapshots for ${application.name}`);
});

​
Gestione degli errori

Le richieste fallite sollevano un SquareCloudAPIError. L’errore espone una proprietà code stabile su cui puoi effettuare uno switch per discriminare le modalità di errore. 
import { SquareCloudAPI, SquareCloudAPIError } from "@squarecloud/api";

try {
    const app = await api.applications.fetch("invalid-id");
} catch (err) {
    if (err instanceof SquareCloudAPIError) {
        console.error(err.code);    // e.g. "APP_NOT_FOUND"
        console.error(err.message);
    }
}