Перейти к содержанию
Sursa для разработчиков

POST/v1/uploads/{upload_id}/complete

Завершить загрузку

complete_upload

Когда все части получены, Sursa собирает файл, сравнивает SHA-256 всего файла с sha256 из тела и выполняет те же проверки, что и при загрузке одним запросом: формат по сигнатуре содержимого и антивирусную проверку. Результат — ready или rejected с reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Каждый отказ проверки формата или антивируса записывается в журнал аудита как file.rejected.

Ответ 200 означает, что результат готов; 202 — файл ещё проверяется (processing), а результат даёт GET /v1/uploads/{upload_id}. Если статус вернулся в pending (перезапуск экземпляра API прервал проверку), отправьте complete ещё раз. Повтор complete после результата возвращает тот же результат. Недостающие части возвращают 409 uploads.incomplete (details.missing). sha256, отличный от объявленного при создании, или parts[].etag, отличный от полученной части, возвращает 422 uploads.checksum_mismatch. Готовая, но не использованная загрузка живёт 24 часа. Добавлено в 1.62.0.

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

Передайте ключ API в заголовке Authorization: Authorization: Bearer <ключ>.

Параметры пути

  • upload_idstringобязательно

    ID загрузки (upl_ и 32 шестнадцатеричных символа).

    length ≤ 64

Параметры заголовков

  • Idempotency-Keystring

    Ключ для безопасного повтора записи: от 1 до 255 печатных символов ASCII; рекомендуется UUID v4 на каждую логическую операцию. Повтор с тем же ключом в течение 24 часов не выполняет операцию заново: он возвращает сохранённый ответ (статус, заголовки и тело) с заголовком Idempotency-Replayed: true. Тот же ключ с другим методом, путём, Content-Type или телом — ответ 409 api.idempotency_mismatch; пока первый запрос ещё выполняется — 409 api.idempotency_in_progress с Retry-After: 1. После ответа 5xx или 429 ключ освобождается, и повтор выполняет операцию заново. Ключ действует в пределах организации и вызывающей стороны (ключ API, пользователь или ключ своего источника).

    length ≥ 1, length ≤ 255

Тело запроса

application/json

Объект: UploadComplete

  • sha256stringобязательно

    SHA-256 всего файла.

  • partsarray of UploadPartRef

    Необязательная проверка частей: ETag каждой части в том виде, в каком его вернул PUT …/parts/{n}.

    items ≤ 1000

Ответы

200Результат готов: `ready` или `rejected`.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

  • Idempotency-Replayed

    true — ответ воспроизведён из сохранённого для этого Idempotency-Key: операция повторно не выполнялась.

application/json

