> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud API 入门：基础 URL 与首个请求

> 开始使用 Square Cloud REST API：v2 基础 URL、Authorization 请求头、第一个 curl 请求、响应结构、ID、权限范围和错误处理。

Square Cloud API 是基于 HTTPS 的 REST API，覆盖你在控制台中完成的操作：部署和控制应用、读取应用的日志和指标，以及管理文件、环境变量、快照、数据库和 workspace。它以 JSON 收发数据，但有两个例外：[上传](/zh/api-reference/endpoint/apps/upload)和[提交](/zh/api-reference/endpoint/apps/commit)以 `multipart/form-data` 接收 zip 文件，[实时日志](/zh/api-reference/endpoint/apps/realtime)则以 Server-Sent Events 推送数据。

## 基础 URL

本参考中的每个端点都相对于：

```bash theme={"system"}
https://api.squarecloud.app/v2
```

[Blob Storage](/zh/blob-reference/quickstart) 是一个独立的 API，拥有自己的基础 URL `https://blob.squarecloud.app/v1`，并使用同一个 API 密钥。

## 身份验证

在[账户安全设置](https://squarecloud.app/zh/account/security)中创建 API 密钥，并在每个请求的 `Authorization` 请求头中发送。`Bearer ` 前缀是可选的。

```bash theme={"system"}
Authorization: <api_key>
```

密钥只会在创建时显示一次。请将其保存在服务器上的环境变量中，切勿放进客户端代码或代码仓库。每个密钥都带有限制其操作范围的权限范围：各端点所需的权限范围见[身份验证](/zh/api-reference/authentication)。

## 第一个请求

[账户信息](/zh/api-reference/endpoint/users/me)会返回你的个人资料、套餐，以及你拥有的所有应用和数据库。它需要具有 `account:read` 权限范围的密钥。

```bash theme={"system"}
export SQUARECLOUD_API_KEY="your-api-key"

curl https://api.squarecloud.app/v2/users/me \
  --header "Authorization: $SQUARECLOUD_API_KEY"
```

```json theme={"system"}
{
  "status": "success",
  "response": {
    "user": {
      "id": "1234567890",
      "name": "John Doe",
      "email": "john@example.com",
      "locale": "en-US",
      "plan": {
        "name": "standard-4",
        "memory": { "limit": 4096, "available": 3584, "used": 512 },
        "duration": 1780615237662
      },
      "created_at": "2024-05-01T12:00:00.000Z"
    },
    "applications": [
      {
        "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
        "name": "my-app",
        "ram": 512,
        "lang": "javascript",
        "domain": "my-app.squareweb.app",
        "custom": null,
        "cluster": "example-cluster",
        "created_at": "2024-05-01T12:00:00.000Z"
      }
    ],
    "databases": []
  }
}
```

如果收到 `401 ACCESS_DENIED`，说明密钥缺失或无法识别。如果收到 `403 MISSING_SCOPE`，说明密钥有效，但缺少 `account:read`。

## 响应格式

调用成功时返回 `2xx` 和 `"status": "success"`，如果有数据需要返回，则放在 `response` 中：

```json theme={"system"}
{ "status": "success", "response": { } }
```

启动或停止等操作只返回 `{ "status": "success" }`。调用失败时返回 `4xx` 或 `5xx`、`"status": "error"`，以及可用于分支处理的 `code`：

```json theme={"system"}
{ "status": "error", "code": "APP_NOT_FOUND" }
```

响应中的字段名使用 `snake_case`。所有错误代码及其处理方式见[错误代码](/zh/api-reference/errors)。

## ID

* **应用和数据库**使用 32 位十六进制 ID，例如 `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`。可以从[账户信息](/zh/api-reference/endpoint/users/me)或控制台中该资源的地址获取。
* **通过 workspace 与你共享的应用**在路径中写作 `<appId>-<workspaceId>`，例如 `/v2/apps/<appId>-<workspaceId>/status`。
* **workspace** 使用 32 位十六进制 ID。较早创建的 workspace 保留 40 位的 ID。

## 限制

每个账户每 60 秒有一定的请求额度，由套餐决定；部分端点另有自己的限制，会在其页面中注明。具体数值见[限制与约束](/zh/api-reference/limitations-and-restrictions)，`429` 的工作方式见[错误代码](/zh/api-reference/errors#速率限制)。

## OpenAPI 规范

整个 API 都由一份 [OpenAPI 文档](/zh/api-reference/openapi)描述，地址为 `https://api.squarecloud.app/v2/openapi.json`。你可以将其导入 Postman 或 Insomnia，或用它生成客户端。

<Tip>
  更喜欢类型化的客户端？适用于 [JavaScript](/zh/sdks/js/client)、[Python](/zh/sdks/py/client) 和 [Go](/zh/sdks/go/client) 的 [Square Cloud SDK](/zh/sdks/introduction) 封装了本参考中的每个端点，[CLI](/zh/cli-reference/quickstart) 则可在终端中完成相同的任务。
</Tip>

## 后续步骤

<CardGroup cols={2}>
  <Card title="身份验证与权限范围" icon="lock" href="/zh/api-reference/authentication">
    为每个集成挑选所需的权限范围。
  </Card>

  <Card title="错误代码" icon="triangle-exclamation" href="/zh/api-reference/errors">
    API 返回的所有代码及处理方式。
  </Card>

  <Card title="上传应用" icon="upload" href="/zh/api-reference/endpoint/apps/upload">
    一个请求即可部署 zip 文件。
  </Card>

  <Card title="速率限制" icon="gauge" href="/zh/api-reference/limitations-and-restrictions">
    各套餐的请求额度。
  </Card>
</CardGroup>