Zum Hauptinhalt springen
Diese Seite dokumentiert @squarecloud/api v4. Wenn Sie von v3 aktualisieren, lesen Sie zuerst den Migrationsleitfaden v3 → v4.

​
Voraussetzungen

​
Installation

npm install @squarecloud/api

​
Instanziierung des Clients

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

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

​
Konstruktor

ParameterTypErforderlichBeschreibung
apiKeystringJaIhr Square Cloud API-Schlüssel. Der Client wirft einen Fehler, wenn dies kein String ist.

​
Module

Der Client stellt die gesamte v2-Plattform über dedizierte Module bereit. Jedes Modul ist eine Eigenschaft der SquareCloudAPI-Instanz.
EigenschaftModulDokumentation
api.userAuthentifizierter Benutzer, Plan, eigene Apps und DatenbankenDiese Seite
api.applicationsAnwendungen auflisten, abrufen, hochladen und inspizierenAnwendungen verwalten
api.databasesDatenbanken erstellen, abrufen und verwaltenDatenbanken
api.workspacesWorkspaces erstellen, auflisten und verwaltenWorkspaces
api.serviceAggregierter PlattformstatusDiese Seite
api.cacheIn-Memory-Cache, der durch SDK-Events befüllt wirdDiese Seite

​
Den authentifizierten Benutzer abrufen

api.user.get() gibt eine User-Instanz zurück, die die Kontodetails, den aktuellen Plan, die eigenen Anwendungen und die eigenen Datenbanken enthält. 
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 und user.databases sind Collection-Instanzen (eine Map-Unterklasse). Iterieren Sie darüber wie über jede Map: 
for (const [id, app] of user.applications) {
    console.log(`${app.name} (${id}) — ${app.ram}MB ${app.language}`);
}

​
Eine einzelne Anwendung abrufen

Verwenden Sie api.applications.fetch(id), um eine vollständig befüllte Application (oder WebsiteApplication, wenn die App eine Website-Domain hat) abzurufen. 
const app = await api.applications.fetch("abc123def456abc123def456");

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

if (app.isWebsite()) {
    // eingegrenzt auf WebsiteApplication — `.network` ist verfügbar
    await app.network.purgeCache();
}
Die veraltete Überladung api.applications.get(id) existiert weiterhin, gibt aber die leichtgewichtigere BaseApplication zurück und wird nur aus Gründen der Abwärtskompatibilität beibehalten. Bevorzugen Sie .fetch() für v4.

​
Snapshot-Verlauf auflisten (kontoweit)

const appSnapshots = await api.user.snapshots("applications");
const dbSnapshots  = await api.user.snapshots("databases");
Siehe Snapshots für Details zu Snapshot-Payloads.

​
Plattformstatus

api.service.status() stellt den aggregierten Plattformzustand bereit (dieselben Daten, die auf der öffentlichen Statusseite angezeigt werden). 
const status = await api.service.status();

console.log(status.status);  // "ok" | "degraded" | "down"
console.log(status.message); // menschenlesbare Zusammenfassung
Anders als die meisten v2-Endpoints kapselt diese Route ihr Payload nicht in den Standard-Envelope { status, response }.

​
Client-Cache

Der Client unterhält einen In-Memory-Cache, den das SDK synchron hält, während Sie Aufrufe tätigen: 
api.cache.user;   // zuletzt abgerufener User
// jede Anwendungsinstanz stellt außerdem app.cache.status / .logs / .snapshots bereit
Das SDK emittiert typisierte Events, die Sie abonnieren können: 
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}`);
});

​
Fehlerbehandlung

Fehlgeschlagene Anfragen werfen einen SquareCloudAPIError. Der Fehler stellt eine stabile code-Eigenschaft bereit, auf die Sie verzweigen können, um Fehlermodi zu unterscheiden. 
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);
    }
}