数据库 - 快照
创建 snapshot
对你的数据库执行 snapshot。速率限制为每 5 秒 1 次请求。
POST
/
v2
/
databases
/
{database_id}
/
snapshots
创建 snapshot
curl --request POST \
--url https://api.squarecloud.app/v2/databases/{database_id}/snapshots \
--header 'Authorization: <authorization>'import requests
url = "https://api.squarecloud.app/v2/databases/{database_id}/snapshots"
headers = {"Authorization": "<authorization>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: '<authorization>'}};
fetch('https://api.squarecloud.app/v2/databases/{database_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/databases/{database_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/databases/{database_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))
}HttpResponse<String> response = Unirest.post("https://api.squarecloud.app/v2/databases/{database_id}/snapshots")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.squarecloud.app/v2/databases/{database_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/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D",
"key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%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"
}
每个账户每 24 小时最多可执行 (RAM / 256) * 2 次 snapshot。
参数
string
必填
数据库的 ID。
软截止时间行为
此路由遵循软截止时间模型 — 它不再总是同步响应。- 如果 snapshot 在 ~90 秒内完成,该路由将返回
200 success以及一个已签名的下载 URL(有效期 30 天),与之前完全相同。 - 如果 snapshot 生成时间超过 ~90 秒,该路由将立即返回
202以及代码SNAPSHOT_PROCESSING。这不是失败。 snapshot 会在后台继续生成,并会自行出现在 snapshot 列表中,通常在 ~2 分钟内。对于大型数据库来说这是预期行为。
请勿将此
POST 端点用作轮询机制。要检查处于 SNAPSHOT_PROCESSING 状态的 snapshot 是否已完成,请使用 List Snapshots(GET)端点 — 而不是另一个 POST。在 snapshot 完成后重新发起 POST 会从头开始一个全新的 snapshot。| 响应 | 含义 | 应执行的操作 |
|---|---|---|
status === "success" | snapshot 已就绪。 | 使用 url 下载它。 |
status === "error" 且 code === "SNAPSHOT_PROCESSING" | snapshot 仍在生成中。 | 等待 ~2 分钟,然后通过 List Snapshots(GET)确认。请勿重新 POST。 |
status === "error" 且带有任何其他 code | 实际失败。 | 处理该错误(见下文)。 |
响应
string
指示调用是否成功。成功时为
success,否则为 error。object
202
当 snapshot 超过 ~90 秒的软截止时间时返回。snapshot 仍在后台生成,并会自行出现在 snapshot 列表中,通常在 ~2 分钟内。这不是错误 — 请等待并通过
GET 列表端点确认。错误
snapshot 请求可能会被拒绝并返回429 Too Many Requests。使用 code 字段来区分这两种情况:
429
短期冷却 — 你触发了每用户(每 5 秒 1 次请求)或每数据库(每 180 秒 1 次请求)的限制。请退避并稍后重试。
429
已达到每日配额 — 该账户已用完其套餐的每日 snapshot 额度(每 24 小时 (RAM / 256) × 2 次)。随着滚动的 24 小时窗口推进,配额会释放;如需更高的每日额度,请升级套餐。
{
"status":"success",
"response":{
"url":"https://snapshots.squarecloud.app/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D",
"key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%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"
}
⌘I
创建 snapshot
curl --request POST \
--url https://api.squarecloud.app/v2/databases/{database_id}/snapshots \
--header 'Authorization: <authorization>'import requests
url = "https://api.squarecloud.app/v2/databases/{database_id}/snapshots"
headers = {"Authorization": "<authorization>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: '<authorization>'}};
fetch('https://api.squarecloud.app/v2/databases/{database_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/databases/{database_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/databases/{database_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))
}HttpResponse<String> response = Unirest.post("https://api.squarecloud.app/v2/databases/{database_id}/snapshots")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.squarecloud.app/v2/databases/{database_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/databases/384443501775028242/a14b8d5e1cb7405a851eb4c075506121.zip?AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%3D",
"key":"AWSAccessKeyId=accesskey&Expires=1757683751&Signature=JR3danhvtVywQmcaIanWsoJFqhQ%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"
}

