StarDots.io Logo

StarDots

返回文档首页

开放API

本章将介绍如何集成开放API,以下内容知识面向开发者,假设您具有一定的编程基础。

你是 AI Agent 吗?查看 Markdown 文档
本页目录

认证

StarDots 通过读取客户端发起的 http 请求中的 headers 字段,对相关字段进行验证来完成鉴权,因此所有的开放 API 请求都应该携带这些鉴权字段信息,并且需要注意这些字段区分大小写,所有字段都应该小写。

  • x-stardots-timestamp
    描述
    当前时间戳(秒)。与 StarDots 服务器的差异不能超过 60 秒。注意:StarDots 的时区为 Asia/Singapore,即 UTC+8。
  • x-stardots-nonce
    描述
    4~20个字符的随机字符串,只能包含大写字母、小写字母和数字,注意此值在60秒内必须是唯一的。
  • x-stardots-key
    描述
    StarDots发布的key信息。
  • x-stardots-sign
    描述
    签名字段是将以上字段按照一定的签名算法组合生成的字符串,具体的签名算法接下来会介绍。

签名算法

我们假设以下字段值

key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
secret
Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp
x-stardots-timestamp
1728958751
x-stardots-nonce
fQvDmMLnKE
x-stardots-key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
Key和Secret由StarDots颁发,您可以在控制台设置页面找到。

然后我们组装上述字段值

needSignStr = x-stardots-timestamp + "|" + secret + "|" + x-stardots-nonce

接下来,我们计算上面组装的字符串的 MD5 摘要

signStrAfterMD5 = md5("1728958751|Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp|fQvDmMLnKE")
signStrAfterMD5 = "51dabfe4b47e73d4a3b85fe29c4f1e82"

最后我们将摘要字符串转换为大写

sign = signStrAfterMD5.toUpperCase()
sign = "51DABFE4B47E73D4A3B85FE29C4F1E82"

因此,x-stardots-sign 字段的最终值为 51DABFE4B47E73D4A3B85FE29C4F1E82

通用的HTTP响应主体

所有接口响应都保持统一的数据结构

  • code
    数据类型
    number
    是否必须
    是
    描述
    服务响应代码。200 表示成功。
  • message
    数据类型
    string
    是否必须
    是
    描述
    操作结果的消息提示。
  • requestId
    数据类型
    string
    是否必须
    是
    描述
    请求的唯一编号,可用于故障排除。
  • success
    数据类型
    boolean
    是否必须
    是
    描述
    业务操作是否成功。
  • ts
    数据类型
    number
    是否必须
    是
    描述
    服务器毫秒时间戳。
  • data
    数据类型
    any
    是否必须
    是
    描述
    业务数据字段,该字段可以为任意数据类型,具体数据类型请参考对应接口。

功能接口

注意所有接口都会有请求速率限制,所有接口共用一套速率限制规则。目前,StarDots 的速率限制为每分钟 300 次。

请求端点

https://api.stardots.io

空间列表

获取空间列表数据。

请求方法
GET
请求路径
/openapi/space/list
请求的内容类型
application/json
响应内容类型
application/json

请求参数

  • page
    数据类型
    number
    是否必须
    否
    描述
    页码,默认值为1。
  • pageSize
    数据类型
    number
    是否必须
    否
    描述
    每页显示条数,范围为1至100,默认值为20。

请求示例

/openapi/space/list?page=1&pageSize=50

响应字段

  • name
    数据类型
    string
    是否必须
    是
    描述
    空间名称
  • public
    数据类型
    boolean
    是否必须
    是
    描述
    空间的可访问性是否为公开。
  • createdAt
    数据类型
    number
    是否必须
    是
    描述
    空间创建时的系统时间戳(以秒为单位)。时区为 UTC+8。
  • fileCount
    数据类型
    number
    是否必须
    是
    描述
    空间内的文件数量。

响应示例

