跳到主要内容

REST API

注意

REST API 目前处于 Beta 阶段，部分接口和响应可能调整。

授权​

REST API 只能通过 HTTPS 访问，并需要访问令牌。可在组织的账号页面生成令牌。

账号标签页

在 API Tokens 区域单击 Generate Token。

生成令牌

输入令牌名称，单击按钮创建，新窗口会显示访问令牌。

请保存令牌，因为关闭窗口后将无法再次查看。令牌应保密，不要分享给团队之外的人，也不要发布到论坛等公开位置。

新令牌

账号页面还可以撤销全部令牌或指定令牌，也可修改令牌名称。

移除令牌

调用 API 时，将 HTTP 请求的 Authorization 头设为：

Bearer [access_token]

将 [access_token] 替换为账号页面中生成的访问令牌。

例如：

curl -H "Authorization: Bearer nesgdxhiqe7hylfilr6ss1rds0gq1uj8" https://playcanvas.com/api/...

参数​

各路由接受不同参数。GET 请求中，未包含在 URL 路径内的参数可作为查询字符串传递。POST、PUT 和 DELETE 请求中，未包含在路径内的参数通常应编码为 JSON，并使用 Content-Type: application/json。

接口中常见参数如下：

project_id​

可在项目概览页的 URL 中找到。

项目 ID

scenes​

在编辑器中打开场景时，URL 包含场景 ID。

场景 ID

branch_id​

可在版本控制面板中找到，并选中复制。

分支 ID

响应格式​

REST API 各调用的响应格式遵循以下通用规则。

获取单个资源​

GET 单个资源时，返回包含所请求资源的 JSON 对象。

获取多个资源​

GET 多个资源时，例如列出项目应用，会返回以下格式的 JSON 对象：

{
    "result": [
        resource_1,
        resource_2,
        ...,
        resource_N
    ],
    "pagination": {
        "limit": number,
        "skip": number,
        "total": number
    }
}

此响应还包含分页信息，可以通过以下 URL 参数控制：

名称说明
limit响应包含的最大条目数。
skip从原始结果集中跳过的条目数。
sort排序字段名称，可用值请参阅各请求文档。
order1 为升序，-1 为降序。

例如，跳过前 16 项后获取 32 项，请求如下：

https://playcanvas.com/api/items?limit=32&skip=16

错误​

发生错误时，返回以下格式的 JSON 对象：

{
    "error": "This is the error message"
}

响应状态码也会设置为相应 HTTP 错误码。

请求限流​

REST API 调用有频率限制，可查询此接口了解实际额度。不同请求使用不同限流类型：

限流类型说明免费账号额度个人／组织账号额度
Normal（普通）普通请求限流每分钟 120 次每分钟 240 次
Strict（严格）严格请求限流每分钟 5 次每分钟 10 次
Assets（资源）资源请求限流每分钟 60 次每分钟 120 次

响应包含以下头，帮助调整调用频率：

名称说明
X-RateLimit-Limit每分钟允许的请求数。
X-RateLimit-Remaining当前分钟内剩余可用请求数。
X-RateLimit-Reset当前限流窗口重置的时间，使用 UTC Unix 时间戳秒数。

超过额度时，返回 429 Too Many Requests。必须等待当前窗口重置后才能继续请求。