Crea Snapshot - Square Cloud

POST

apps

{app_id}

snapshots

Crea Snapshot

curl --request POST \
  --url https://api.squarecloud.app/v2/apps/{app_id}/snapshots \
  --header 'Authorization: <authorization>'

const options = {method: 'POST', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/snapshots"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
    "status": "success",
    "response": {
        "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D",
        "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D"
    }
}

{
  "status": "error",
  "code": "SNAPSHOT_PROCESSING"
}

{
  "status": "error",
  "code": "KEEP_CALM",
  "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
}

{
  "status": "error",
  "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
  "message": "You are being rate limited for daily snapshots. 8r/24h"
}

Ogni account può eseguire fino a (RAM / 256) * 2 snapshot ogni 24 ore.

string

obbligatorio

La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.

Crea Snapshot cattura una copia .zip puntuale dell’intero storage di un’applicazione e restituisce un URL di download firmato, offrendoti un punto di ripristino prima di una modifica rischiosa o un modo per scaricare un backup completo al di fuori della piattaforma. Per riportare l’applicazione a quello stato in seguito, passa lo snapshot risultante a Ripristina Snapshot; per ispezionare o scaricare snapshot precedenti senza crearne uno nuovo, usa Elenca Snapshot. Gli snapshot sono disponibili solo sui piani a pagamento, e la quota giornaliera scala in base alla RAM dell’applicazione ((RAM / 256) × 2 ogni 24 ore). Sulle applicazioni condivise in un workspace, il chiamante deve avere il ruolo di Amministratore.

Parametri

string

obbligatorio

L’ID dell’applicazione. Puoi trovarlo nell’URL della dashboard della tua applicazione.

Comportamento con soft deadline

Questa route segue un modello a soft deadline — non risponde più sempre in modo sincrono.

Se lo snapshot termina entro ~90 secondi, la route risponde con 200 success e un URL di download firmato (valido per 30 giorni), esattamente come prima.
Se lo snapshot impiega più di ~90 secondi per essere generato, la route risponde immediatamente con 202 e il codice SNAPSHOT_PROCESSING. Questo non è un errore. Lo snapshot continua a essere generato in background e comparirà da solo nell’elenco degli snapshot, tipicamente entro ~2 minuti. Questo è il comportamento atteso per le applicazioni di grandi dimensioni.

Non usare questo endpoint POST come meccanismo di polling. Per verificare se uno snapshot SNAPSHOT_PROCESSING è stato completato, usa l’endpoint List Snapshots (GET) — non un altro POST. Rieseguire il POST dopo che lo snapshot è terminato avvia un nuovo snapshot da zero.

Il client dovrebbe ramificare in base alla risposta come segue:

Risposta	Significato	Cosa fare
`status === "success"`	Lo snapshot è pronto.	Usa l’`url` per scaricarlo.
`status === "error"` e `code === "SNAPSHOT_PROCESSING"`	Lo snapshot è ancora in generazione.	Attendi ~2 minuti, poi conferma tramite List Snapshots (`GET`). Non rieseguire il `POST`.
`status === "error"` con qualsiasi altro `code`	Fallimento effettivo.	Gestisci l’errore (vedi sotto).

Risposta

string

Indica se la chiamata è andata a buon fine. success in caso di successo, error in caso contrario.

object

Il contenuto della risposta. Presente solo quando status è success.

Mostra Mostra oggetto

string

L’URL per scaricare lo snapshot della tua applicazione.

string

La chiave per scaricare lo snapshot della tua applicazione.

202

Restituito quando lo snapshot supera la soft deadline di ~90 secondi. Lo snapshot è ancora in generazione in background e comparirà da solo nell’elenco degli snapshot, tipicamente entro ~2 minuti. Non è un errore — attendi e conferma tramite l’endpoint di elenco GET.

Errori

Una richiesta di snapshot può essere rifiutata con 429 Too Many Requests. Usa il campo code per distinguere i due casi:

429

Cooldown a breve termine — hai raggiunto il limite per utente (1 richiesta / 5s) o per applicazione (1 richiesta / 180s). Attendi e riprova a breve.

429

Quota giornaliera raggiunta — l’account ha esaurito il numero di snapshot giornalieri consentiti dal suo piano ((RAM / 256) × 2 ogni 24h). La quota si libera man mano che la finestra mobile di 24 ore avanza; per un limite giornaliero più alto, effettua l’upgrade del piano.

{
    "status": "success",
    "response": {
        "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D",
        "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D"
    }
}

{
  "status": "error",
  "code": "SNAPSHOT_PROCESSING"
}

{
  "status": "error",
  "code": "KEEP_CALM",
  "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
}

{
  "status": "error",
  "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
  "message": "You are being rate limited for daily snapshots. 8r/24h"
}

Ripristina SnapshotRipristina un'applicazione a partire da uno snapshot della stessa.

Crea Snapshot

curl --request POST \
  --url https://api.squarecloud.app/v2/apps/{app_id}/snapshots \
  --header 'Authorization: <authorization>'

const options = {method: 'POST', headers: {Authorization: '<authorization>'}};

fetch('https://api.squarecloud.app/v2/apps/{app_id}/snapshots', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.squarecloud.app/v2/apps/{app_id}/snapshots",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.squarecloud.app/v2/apps/{app_id}/snapshots"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.squarecloud.app/v2/apps/{app_id}/snapshots")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
    "status": "success",
    "response": {
        "url": "https://snapshots.squarecloud.app/applications/23457145698959364/a23d130fcc9ddaf2d288ae9599a4292c32.zip?AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D",
        "key": "AWSAccessKeyId=i06Xdad2dRD74Pm8Xly&Expires=1753081182&Signature=riWPedawcsouRAPGU5n3kGHnWoOuw%3D"
    }
}

{
  "status": "error",
  "code": "SNAPSHOT_PROCESSING"
}

{
  "status": "error",
  "code": "KEEP_CALM",
  "message": "You already requested a snapshot recently. Please wait a minute before trying again. 1r/5s"
}

{
  "status": "error",
  "code": "DAILY_SNAPSHOTS_LIMIT_REACHED",
  "message": "You are being rate limited for daily snapshots. 8r/24h"
}

​Parametri

​Comportamento con soft deadline

​Risposta

​Errori

Parametri

Comportamento con soft deadline

Risposta

Errori