{
    "code": 200,
    "data": [
        {
            "createdAt": 1723789637,
            "fileCount": 2,
            "name": "star",
            "public": true
        }
    ],
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

创建空间

创建新的空间。

请求方法
PUT
请求路径
/openapi/space/create
请求内容类型
application/json
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • public
    数据类型
    boolean
    是否必须
    否
    描述
    指定空间是否可公开访问。默认值为false。

请求示例

{
    "public": false,
    "space": "stardots"
}

响应字段

无字段

响应示例

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

删除空间

删除一个已有的空间,注意必须保证该空间中没有文件,否则删除会失败。

请求方法
DELETE
请求路径
/openapi/space/delete
请求内容类型
application/json
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。

请求示例

{
    "space": "stardots"
}

响应字段

无字段

响应示例

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

空间可访问性

切换空间的可访问性。

请求方法
POST
请求路径
/openapi/space/accessibility/toggle
请求内容类型
application/json
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • public
    数据类型
    boolean
    是否必须
    否
    描述
    指定空间是否可公开访问。默认值为false。

请求示例

{
    "public": false,
    "space": "stardots"
}

响应字段

无字段

响应示例

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

空间内的文件列表

获取空间内文件列表,列表按照文件上传时间降序排列。

请求方法
GET
请求路径
/openapi/file/list
请求内容类型
application/json
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • page
    数据类型
    number
    是否必须
    否
    描述
    页码,默认值为1。
  • pageSize
    数据类型
    number
    是否必须
    否
    描述
    每页显示条数范围为1至100,默认值为20。

请求示例

{
    "space": "stardots",
    "page": 1,
    "pageSize": 20
}

响应字段

  • page
    数据类型
    number
    是否必须
    是
    描述
    页码,默认值为1。
  • pageSize
    数据类型
    number
    是否必须
    是
    描述
    每页显示条数范围为1至100,默认值为20。
  • totalCount
    数据类型
    number
    是否必须
    是
    描述
    总的文件数量。
  • list
    数据类型
    array<object>
    是否必须
    是
    描述
    文件列表数组。
  • list.name
    数据类型
    string
    是否必须
    是
    描述
    文件名称
  • list.byteSize
    数据类型
    number
    是否必须
    是
    描述
    文件的字节大小。
  • list.size
    数据类型
    string
    是否必须
    是
    描述
    文件大小,已格式化以便于阅读。
  • list.uploadedAt
    数据类型
    number
    是否必须
    是
    描述
    文件上传的时间戳(以秒为单位)。时区为 UTC+8。
  • list.url
    数据类型
    string
    是否必须
    是
    描述
    文件的访问地址,注意如果该空间的可访问性为private,则该字段值会携带访问票据,有效期为20秒。

响应示例

{
    "code": 0,
    "data": {
        "list": [
            {
                "byteSize": 3600000,
                "name": "star",
                "size": "35KB",
                "uploadedAt": 1723789637,
                "url": "https://....."
            }
        ],
        "page": 1,
        "pageSize": 10,
        "totalCount": 1
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

文件临时访问票据

获取文件的访问票,当空间的可访问性为私密时,需要携带访问票才能访问该空间下的文件,否则请求将被拒绝。

请求方法
POST
请求路径
/openapi/file/ticket
请求内容类型
application/json
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • filename
    数据类型
    string
    是否必须
    是
    描述
    文件的名称,不超过170个字符。

请求示例

{
    "filename": "1.jpg",
    "space": "stardots"
}

响应内容

  • ticket
    数据类型
    string
    是否必须
    是
    描述
    临时访问票据

响应示例

{
    "code": 200,
    "data": {
    "ticket": "a312.."
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

文件上传

将文件上传到空间。注意,此请求需要你以表单的形式发起请求。

请求方法
PUT
请求路径
/openapi/file/upload
请求内容类型
multipart/form-data
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • file
    数据类型
    binary
    是否必须
    是
    描述
    文件的二进制流。注意,文件名称不得超过170个字符。文件大小不能超过10MB。

响应字段

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • filename
    数据类型
    string
    是否必须
    是
    描述
    文件的名称。
  • url
    数据类型
    string
    是否必须
    是
    描述
    文件的访问链接,如果空间的可访问性为私密,则访问链接会携带访问票。

响应示例

{
    "code": 200,
    "data": {
        "filename": "1.png",
        "space": "space",
        "url": "https://i.stardots.io/space/1.png"
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

删除文件

删除空间内的文件。此接口支持批量操作。

请求方法
DELETE
请求路径
/openapi/file/delete
请求内容类型
application/json
响应内容类型
application/json

请求参数

  • space
    数据类型
    string
    是否必须
    是
    描述
    空间名称,只能为字母或数字组合,长度为4~15个字符。
  • filenameList
    数据类型
    array<string>
    是否必须
    是
    描述
    文件名称字符串数组。

请求示例

{
    "filenameList": ["1.jpg", "2.jpg"],
    "space": "stardots"
}

响应字段

无字段

响应示例

{
    "code": 0,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

服务器响应代码

服务器响应代码是服务器返回给客户端的响应代码,用于表示服务器处理请求的结果。

  • 200
    描述
    成功
  • 504
    描述
    请求超时
  • 999999
    描述
    服务器内部错误
  • 100000
    描述
    请求参数错误
  • 100001
    描述
    访问凭证失效
  • 100002
    描述
    人机验证不通过
  • 100003
    描述
    验证码不正确
  • 100004
    描述
    账号不存在
  • 100005
    描述
    账号密码不匹配
  • 100006
    描述
    订阅计划不存在
  • 100007
    描述
    短信/邮件发送过于频繁
  • 100008
    描述
    短信/邮件发送次数超出限制
  • 100009
    描述
    空间/存储桶不存在
  • 100010
    描述
    空间/存储桶已存在
  • 100011
    描述
    空间/存储桶不为空
  • 100012
    描述
    操作过于频繁
  • 100013
    描述
    空间/存储桶数量配额已达到数量上限
  • 100014
    描述
    文件数量配额已达到数量上限
  • 100015
    描述
    流量传输配额已耗尽
  • 100016
    描述
    订阅计划不匹配
  • 100017
    描述
    空间/存储桶文件访问受限
  • 100018
    描述
    文件超出大小限制
  • 100019
    描述
    文件格式不受支持
  • 100020
    描述
    Referer不允许
  • 100021
    描述
    功能仅对Pro或Premium用户开放
  • 100022
    描述
    功能仅对Premium用户开放
  • 100023
    描述
    证书内容无效
  • 100024
    描述
    证书和私钥不匹配
  • 100025
    描述
    无效的图像MIME类型
  • 100026
    描述
    文件访问链接已失效
  • 100027
    描述
    API调用次数已达到上限
  • 100028
    描述
    批量操作仅对付费用户开放
  • 100029
    描述
    图像链接无效
  • 100030
    描述
    账号涉嫌违规,已被禁止登录

SDK

StarDots 为各种编程语言提供了 SDK,以帮助您快速集成我们的 API。您可以在以下链接中找到 SDK:

如果你遇到任何问题,请联系我们