Перейти до вмісту
Sursa Developers

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Дію не дозволено: роль не має достатніх прав, немає доступу до колекції чи картки, запит виконується в режимі «View as» або організацію призупинено чи видалено (`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