StarDots.io Logo

StarDots

К началу документации

Открытое API

В этой главе рассказывается, как интегрировать открытые API. Следующая информация предназначена для разработчиков, и мы предполагаем, что вы обладаете базовыми знаниями программирования.

Вы ИИ-агент? Откройте документацию в Markdown
На этой странице

Аутентификация

StarDots выполняет аутентификацию, считывая поле заголовков в HTTP-запросе, отправленном клиентом, и проверяя соответствующие поля. Таким образом, все запросы к открытому API должны содержать информацию об этих полях аутентификации. Обратите внимание, что эти поля чувствительны к регистру, и все они должны быть написаны в нижнем регистре.

  • x-stardots-timestamp
    Описание
    Текущая метка времени в секундах. Разница с сервером StarDots не должна превышать 60 секунд. Примечание: Часовой пояс StarDots — Азия/Сингапур, что соответствует UTC+8.
  • x-stardots-nonce
    Описание
    Случайная строка длиной от 4 до 20 символов, которая может содержать только заглавные и строчные буквы, а также цифры. Обратите внимание, что это значение должно быть уникальным в течение 60 секунд.
  • x-stardots-key
    Описание
    Ключевая информация, выданная StarDots.
  • 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
Ключ и секрет выдаются 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
    Обязательно
    Да
    Описание
    Является ли доступ к пространству закрытым (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.

Пример запроса

{
    "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": "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
    Обязательно
    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 секунд.

Пример ответа

{
    "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
    Описание
    Название файла.

Пример запроса

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

Поля ответа

  • 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 символов.
  • 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
    Описание
    Массив имен файлов.

Пример запроса

{
    "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 по следующим ссылкам:

Если у вас возникнут какие-либо проблемы, пожалуйста, свяжитесь с нами