Аутентификация
StarDots выполняет аутентификацию, считывая поле заголовков в HTTP-запросе, отправленном клиентом, и проверяя соответствующие поля. Таким образом, все запросы к открытому API должны содержать информацию об этих полях аутентификации. Обратите внимание, что эти поля чувствительны к регистру, и все они должны быть написаны в нижнем регистре.
| Имя | Описание |
|---|---|
x-stardots-timestamp | Текущая метка времени в секундах. Разница с сервером StarDots не должна превышать 60 секунд. Примечание: Часовой пояс StarDots — Азия/Сингапур, что соответствует UTC+8. |
x-stardots-nonce | Случайная строка длиной от 4 до 20 символов, которая может содержать только заглавные и строчные буквы, а также цифры. Обратите внимание, что это значение должно быть уникальным в течение 60 секунд. |
x-stardots-key | Ключевая информация, выданная StarDots. |
x-stardots-sign | Поле подписи — это строка, сгенерированная путем объединения вышеуказанных полей в соответствии с определенным алгоритмом подписи. Конкретный алгоритм подписи будет представлен далее. |
x-stardots-timestamp- Описание
- Текущая метка времени в секундах. Разница с сервером StarDots не должна превышать 60 секунд. Примечание: Часовой пояс StarDots — Азия/Сингапур, что соответствует UTC+8.
x-stardots-nonce- Описание
- Случайная строка длиной от 4 до 20 символов, которая может содержать только заглавные и строчные буквы, а также цифры. Обратите внимание, что это значение должно быть уникальным в течение 60 секунд.
x-stardots-key- Описание
- Ключевая информация, выданная StarDots.
x-stardots-sign- Описание
- Поле подписи — это строка, сгенерированная путем объединения вышеуказанных полей в соответствии с определенным алгоритмом подписи. Конкретный алгоритм подписи будет представлен далее.
Алгоритм подписи
Мы предполагаем следующие значения полей
key2dcded8e-f231-4d0a-8498-d10ef0639eb3secretEy1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNpx-stardots-timestamp1728958751x-stardots-noncefQvDmMLnKEx-stardots-key2dcded8e-f231-4d0a-8498-d10ef0639eb3
Затем мы объединяем значения указанных полей
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 | Да | Поле бизнес-данных. Этот параметр может быть любого типа данных. Для конкретных типов данных обратитесь к соответствующему интерфейсу. |
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. |
page- Тип данных
number- Обязательно
- Нет
- Описание
- Номер страницы, значение по умолчанию — 1.
pageSize- Тип данных
number- Обязательно
- Нет
- Описание
- Количество записей на странице: от 1 до 100, значение по умолчанию — 20.
Пример запроса
/openapi/space/list?page=1&pageSize=50Поля ответа
| Имя | Тип данных | Обязательно | Описание |
|---|---|---|---|
name | string | Да | Название пространства. |
public | boolean | Да | Является ли доступ к пространству закрытым (false). |
createdAt | number | Да | Системная метка времени в секундах при создании пространства. Часовой пояс — UTC+8. |
fileCount | number | Да | Количество файлов в данном пространстве. |
name- Тип данных
string- Обязательно
- Да
- Описание
- Название пространства.
public- Тип данных
boolean- Обязательно
- Да
- Описание
- Является ли доступ к пространству закрытым (false).
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. |
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 | Yes | Название пространства. Это может быть только комбинация букв или цифр, и длина от 4 до 15 символов. |
space- Тип данных
string- Обязательно
- Yes
- Описание
- Название пространства. Это может быть только комбинация букв или цифр, и длина от 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. |
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 | Yes | Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов. |
page | number | No | Номер страницы, значение по умолчанию - 1. |
pageSize | number | No | Количество записей на странице от 1 до 100, значение по умолчанию - 20. |
space- Тип данных
string- Обязательно
- Yes
- Описание
- Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов.
page- Тип данных
number- Обязательно
- No
- Описание
- Номер страницы, значение по умолчанию - 1.
pageSize- Тип данных
number- Обязательно
- No
- Описание
- Количество записей на странице от 1 до 100, значение по умолчанию - 20.
Пример запроса
{
"space": "stardots",
"page": 1,
"pageSize": 20,
}Поля ответа
| Имя | Тип данных | Обязательно | Описание |
|---|---|---|---|
page | number | Yes | Номер страницы, значение по умолчанию - 1. |
pageSize | number | Yes | Количество записей на странице от 1 до 100, значение по умолчанию - 20. |
totalCount | number | Yes | Общее количество записей. |
list | array<object> | Yes | Массив списка файлов. |
list.name | string | Yes | Название файла. |
list.byteSize | number | Yes | Размер файла в байтах. |
list.size | string | Yes | Размер файла, отформатированный для удобства чтения. |
list.uploadedAt | number | Yes | Метка времени загрузки файла в секундах. Часовой пояс - UTC+8. |
list.url | string | Yes | Адрес для доступа к файлу. Обратите внимание, что если доступность пространства приватная, это поле будет содержать билет доступа, который действителен 20 секунд. |
page- Тип данных
number- Обязательно
- Yes
- Описание
- Номер страницы, значение по умолчанию - 1.
pageSize- Тип данных
number- Обязательно
- Yes
- Описание
- Количество записей на странице от 1 до 100, значение по умолчанию - 20.
totalCount- Тип данных
number- Обязательно
- Yes
- Описание
- Общее количество записей.
list- Тип данных
array<object>- Обязательно
- Yes
- Описание
- Массив списка файлов.
list.name- Тип данных
string- Обязательно
- Yes
- Описание
- Название файла.
list.byteSize- Тип данных
number- Обязательно
- Yes
- Описание
- Размер файла в байтах.
list.size- Тип данных
string- Обязательно
- Yes
- Описание
- Размер файла, отформатированный для удобства чтения.
list.uploadedAt- Тип данных
number- Обязательно
- Yes
- Описание
- Метка времени загрузки файла в секундах. Часовой пояс - UTC+8.
list.url- Тип данных
string- Обязательно
- Yes
- Описание
- Адрес для доступа к файлу. Обратите внимание, что если доступность пространства приватная, это поле будет содержать билет доступа, который действителен 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 | Yes | Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов. |
filename | string | Yes | Название файла. |
space- Тип данных
string- Обязательно
- Yes
- Описание
- Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов.
filename- Тип данных
string- Обязательно
- Yes
- Описание
- Название файла.
Пример запроса
{
"filename": "1.jpg",
"space": "stardots"
}Поля ответа
| Имя | Тип данных | Обязательно | Описание |
|---|---|---|---|
ticket | string | Yes | Билет доступа. |
ticket- Тип данных
string- Обязательно
- Yes
- Описание
- Билет доступа.
Пример ответа
{
"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 | Yes | Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов. |
file | binary | Yes | Бинарный поток файла. Обратите внимание, что имя файла не должно превышать 170 символов. Размер файла не может превышать 10 МБ. |
space- Тип данных
string- Обязательно
- Yes
- Описание
- Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов.
file- Тип данных
binary- Обязательно
- Yes
- Описание
- Бинарный поток файла. Обратите внимание, что имя файла не должно превышать 170 символов. Размер файла не может превышать 10 МБ.
Поля ответа
| Имя | Тип данных | Обязательно | Описание |
|---|---|---|---|
space | string | Yes | Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов. |
filename | string | Yes | Название файла. |
url | string | Yes | Ссылка на файл. Если доступность пространства является приватной, ссылка на файл будет содержать билет доступа. |
space- Тип данных
string- Обязательно
- Yes
- Описание
- Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов.
filename- Тип данных
string- Обязательно
- Yes
- Описание
- Название файла.
url- Тип данных
string- Обязательно
- Yes
- Описание
- Ссылка на файл. Если доступность пространства является приватной, ссылка на файл будет содержать билет доступа.
Пример ответа
{
"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 | Yes | Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов. |
filenameList | array<string> | Yes | Массив имен файлов. |
space- Тип данных
string- Обязательно
- Yes
- Описание
- Название пространства. Оно может содержать только буквы или цифры, и длина составляет от 4 до 15 символов.
filenameList- Тип данных
array<string>- Обязательно
- Yes
- Описание
- Массив имен файлов.
Пример запроса
{
"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 | Аккаунт подозревается в нарушении, и его доступ запрещен |
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 по следующим ссылкам:
GoJavaC#PythonTypescriptC++RustPHPRubyVSwiftKotlinDart