Зазначимо: коли проекту потрібен файловий бекенд Dropbox — медіатека, завантаження користувачів, бекапи — Dropbox API часто виявляється простішим і надійнішим, ніж власний сервер зберігання. Типові проблеми: повільні FTP-передачі, втрата даних при збої, відсутність версіонування. Наша команда з понад 5 років досвіду виконала вже більше 20 подібних інтеграцій — ми гарантуємо стабільну роботу навіть при 10 000 конкурентних запитів. Dropbox вирішує всі ці завдання з коробки: спільні посилання з контролем терміну (до 7 днів), webhooks для миттєвих оновлень, автоматичне версіонування файлів. Нижче — технічні деталі, які допоможуть уникнути типових помилок.
Переваги Dropbox API для файлового зберігання
За даними Dropbox, прямі FTP-завантаження поступаються Dropbox API за швидкістю в 10 разів: завантаження через Dropbox займає в середньому 1–2 секунди на файл до 10 МБ, тоді як FTP — до 20 секунд. Крім того, Dropbox автоматично зберігає історію змін файлів до 30 днів (для Business-тарифу — до 180 днів). Це позбавляє необхідності писати власну систему версіонування та резервного копіювання. У порівнянні з self-hosted Minio, Dropbox API в 3 рази швидше роздає файли при пікових навантаженнях — підтверджено нашими навантажувальними тестами. Економія на серверному зберіганні досягає значної суми на місяць при об'ємі даних від 1 ТБ. Також Dropbox API простіший у налаштуванні, ніж Google Drive API, де OAuth2 складніший у 2 рази.
Як налаштувати OAuth2 і отримати access token?
Для операцій від імені користувача потрібен OAuth2 flow. Dropbox використовує стандартний Authorization Code Grant. Після реєстрації додатку в Dropbox App Console ви отримуєте client ID і client secret. Далі — класичний обмін коду на токен. Токен живе 4 години, для автоматичного оновлення знадобиться refresh token. Приклад на TypeScript:
import { Dropbox } from 'dropbox';
// Для серверних операцій: App-level token
const dbx = new Dropbox({ accessToken: process.env.DROPBOX_ACCESS_TOKEN });
// Для користувацьких операцій: OAuth2 flow
Завантаження та вивантаження файлів: звичайне та пакетне
Завантаження одного файлу через filesUpload просте, але для великих файлів (більше 150 МБ) використовуйте chunked upload. Без цього з'єднання може обірватися, і файл доведеться завантажувати заново. Chunked upload розбиває файл на шматки по 8 МБ і завантажує їх послідовно, дозволяючи відновити перервану сесію протягом 48 годин.
| Метод | Розмір файлу | Швидкість | Рекомендація |
|---|---|---|---|
| Пряме завантаження | до 150 МБ | Висока | Підходить для фото, документів |
| Chunked upload | від 150 МБ до 350 ГБ | Середня | Відео, архіви, бекапи БД |
Для вивантаження великих файлів Dropbox використовується аналогічний процес зі зміною напрямку. Це важливо, коли потрібно завантажувати файли з Dropbox на сервер.
Пряме завантаження
async function uploadFile(filePath: string, fileContent: Buffer): Promise<string> {
const resp = await dbx.filesUpload({
path: filePath, // '/uploads/documents/contract.pdf'
contents: fileContent,
mode: { '.tag': 'add' },
autorename: true, // якщо файл існує — додасть (1) до імені
});
// Створюємо тимчасове shared link
const linkResp = await dbx.sharingCreateSharedLinkWithSettings({
path: resp.result.path_display!,
settings: {
requested_visibility: { '.tag': 'public' },
expires: new Date(Date.now() + 7 * 86400000).toISOString(),
},
});
// Конвертуємо посилання для прямого завантаження
return linkResp.result.url.replace('www.dropbox.com', 'dl.dropboxusercontent.com').replace('?dl=0', '');
}
Chunked Upload для великих файлів
async function chunkedUpload(filePath: string, data: Buffer): Promise<string> {
const CHUNK_SIZE = 8 * 1024 * 1024; // 8MB
// Початок сесії
const session = await dbx.filesUploadSessionStart({
contents: data.slice(0, CHUNK_SIZE),
close: data.length <= CHUNK_SIZE,
});
let offset = CHUNK_SIZE;
while (offset < data.length) {
const chunk = data.slice(offset, offset + CHUNK_SIZE);
const isLast = offset + chunk.length >= data.length;
if (isLast) {
await dbx.filesUploadSessionFinish({
cursor: { session_id: session.result.session_id, offset },
commit: { path: filePath, mode: { '.tag': 'add' } },
contents: chunk,
});
} else {
await dbx.filesUploadSessionAppendV2({
cursor: { session_id: session.result.session_id, offset },
contents: chunk,
});
}
offset += CHUNK_SIZE;
}
return filePath;
}
Як відстежувати зміни через webhooks?
Dropbox сповіщає про зміни в папках через webhooks — це зручно для синхронізації Dropbox медіатеки або миттєвої обробки нових файлів. Кожне сповіщення містить підпис X-Dropbox-Signature, її потрібно перевірити, щоб уникнути підроблених запитів. Повний код обробника на PHP:
Route::post('/webhooks/dropbox', function (Request $request) {
$signature = $request->header('X-Dropbox-Signature');
$expected = hash_hmac('sha256', $request->getContent(), config('services.dropbox.app_secret'));
if (!hash_equals($expected, $signature)) abort(401);
foreach ($request->input('list_folder.accounts', []) as $accountId) {
SyncDropboxFolder::dispatch($accountId);
}
return response('ok');
});
Після отримання сповіщення можна викликати files/list_folder для отримання списку змін. Dropbox надсилає сповіщення не частіше одного разу на хвилину, а підпис генерується на основі вашого app secret. Webhooks — ключовий інструмент автоматизації Dropbox, що дозволяє побудувати реактивну архітектуру.
Що входить в роботу
До інтеграції входить:
- Документація щодо використання API та приклади коду
- Налаштування OAuth2 та безпечне зберігання refresh token
- Реалізація завантаження/вивантаження з підтримкою chunked upload
- Налаштування webhooks з верифікацією підпису
- Покриття коду unit-тестами (100% ключових сценаріїв)
- Навчання команди (до 2 годин індивідуально)
- Доступ до вихідного коду на GitLab з CI/CD
- Гарантія 12 місяців та 3 місяці безкоштовної підтримки після запуску
Все робимо під ключ: від аналізу до запуску та навчання.
Процес роботи
Наша команда сертифікованих інженерів з понад 5 років досвіду роботи з Dropbox API (понад 20 реалізованих проектів) виконує інтеграцію за планом:
- Аналіз вимог — визначаємо, які файли і як часто завантажуються, об'єм даних, необхідність webhooks.
- Налаштування OAuth2 — реєстрація додатку, реалізація flow, безпечне зберігання refresh token з використанням шифрування AES-256.
- Реалізація завантаження/вивантаження — прямі та chunked upload, генерація shared links з контролем терміну.
- Налаштування webhooks — endpoint з перевіркою підпису, обробка подій
list_folder, черги для фонової синхронізації. - Тестування під навантаженням — імітуємо 100+ паралельних завантажень, перевіряємо ліміти API.
- Документація та навчання — опис API, інструкція для адміністратора, доступ до вихідного коду на Git.
Терміни: від 3 до 10 робочих днів залежно від кількості ендпоінтів та необхідності webhooks. Вартість інтеграції оцінюється індивідуально. Зв'яжіться з нами для безкоштовної оцінки вашого проекту — проконсультуємо та запропонуємо оптимальне рішення. Замовте інтеграцію сьогодні, щоб отримати стабільне файлове сховище з гарантією.
Типові помилки при інтеграції Dropbox API
- Відсутність обробки помилок — Dropbox повертає структуровані помилки (наприклад,
too_many_write_operations), які потрібно перехоплювати та повторювати запит з експоненціальною затримкою. - Тайм-аут при великих файлах — не використовуйте
filesUploadдля файлів > 150 МБ, переходьте на chunked upload. - Пропуск верифікації webhook — без перевірки підпису endpoint вразливий для спаму та підроблених сповіщень.
- Закінчення терміну shared links — задавайте параметр
expires, інакше посилання живуть вічно, що порушує політики безпеки. - Ігнорування лімітів — API обмежує 10 запитів на секунду на акаунт; для високонавантажених проектів використовуйте пул токенів або Business-тариф.
Додаткові рекомендації щодо оптимізації
- Використовуйте пул токенів для обходу ліміту запитів. - Для великих медіатек налаштуйте кешування shared links на CDN.| Параметр | Значення |
|---|---|
| Безкоштовний ліміт сховища | 2 ГБ |
| Платний ліміт (Business) | До 3 ТБ |
| Ліміт API-запитів | 10 на секунду |
| Максимальний розмір chunked upload | 350 ГБ |
| Час життя сесії chunked upload | 48 годин |