SDK de Python: gestionar aplicaciones

Todos los métodos de esta página están en client.apps y reciben primero el id de la aplicación. Un app_id también puede ser el id compuesto <appId>-<workspaceId> de una aplicación compartida a través de un workspace.

import os

from squarecloud import SquareCloud

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

Con AsyncSquareCloud, cada llamada de abajo es igual con await delante. Para listar tus aplicaciones, usa client.account.me(): su lista applications contiene todas las aplicaciones que la clave puede ver.

Obtener una aplicación

app = client.apps.get(app_id)

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

Campo	Tipo	Descripción
`id`	`str`	Id de la aplicación
`name`	`str`	Nombre visible
`desc`	`str`, opcional	Descripción
`owner`	`str`	Id de usuario del propietario
`cluster`	`str`	Clúster en el que se ejecuta la aplicación
`ram`	`int`	RAM asignada en MB
`language`	`str`	Lenguaje del runtime
`domain`	`str \| None`, opcional	Host por defecto `<subdomain>.squareweb.app`; ausente o `None` en aplicaciones que no son web
`custom`	`str \| None`, opcional	Dominio personalizado; ausente o `None` cuando no hay ninguno configurado
`created_at`	`str`	Fecha de creación (ISO 8601)

Los campos opcionales pueden faltar en el dict: léelos con app.get("domain").

Estado

status(app_id) devuelve el estado en vivo con valores formateados:

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

Pasa raw=True para obtener números en su lugar (cpu en %, ram en MB, network["total"] y network["now"] como pares de bytes [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 es una marca de tiempo (cuándo se inició la aplicación), no una duración. Usa time.time() * 1000 - status["uptime"] para saber cuánto tiempo lleva en marcha, en ms.

Estado de todas las aplicaciones

status_all() devuelve un resumen por cada aplicación que la clave puede ver, en una sola petición. cpu y ram solo están presentes mientras la aplicación se ejecuta.

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)

Iniciar, detener y reiniciar

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

El servidor mantiene estas llamadas abiertas hasta que el contenedor actúa, así que esperan al menos 120 s antes de agotar el tiempo. Cuando la plataforma rechaza la acción, la llamada lanza un SquareCloudAPIError con estado 409, un code y un mensaje vacío (''):

Código	Significado
`CONTAINER_ALREADY_STARTED`	`start` sobre una aplicación en ejecución
`CONTAINER_ALREADY_STOPPED`	`stop` sobre una aplicación detenida
`CONTAINER_TEMPORARILY_SUSPENDED`	La aplicación está suspendida
`CONTAINER_NOT_FOUND`	El contenedor no existe en el clúster
`CONTAINER_INSUFFICIENT_DISK_SPACE`	No hay suficiente disco para iniciar
`CONTAINER_NETWORK_CONFLICT`	Conflicto de red en el clúster
`ACTION_FAILED`	El clúster no pudo realizar la acción

“Ya iniciada” y “ya detenida” también son errores. Si para ti significan éxito, gestiónalos:

from squarecloud import SquareCloudAPIError

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

Logs

logs(app_id) devuelve la salida de consola más reciente como un único string ('' cuando no hay ninguna).

print(client.apps.logs(app_id))

Para un stream de logs en vivo, usa Tiempo real.

Métricas

metrics(app_id) devuelve las últimas 24 horas, un punto cada 5 minutos, del más reciente al más antiguo.

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

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

Dominios y balanceadores de carga

domains() lista los nombres de host por defecto y personalizados de todas las aplicaciones. load_balancers() lista los dominios compartidos por varias aplicaciones, con el límite de tu plan.

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"]])

Para configurar un dominio personalizado, consulta Red.

Eliminar una aplicación

client.apps.delete(app_id)

La eliminación es permanente. Crea primero un snapshot si es posible que vuelvas a necesitar los archivos.

Próximos pasos

Commit y subida

Crea una aplicación a partir de un zip o envíale archivos.

Referencia de la API de aplicaciones

Los endpoints REST detrás de estos métodos.

Gestionar aplicaciones desde la CLI

Las mismas acciones desde la terminal.

CLI

VS Code

SDKs

SDK de Python: gestionar aplicaciones

Obtener una aplicación

Estado

Estado de todas las aplicaciones

Iniciar, detener y reiniciar

Logs

Métricas

Dominios y balanceadores de carga

Eliminar una aplicación

Próximos pasos

Commit y subida

Referencia de la API de aplicaciones

Gestionar aplicaciones desde la CLI

​Obtener una aplicación

​Estado

​Estado de todas las aplicaciones

​Iniciar, detener y reiniciar

​Logs

​Métricas

​Dominios y balanceadores de carga

​Eliminar una aplicación

​Próximos pasos

Commit y subida

Referencia de la API de aplicaciones

Gestionar aplicaciones desde la CLI

Obtener una aplicación

Estado

Estado de todas las aplicaciones

Iniciar, detener y reiniciar

Logs

Métricas

Dominios y balanceadores de carga

Eliminar una aplicación

Próximos pasos