SDK Python: snapshots e backups

Snapshots são backups do armazenamento de uma aplicação ou de um banco de dados. Aplicações e bancos de dados compartilham os mesmos três métodos:

client.apps.snapshots: list(app_id), create(app_id), restore(app_id, name, version_id)
client.databases.snapshots: list(database_id), create(database_id), restore(database_id, name, version_id)

Quantos snapshots você pode criar por dia depende do seu plano (veja Limites). Os exemplos usam o client de Criando o cliente. app_id é o id de uma das suas aplicações: client.account.me() lista todas.

Listando snapshots

for snapshot in client.apps.snapshots.list(app_id):
    print(snapshot["name"], snapshot["version_id"], snapshot["size"], snapshot["modified"])

Campo	Descrição
`name`	O id do snapshot que `restore` recebe
`version_id`	A versão que `restore` recebe
`size`	Tamanho em bytes
`modified`	Quando foi criado
`url`	URL de download assinada, válida por 30 dias
`key`	Query string assinada da URL
`runtime`	Engine do banco de dados ou linguagem da aplicação (`None` em snapshots antigos)
`origin`	`"automatic"`, `"manual"` ou `None`

Criando um snapshot

create() aguarda o snapshot (pelo menos 120 s antes de expirar). Um snapshot grande pode não terminar a tempo: a API então responde 202 e o SDK retorna {'pending': True}. O snapshot continua sendo gerado e aparece em list() sozinho, geralmente em até 2 minutos. Caso contrário, retorna {'pending': False, 'url': ..., 'key': ...}.

result = client.apps.snapshots.create(app_id)

if result["pending"]:
    # Poll list() later. Do not call create() again: that starts a new snapshot.
    pass
else:
    print(result["url"])  # signed download URL, valid 30 days

Nunca chame create() novamente para verificar um snapshot pendente: isso inicia um novo e conta para a cota diária de snapshots do plano. Consulte list() em vez disso.

Restaurando um snapshot

restore(id, name, version_id) recebe o name e o version_id de um snapshot listado.

latest = client.apps.snapshots.list(app_id)[0]

client.apps.snapshots.restore(app_id, latest["name"], latest["version_id"])

Status	Código	Quando
400	`MISSING_PARAMETERS`	`name` ou `version_id` está ausente
400	`INVALID_SNAPSHOT_ID`, `INVALID_VERSION_ID`	Não é um `name`/`version_id` da listagem
400	`SNAPSHOT_DATABASE_MISMATCH`	A engine do snapshot não corresponde ao tipo do banco de dados (apenas bancos de dados)
404	`SNAPSHOT_NOT_FOUND`	Nenhum snapshot com esse nome e versão
404	`SNAPSHOT_RESTORE_FAILED`	A restauração não pôde ser despachada (a falha mais comum)
413	`PAYLOAD_TOO_LARGE`	O snapshot é grande demais para ser restaurado

Baixando um snapshot

client.download_snapshot(url, dest) transmite um arquivo de snapshot a partir da sua url assinada (de list() ou create()) para o disco e retorna o caminho em que escreveu. Ele não chama a API: a chave de API nunca é enviada ao host de armazenamento. Nada é armazenado em memória.

dest é um caminho de arquivo, ou um diretório para manter o nome do arquivo remoto. Um caminho terminado em / é criado como diretório.
Os dados vão para um arquivo .part que é renomeado quando termina, então um download que falhe nunca sobrescreve um arquivo anterior.
Não há timeout para o download inteiro: timeout limita cada leitura.

latest = client.apps.snapshots.list(app_id)[0]

path = client.download_snapshot(latest["url"], "backup.zip")
print("saved to", path)

# Or into a directory, keeping the remote name
client.download_snapshot(latest["url"], "backups/")

Com o AsyncSquareCloud, é await client.download_snapshot(url, dest). Uma URL expirada ou inválida lança um SquareCloudAPIError com o status HTTP do host de armazenamento e UNKNOWN_ERROR. Um destino em que não é possível escrever lança um OSError.

Snapshots da conta

client.account.snapshots(scope=None) lista todos os snapshots da conta, opcionalmente apenas "applications" ou "databases" (keyword-only). Requer um plano ativo e compartilha o rate limit dos endpoints de rede (429 RATE_LIMITED).

everything = client.account.snapshots()
databases = client.account.snapshots(scope="databases")

Status	Código	Quando
400	`INVALID_SCOPE`	`scope` não é `applications` nem `databases`
402	`UPGRADE_REQUIRED`	A conta não tem um plano ativo
429	`RATE_LIMITED`	Rate limit atingido

Limites

create() é limitado a uma chamada a cada 180 segundos e a uma cota diária que depende do plano: ultrapassar a cota resulta em 429 DAILY_SNAPSHOTS_LIMIT_REACHED.
Enquanto uma restauração está em andamento, excluir a aplicação ou iniciar o banco de dados resulta em 403 RESTORE_IN_PROGRESS.

Próximos passos

Bancos de dados

Crie e gerencie bancos de dados.

Referência da API de snapshots

Os endpoints REST por trás destes métodos.

Snapshots pela CLI

As mesmas ações pelo terminal.

CLI

VS Code

SDKs

SDK Python: snapshots e backups

Listando snapshots

Criando um snapshot

Restaurando um snapshot

Baixando um snapshot

Snapshots da conta

Limites

Próximos passos

Bancos de dados

Referência da API de snapshots

Snapshots pela CLI

​Listando snapshots

​Criando um snapshot

​Restaurando um snapshot

​Baixando um snapshot

​Snapshots da conta

​Limites

​Próximos passos

Bancos de dados

Referência da API de snapshots

Snapshots pela CLI

Listando snapshots

Criando um snapshot

Restaurando um snapshot

Baixando um snapshot

Snapshots da conta

Limites

Próximos passos