Skip to main content
Esta página documenta o squarecloud-api 5.0, uma reescrita do SDK. Vindo da v4? Leia o guia de migração v4 → v5.

Requisitos

O pacote não tem nenhuma dependência em tempo de execução (apenas a biblioteca padrão: http.client, json, ssl) e é totalmente tipado (py.typed): as respostas são TypedDicts que seu editor e seu verificador de tipos entendem.

Instalação

O pacote é instalado como squarecloud-api e importado como squarecloud. A versão instalada é squarecloud.__version__.

Chave de API e escopos

Crie uma chave em squarecloud.app/account/security. O SDK a envia como está no header Authorization (sem o prefixo Bearer). Uma chave pode ser limitada a escopos (apps:read, apps:deploy, apps:control, ai:chat, …) e a aplicações ou bancos de dados específicos:
  • Uma chamada fora desses limites lança um SquareCloudAPIError com 403 MISSING_SCOPE ou RESOURCE_NOT_ALLOWED.
  • Métodos de listagem (account.me(), apps.status_all(), …) retornam apenas os recursos que a chave pode ver.
  • Uma chave desconhecida, revogada ou expirada resulta em 401 ACCESS_DENIED.
Mantenha a chave fora do seu código-fonte: leia-a do ambiente (os.environ["SQUARECLOUD_API_KEY"]) ou de um gerenciador de segredos.
Os exemplos leem a chave da variável de ambiente SQUARECLOUD_API_KEY. Defina-a no terminal em que você vai executá-los:

Criando o cliente

O SDK tem dois clientes com os mesmos grupos e métodos:
  • SquareCloud é síncrono e thread-safe: compartilhe uma única instância entre threads. Cada thread reutiliza sua própria conexão keep-alive.
  • AsyncSquareCloud é a mesma API com await. Cada chamada executa o cliente síncrono em asyncio.to_thread, então o event loop nunca é bloqueado.
Os dois imprimem o nome da sua conta e o número de aplicações que a chave pode ver:
Sair do bloco with / async with fecha as conexões do pool. Sem um bloco, chame client.close() quando terminar. close() é um método comum (síncrono) nos dois clientes. Uma chave vazia ou composta apenas de espaços lança um ValueError no construtor, antes de qualquer requisição.

O cliente assíncrono

AsyncSquareCloud difere de SquareCloud em apenas três pontos:
  • Todo método retorna uma coroutine: await client.apps.status(app_id).
  • close() é síncrono: chame-o sem await.
  • apps.realtime(app_id) não é aguardado: ele retorna um AsyncRealtime que você consome com async for (veja Tempo real).
Como cada chamada roda em uma thread de trabalho, você pode executar chamadas em paralelo com asyncio.gather:
Cancelar uma task em espera não interrompe a requisição que já está rodando na sua thread de trabalho: a chamada ainda termina (ou expira) em segundo plano.

Opções

As opções são keyword-only, e o AsyncSquareCloud recebe as mesmas.
O cliente guarda a chave apenas nos seus headers privados de requisição: não existe um atributo client.api_key, e o logger do SDK nunca a escreve.

Módulos

O pacote exporta SquareCloud, AsyncSquareCloud, SquareCloudAPIError, BASE_URL, HTTPTransport, os protocolos Transport e Response, Realtime, AsyncRealtime e __version__. Os tipos de resposta (App, RuntimeStats, Snapshot, …) ficam em squarecloud.types:

Convenções

Ids primeiro, dados simples de volta

Todo método recebe o id do recurso como primeiro argumento e retorna dados simples: cada resposta é um TypedDict, que em tempo de execução é um dict comum (sem classes, sem cache), então os campos que a API adicionar no futuro são mantidos. Os nomes dos campos são os da própria API (created_at, version_id, lastModified, joinedAt, netIO, …), então a referência da API se aplica diretamente.
  • Mutações retornam None, a menos que a API retorne dados (envs.*, deploys.set_webhook, deploys.link_github_app, databases.reset_credentials e os métodos create).
  • Um resultado string nunca é None: ele é '' quando a API não envia nada.
  • Listas vêm completas em uma única chamada: não há paginação.
  • Modificadores opcionais são keyword-only (status(app_id, raw=True), commit(app_id, file, path="/src")). A única exceção é o path opcional de files.list, que também pode ser passado por posição.
Os métodos são bound methods comuns, então você pode guardar uma referência a eles:

Aplicações de workspace

Todo app_id também aceita a forma composta <appId>-<workspaceId> para atuar sobre uma aplicação compartilhada com você por meio de um workspace. workspaces.get() e workspaces.list() retornam ids brutos; você mesmo monta o id composto:

Ids são codificados

Ids no caminho da URL são codificados com percent-encoding. Um id vazio, . ou .. chegaria a uma rota diferente, então ele falha localmente com INVALID_ID (status 0) antes que qualquer coisa seja enviada. As rotas de workspace enviam seus ids no corpo: nelas, o INVALID_ID (400) vem do servidor.

Datas

Os argumentos start e end (veja Rede) aceitam uma string ISO 8601 (enviada como está) ou um datetime (enviado em UTC). Um datetime naive é tratado como horário local e convertido para UTC, então prefira os aware (datetime.now(UTC)). As datas nas respostas permanecem como a API as envia (strings ISO, ou milissegundos Unix onde a API os usa).

Timeouts

timeout limita cada operação de socket: a conexão e cada leitura ou escrita. Uma resposta que continua enviando dados pode levar mais do que timeout no total. Um timeout de 0 ou menos desativa todos os timeouts, incluindo os mínimos de 120 s. As chamadas não podem ser canceladas depois de enviadas: o único stream que você pode interromper no meio é o apps.realtime(), com close() a partir de qualquer thread. Para um upload longo, mantenha o timeout padrão para que uma conexão morta seja detectada na conexão, e execute-o em uma thread ou com o AsyncSquareCloud se o resto do seu programa precisar continuar rodando.

Conta

client.account.me() retorna o usuário autenticado, além das aplicações e bancos de dados que a chave pode ver.
client.account.snapshots(scope=...) lista todos os snapshots da conta: veja Snapshots.

Status da plataforma

client.service.status() retorna o status público da plataforma. A rota não exige uma chave válida, mas o cliente ainda requer uma chave não vazia.
unknown significa que a própria verificação não pôde ser executada: não é evidência de uma indisponibilidade.

Avançado

Transporte personalizado

transport= substitui a camada HTTP. Use-o para proxies, tracing ou testes. Um transporte é qualquer callable com esta assinatura:
O objeto retornado precisa de status, read(), readline() e close(): um http.client.HTTPResponse serve. As novas tentativas, o mapeamento de erros e o desempacotamento de {status, response} ficam no cliente, então um transporte apenas move bytes. HTTPTransport(timeout=30.0) é o transporte padrão: uma conexão keep-alive por thread e host, respostas comprimidas com gzip (exceto em streams) e timeout como limite de conexão das chamadas sem timeout próprio. Você pode encapsulá-lo:
client.close() fecha as conexões do transporte padrão. Um transporte personalizado que tenha um método close() também é fechado.

Registro de logs

O SDK registra cada requisição em DEBUG no logger squarecloud: método, caminho e status, nunca corpos ou chaves. Ele apenas anexa um NullHandler, então nada é impresso até você configurar o logging:

Próximos passos

Gerenciando aplicações

Status, ciclo de vida, logs e métricas.

Erros

Classe de erro, novas tentativas e rate limits.

Introdução à API

URL base, autenticação e uma primeira requisição.

Início rápido da CLI

Faça deploy e gerencie aplicações pelo terminal.