SDK Python: gestire le applicazioni

Ogni metodo di questa pagina si trova su client.apps e accetta come primo argomento l’id dell’app. Un app_id può anche essere il composto <appId>-<workspaceId> di un’app condivisa tramite un workspace.

import os

from squarecloud import SquareCloud

client = SquareCloud(os.environ["SQUARECLOUD_API_KEY"])
app_id = "abc123def456abc123def456"

Con AsyncSquareCloud, ogni chiamata qui sotto è identica, con await davanti. Per elencare le tue app, usa client.account.me(): la sua lista applications contiene ogni app che la chiave può vedere.

Recuperare un’applicazione

app = client.apps.get(app_id)

print(app["id"], app["name"], app["language"], app["ram"], app["cluster"], app["created_at"])

Campo	Tipo	Descrizione
`id`	`str`	Id dell’app
`name`	`str`	Nome visualizzato
`desc`	`str`, facoltativo	Descrizione
`owner`	`str`	Id utente del proprietario
`cluster`	`str`	Cluster su cui gira l’app
`ram`	`int`	RAM allocata in MB
`language`	`str`	Linguaggio del runtime
`domain`	`str \| None`, facoltativo	Host predefinito `<subdomain>.squareweb.app`; assente o `None` per le app non web
`custom`	`str \| None`, facoltativo	Dominio personalizzato; assente o `None` se non è impostato
`created_at`	`str`	Data di creazione (ISO 8601)

I campi facoltativi possono mancare dal dict: leggili con app.get("domain").

Stato

status(app_id) restituisce lo stato in tempo reale con valori formattati:

status = client.apps.status(app_id)

print(status["status"])   # e.g. "running", "exited"
print(status["running"])  # True
print(status["cpu"])      # "0.5%"
print(status["ram"])      # "120.4MB" (RAM in use)
print(status["storage"], status["network"]["total"], status["network"]["now"])
print(status["uptime"])   # Unix ms of the last start, None when stopped

Passa raw=True per ottenere invece dei numeri (cpu in %, ram in MB, network["total"] e network["now"] come coppie di byte [in, out]):

raw = client.apps.status(app_id, raw=True)

print(raw["cpu"], raw["ram"], raw["network"]["total"])  # 0.5 120.4 [1024, 2048]

uptime è un timestamp (quando l’app è stata avviata), non una durata. Usa time.time() * 1000 - status["uptime"] per sapere da quanto tempo è attiva, in ms.

Stato di tutte le applicazioni

status_all() restituisce un riepilogo per ogni app che la chiave può vedere, in un’unica richiesta. cpu e ram sono presenti solo mentre l’app è in esecuzione.

for item in client.apps.status_all():
    print(item["id"], f"{item['cpu']} {item['ram']}" if item["running"] else "stopped")

# Only the apps of one workspace
shared = client.apps.status_all(workspace_id=workspace_id)

Avvio, arresto e riavvio

client.apps.start(app_id)
client.apps.stop(app_id)
client.apps.restart(app_id)

Il server tiene aperte queste chiamate finché il container non agisce, quindi attendono almeno 120 s prima di andare in timeout. Quando la piattaforma rifiuta l’azione, la chiamata solleva un SquareCloudAPIError con status 409, un code e un messaggio vuoto (''):

Codice	Significato
`CONTAINER_ALREADY_STARTED`	`start` su un’app in esecuzione
`CONTAINER_ALREADY_STOPPED`	`stop` su un’app arrestata
`CONTAINER_TEMPORARILY_SUSPENDED`	L’app è sospesa
`CONTAINER_NOT_FOUND`	Il container non esiste sul cluster
`CONTAINER_INSUFFICIENT_DISK_SPACE`	Spazio su disco insufficiente per l’avvio
`CONTAINER_NETWORK_CONFLICT`	Conflitto di rete sul cluster
`ACTION_FAILED`	Il cluster non è riuscito a eseguire l’azione

Anche “già avviata” e “già arrestata” sono errori. Se per te significano successo, gestiscili:

from squarecloud import SquareCloudAPIError

try:
    client.apps.start(app_id)
except SquareCloudAPIError as error:
    if error.code != "CONTAINER_ALREADY_STARTED":
        raise

Log

logs(app_id) restituisce l’output più recente della console come un’unica stringa ('' quando non ce n’è).

print(client.apps.logs(app_id))

Per un flusso di log in tempo reale, usa Realtime.

Metriche

metrics(app_id) restituisce le ultime 24 ore, un punto ogni 5 minuti, dal più recente.

latest = client.apps.metrics(app_id)[0]

print(latest["date"], latest["cpu"], latest["ram"], latest["net"])

Domini e load balancer

domains() elenca gli hostname predefiniti e personalizzati di ogni app. load_balancers() elenca i domini condivisi da più app, con il limite del tuo piano.

for domain in client.apps.domains():
    print(domain["app_id"], domain["hostname"], domain["type"])  # type: "subdomain" | "custom"

balancers = client.apps.load_balancers()
print(balancers["limit"])
for balancer in balancers["balancers"]:
    print(balancer["hostname"], [app["id"] for app in balancer["apps"]])

Per impostare un dominio personalizzato, vedi Rete.

Eliminare un’applicazione

client.apps.delete(app_id)

L’eliminazione è permanente. Crea prima uno snapshot se potresti avere di nuovo bisogno dei file.

Prossimi passi

Commit e upload

Crea un’app da uno zip o inviale dei file.

Riferimento API delle applicazioni

Gli endpoint REST dietro questi metodi.

Gestire le app dalla CLI

Le stesse azioni dal terminale.

CLI

VS Code

SDKs

SDK Python: gestire le applicazioni

Recuperare un’applicazione

Stato

Stato di tutte le applicazioni

Avvio, arresto e riavvio

Log

Metriche

Domini e load balancer

Eliminare un’applicazione

Prossimi passi

Commit e upload

Riferimento API delle applicazioni

Gestire le app dalla CLI

​Recuperare un’applicazione

​Stato

​Stato di tutte le applicazioni

​Avvio, arresto e riavvio

​Log

​Metriche

​Domini e load balancer

​Eliminare un’applicazione

​Prossimi passi

Commit e upload

Riferimento API delle applicazioni

Gestire le app dalla CLI

Recuperare un’applicazione

Stato

Stato di tutte le applicazioni

Avvio, arresto e riavvio

Log

Metriche

Domini e load balancer

Eliminare un’applicazione

Prossimi passi