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

POST/v1/uploads

Розпочати завантаження частинами

create_upload

Відкриває сесію завантаження великого файлу (до ліміту інсталяції для завантажень частинами, типово 5 ГБ): ім’я, тип вмісту, розмір і purpose — мета, що вказує, хто використає завантаження: card_file (POST /v1/cards), archive (POST /v1/cards/archive) або import_attachment (вкладення документа власного джерела). Відповідь містить id (upl_, а за ним 32 шістнадцяткові символи), розмір частини part_size і кількість частин part_count. Кожна частина, крім останньої, має рівно part_size байтів (від 5 до 100 МіБ), а остання — решту. Незавершене завантаження діє 24 години (expires_at).

Розширення імені файлу поза форматами цієї мети повертає 415 uploads.unsupported_format (вкладення імпорту приймає будь-яке розширення). Файл, більший за ліміт інсталяції або за загальне сховище організації на її тарифі, повертає 413 uploads.too_large. Якщо з урахуванням незавершених завантажень організації сховища лишилося недостатньо, повертається 402 limits.storage.

Частини проходять через Sursa (PUT /v1/uploads/{upload_id}/parts/{n}) і шифруються ключем організації у файловому сховищі; прямих посилань на сховище немає. Бачити й використовувати завантаження може лише той ключ API або користувач, що його створив. Додано в 1.62.0.

Автентифікація

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

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

  • 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

Об’єкт: UploadCreate

  • filenamestringобов’язково

    Ім’я файлу з розширенням; розширення визначає формат.

    length ≥ 1, length ≤ 255

  • content_typestring

    Заявлений тип вмісту (MIME); його звіряють із сигнатурою файлу.

    length ≤ 255

  • sizeinteger (int64)обов’язково

    Розмір файлу в байтах.

    ≥ 1

  • purposeUploadPurposeобов’язково
  • sha256string

    SHA-256 файлу, якщо він відомий заздалегідь; complete звіряє з ним контрольну суму файлу.

Відповіді

201Сесію завантаження створено.

Заголовки відповіді

  • 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

402Організація досягла ліміту тарифу (картки, сховище або користувачі). `error.details` містить `kind`, `limit` і `used`.

Заголовки відповіді

  • 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

413Тіло запиту перевищує допустимий розмір.

Заголовки відповіді

  • 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

415Формат файлу не підтримується.

Заголовки відповіді

  • 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