Объект: Upload

  • idstringобязательно

    ID загрузки (upl_ и 32 шестнадцатеричных символа).

  • purposeUploadPurposeобязательно
  • filenamestringобязательно

    Имя файла (без папок).

  • content_typestringобязательно

    Объявленный тип содержимого; пусто, если не объявлен.

  • sizeinteger (int64)обязательно

    Размер файла в байтах.

  • sha256string | nullобязательно

    SHA-256 файла, объявленная при создании или на шаге complete; null, если ещё неизвестна.

  • statusUploadStatusобязательно
  • part_sizeinteger (int64)обязательно

    Размер каждой части, кроме последней (от 5 до 100 МиБ).

  • part_countintegerобязательно

    Число частей.

    ≥ 1, ≤ 1000

  • parts_receivedintegerобязательно

    Число полученных частей.

    ≥ 0

  • partsarray of UploadPartобязательно

    Полученные части по номерам (пусто в ответе POST /v1/uploads).

  • reject_reasonstring | nullобязательно

    Причина отказа (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Перечисление может расширяться; null, если отказа нет.

  • reject_detailsobject | nullобязательно

    Подробности отказа (расширение, объявленный и определённый формат, контрольные суммы); null, если отказа нет.

  • created_atstring (date-time)обязательно

    Когда создана загрузка.

  • expires_atstring (date-time)обязательно

    Крайний срок, чтобы завершить загрузку и, когда она готова, использовать её.

  • completed_atstring (date-time) | nullобязательно

    Когда закончилась проверка (ready или rejected).

  • consumed_atstring (date-time) | nullобязательно

    Когда загрузка использована (карточкой, архивом или импортом).

202Файл ещё проверяется (`processing`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

  • Idempotency-Replayed

    true — ответ воспроизведён из сохранённого для этого Idempotency-Key: операция повторно не выполнялась.

application/json

Объект: Upload

  • idstringобязательно

    ID загрузки (upl_ и 32 шестнадцатеричных символа).

  • purposeUploadPurposeобязательно
  • filenamestringобязательно

    Имя файла (без папок).

  • content_typestringобязательно

    Объявленный тип содержимого; пусто, если не объявлен.

  • sizeinteger (int64)обязательно

    Размер файла в байтах.

  • sha256string | nullобязательно

    SHA-256 файла, объявленная при создании или на шаге complete; null, если ещё неизвестна.

  • statusUploadStatusобязательно
  • part_sizeinteger (int64)обязательно

    Размер каждой части, кроме последней (от 5 до 100 МиБ).

  • part_countintegerобязательно

    Число частей.

    ≥ 1, ≤ 1000

  • parts_receivedintegerобязательно

    Число полученных частей.

    ≥ 0

  • partsarray of UploadPartобязательно

    Полученные части по номерам (пусто в ответе POST /v1/uploads).

  • reject_reasonstring | nullобязательно

    Причина отказа (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. Перечисление может расширяться; null, если отказа нет.

  • reject_detailsobject | nullобязательно

    Подробности отказа (расширение, объявленный и определённый формат, контрольные суммы); null, если отказа нет.

  • created_atstring (date-time)обязательно

    Когда создана загрузка.

  • expires_atstring (date-time)обязательно

    Крайний срок, чтобы завершить загрузку и, когда она готова, использовать её.

  • completed_atstring (date-time) | nullобязательно

    Когда закончилась проверка (ready или rejected).

  • consumed_atstring (date-time) | nullобязательно

    Когда загрузка использована (карточкой, архивом или импортом).

401Учётные данные не переданы (нет ни cookie сессии, ни ключа API) или ключ не найден.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

403Действие запрещено: недостаточно прав роли, нет доступа к коллекции или карточке, запрос выполняется в режиме «Смотреть как» либо организация приостановлена или удалена (`detail` — объект с `code: org_suspended | org_deleted`).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

404Объект не существует или вам недоступен. API не подтверждает существование объекта с ограниченным доступом.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

409Состояние объекта не позволяет выполнить действие: например, дубль, идёт индексация или задание уже обработано.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

410Объект существовал, но больше недоступен: ссылка использована или истекла либо файл удалён по окончании срока хранения.

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

422Ошибка проверки: тело или параметры не соответствуют схеме (`detail` — список ошибок проверки) либо значение параметра вне допустимого диапазона (`detail` — сообщение).

Заголовки ответа

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

429Слишком много запросов (`api.rate_limited`), квота организации на минуту, день или месяц исчерпана (`api.quota_exceeded`; в `error.details` — `quota`, `limit` и `reset_at`), достигнут лимит организации или сервис ответов занят (`answers.engine_busy`). Подождите время, указанное в заголовке `Retry-After`.

Заголовки ответа

  • Retry-After

    Сколько секунд подождать перед повтором запроса.

  • RateLimit-Policy

    Действующие лимиты в формате черновика IETF draft-ietf-httpapi-ratelimit-headers: элементы через запятую "<name>";q=<quota>;w=<window in seconds>. key — частота запросов ключа API (квота — допустимый всплеск, окно — время до полного восстановления; для сессии это user, без учётных данных — ip); minute, day и month — квоты организации на календарную минуту, день и месяц по UTC.

  • RateLimit

    Сколько осталось по каждому лимиту из RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Лимит самой строгой записи в RateLimit-Policy (той, где осталось меньше всего запросов).

  • X-RateLimit-Remaining

    Сколько запросов осталось в пределах самого строгого лимита.

  • X-RateLimit-Reset

    Через сколько секунд сбросится самый строгий лимит.

application/json

Объект: Error

Коды ошибок

Коды, которые эта операция может вернуть в error.code, помимо общих кодов любого запроса.

Безопасные повторы

Передавайте заголовок Idempotency-Key (например, UUID) с каждым POST и PATCH. Повтор с тем же ключом в течение 24 часов возвращает сохранённый ответ, а не выполняет запрос снова.

Лимиты частоты

В ответах есть заголовки RateLimit и RateLimit-Policy, а также прежние X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. В ответе 429 есть Retry-After в секундах: подождите и повторите запрос.

← uploads · Справочник API