Offizielle SDKs für JavaScript, Python und Go

Wähle dein SDK

Alle SDKs sind Open Source und auf GitHub verfügbar. Sie haben keine Laufzeitabhängigkeiten und geben die Daten der API unverändert zurück, einschließlich der Feldnamen.

JavaScript

@squarecloud/api v6. Apps, Datenbanken, Workspaces, Deploys, Netzwerk, Realtime, Snapshots und KI, auf Node.js, Deno, Bun und Edge-Runtimes.

Python

squarecloud-api v5. Derselbe Funktionsumfang, mit einem synchronen und einem asynchronen Client, nur mit der Standardbibliothek.

Go

sdk-api-go v3. Derselbe Funktionsumfang, mit context bei jedem Aufruf und einem einzigen Fehlertyp.

Blob Storage (JavaScript)

@squarecloud/blob v4. Uploads bis 10 GiB, private Objekte, Links, Freigaben, Regeln und das S3-Gateway, in Node.js und im Browser.

Auf einen Blick

SDK	Paket	Version	Laufzeit	Installation
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+ und Browser	`npm install @squarecloud/blob`

Schnellstart

Mach deinen ersten Aufruf in wenigen Minuten. Jedes Programm unten gibt deinen Kontonamen aus und wie viele Apps dein API-Schlüssel sehen kann.

API-Schlüssel erstellen

Erstelle einen Schlüssel in den Sicherheitseinstellungen deines Kontos. Behandle ihn wie ein Passwort: Er gehört nicht in deinen Quellcode.

Umgebungsvariable SQUARECLOUD_API_KEY setzen

Die Beispiele lesen den Schlüssel aus SQUARECLOUD_API_KEY. Setze die Variable in dem Terminal, in dem du sie ausführst:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

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

SDK installieren und ersten Aufruf machen

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 .

Ausgabe prüfen

Das Programm gibt deinen Kontonamen und die Anzahl der Apps aus, die der Schlüssel sehen kann:

Hi Jane, you have 3 apps

Ein Fehler 401 ACCESS_DENIED bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist. Ist die Variable nicht gesetzt, bricht das Programm ab, bevor es etwas sendet.

Was jedes SDK abdeckt

Die SDKs für JavaScript, Python und Go decken die gesamte Square Cloud API ab: dieselben 67 Operationen plus das Herunterladen von Snapshot-Dateien. Sie teilen dieselbe Seitenstruktur, dieselben Beispiele und dasselbe Verhalten:

eine Fehlerklasse mit dem HTTP-Status und dem Fehlercode der API;
ein Timeout von 30 Sekunden und mindestens 120 Sekunden für Aufrufe, die der Server offen hält;
Wiederholungen nur bei Fehlern, die sich gefahrlos wiederholen lassen, niemals bei einem 429;
IDs der Form <appId>-<workspaceId>, um auf Apps zuzugreifen, die über einen Workspace geteilt werden.

Das Blob Storage SDK deckt die Blob API und das S3-Gateway ab. Es ist ein separates Paket mit eigenem Client, eigenen Zugangsdaten und eigenen Fehlercodes.

Fehlerreferenzen

Die Fehlerseite jedes SDK behandelt seine Fehlerklasse, Wiederholungen und Rate Limits. Die Fehlercodes selbst kommen von der API: Die Referenz der API-Fehler listet jeden auf, und die Referenz der Blob-API-Fehler listet die Codes von Blob Storage auf.

SDK	Fehler, Wiederholungen und Rate Limits
JavaScript	`SquareCloudAPIError`
Python	`SquareCloudAPIError`
Go	`*APIError`
Blob Storage	`SquareCloudBlobError`

Upgrade

Jede oben genannte Version der API-SDKs ist eine Neuentwicklung. Siehe die Migrationsleitfäden: JavaScript v5 → v6, Python v4 → v5, Go v2 → v3 und Blob v3 → v4. Square Cloud verbessert seine SDKs laufend und fügt neue Sprachen hinzu. Fehlt deine, sag uns Bescheid.

Nächste Schritte

Einführung in die API

Die REST-API direkt mit curl aufrufen.

CLI-Schnellstart

Apps im Terminal deployen und verwalten.

Schnellstart der Blob-API

Eine Datei mit curl in Blob Storage hochladen.

​Wähle dein SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

​Auf einen Blick

​Schnellstart

​Was jedes SDK abdeckt

​Fehlerreferenzen

​Upgrade

​Nächste Schritte