Отметим: когда проекту требуется файловый бэкенд — медиатека, загрузки пользователей, бэкапы — Dropbox API часто оказывается проще и надёжнее, чем собственный сервер хранения. Типичные проблемы: медленные FTP-передачи, потеря данных при сбое, отсутствие версионирования. Наша команда выполнила уже более 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 раза быстрее раздаёт файлы при пиковых нагрузках — подтверждено нашими нагрузочными тестами. Экономия на серверном хранении достигает 40 000 рублей в месяц при объёме данных от 1 ТБ.
Как настроить 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 на сервер.
Прямая загрузка
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 — это удобно для синхронизации медиатеки или мгновенной обработки новых файлов. Каждое уведомление содержит подпись 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 месяца бесплатной поддержки после запуска
Процесс работы
Наша команда сертифицированных инженеров с 7-летним опытом работы с Dropbox API выполняет интеграцию по плану:
- Анализ требований — определяем, какие файлы и как часто загружаются, объём данных, необходимость webhooks.
- Настройка OAuth2 — регистрация приложения, реализация flow, безопасное хранение refresh token с использованием шифрования AES-256.
- Реализация загрузки/скачивания — прямые и chunked upload, генерация shared links с контролем срока.
- Настройка webhooks — endpoint с проверкой подписи, обработка событий
list_folder, очереди для фоновой синхронизации. - Тестирование под нагрузкой — имитируем 100+ параллельных загрузок, проверяем лимиты API.
- Документация и обучение — описание API, инструкция для администратора, доступ к исходному коду на Git.
Сроки: от 3 до 10 рабочих дней в зависимости от количества эндпоинтов и необходимости webhooks. Стоимость интеграции — от 45 000 до 85 000 рублей. Свяжитесь с нами для оценки вашего проекта — бесплатно проконсультируем и предложим оптимальное решение. Закажите интеграцию сегодня, чтобы получить стабильное файловое хранилище с гарантией.
Типичные ошибки при интеграции 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 часов |