Этот пост в блоге был обновлен с учетом последних изменений в продуктах Cloudinary.
Чтобы загрузить видео в Cloudinary, используйте Upload Widget для готового интерфейса браузера, Upload API для загрузок, управляемых приложением, консоль Media Library для ручной загрузки или виджет Media Library внутри редакторского приложения. Программные загрузки должны содержать параметр resource_type: "video"; файлы размером более 100 МБ требуют использования метода пошаговой загрузки (chunked upload) в пределах лимитов вашего аккаунта. Руководство по загрузке Cloudinary.
Правильный выбор зависит от того, кто именно выполняет загрузку. Клиенту, отправляющему видео о товаре, нужен иной рабочий процесс, чем редактору, выбирающему утвержденный ролик. В этом руководстве сравниваются данные подходы, приводятся примеры на JavaScript и Node.js, а также объясняется, как проверить, готово ли сохраненное видео к использованию по назначению.
Используйте Upload Widget для выбора файлов публичными пользователями, а виджет Media Library — для выбора контента авторизованными редакторами. Применяйте API, когда вам требуется полный контроль над интерфейсом или серверным процессом.
Первые два метода подходят для пользовательского контента. Последние два предназначены для командных рабочих процессов. Данное сравнение объединяет клиентские варианты загрузки Cloudinary, руководство разработчика по Media Library и документацию по виджету Media Library.
Вам понадобятся программная среда (product environment) Cloudinary и видео, на загрузку которого у вас есть разрешение. Для примеров на Node.js используйте поддерживаемую версию Node.js и актуальный пакет cloudinary.
Найдите свое имя облака (cloud name), ключ API и секретный ключ API в разделе Настройки > Ключи API (Settings > API Keys). Имя облака идентифицирует программную среду. Храните секретный ключ API только на сервере — никогда не размещайте его в HTML, браузере в JavaScript, переменных окружения, доступных клиенту, или в системе контроля версий. Cloudinary рекомендует обновить SDK для Node.js до последней версии для повышения безопасности.
Перед тестированием проверьте лимиты загрузки в среде, доступное хранилище, а также использование трансформаций и доставки. Примеры не требуют надстроек ИИ или бета-функций, но они расходуют ресурсы аккаунта. Виджет Media Library имеет особые требования к числу пользовательских мест; клиентам корпоративного тарифа (Enterprise) также необходим план Assets. Сравнение планов, требования к виджетам.
Upload Widget предоставляет функции выбора файлов, отображения прогресса и событий загрузки, избавляя ваше приложение от необходимости передавать байты видео через себя. Его можно встроить с помощью JavaScript независимо от фронтенд-фреймворка. Руководство по Upload Widget.
Для первичного тестирования создайте несогласованный пресет загрузки (unsigned upload preset) в разделе Настройки > Загрузка > Пресеты загрузки (Settings > Upload > Upload Presets). Назовите его video_demo_unsigned, выберите Unsigned и ограничьте разрешенные форматы (allowed_formats) значениями mp4, mov и webm. Ограничивайте пресет только тем поведением, которое вы намерены предоставить. Имя несогласованного пресета — это публичная конфигурация, а не пароль. Конфигурация пресетов загрузки.
Добавьте кнопку, сообщение о статусе и текущий загрузчик виджета:
Поместите этот код JavaScript после разметки, заменив заполнитель имени облака (cloud-name):
My Files открывает выбор локальных файлов. На этом скриншоте показано состояние пустого выбора до начала загрузки.
Значение в 50 МБ является лимитом браузера для данного примера, а не ограничением тарифного плана Cloudinary. Параметры maxVideoFileSize и clientAllowedFormats применяются для проверки локальных файлов. Удаленный URL-адрес не подпадает под эти локальные проверки, и вызывающая сторона может обойти вашу страницу. Пресеты загрузки Cloudinary не предоставляют ограничение размера в байтах на один пресет. Обеспечивайте соблюдение политики приложения с помощью надежной валидации, элементов управления аккаунтом и проверки на стороне сервера. Клиентские параметры виджета, соображения безопасности пресетов.
Web Address принимает доступный URL-адрес файла. Заполнитель не является отправленным URL-адресом.
Для стартового проекта см. пример виджета загрузки JavaScript Cloudinary на GitHub. Конфигурируйте источники явно, а не предполагайте, что каждый внешний сервис доступен в любой интеграции.
Подписанная прямая загрузка (signed direct upload) позволяет браузеру отправлять байты видео в Cloudinary, в то время как ваш бэкенд контролирует подписанные параметры. Бэкенд аутентифицирует пользователя, авторизует запрос, выбирает разрешенные опции и генерирует подпись. Браузер получает подпись, метку времени, ключ API и параметры загрузки, но никогда не получает секретный ключ API. Подписи аутентификации.
!Примечание: Не создавайте эндпоинт, который подписывает произвольные параметры, передаваемые клиентом. Например, ваш сервер может выбрать уникальный идентификатор (public ID), отключить перезапись и ограничить форматы до выдачи подписи.
Подпись не является одноразовым билетом на загрузку. Подписи загрузки Cloudinary остаются действительными в течение одного часа, а файлы и resource_type исключаются из подписанной строки. Подписание не проверяет подлинность самих байтов и не обеспечивает независимое соблюдение политики «только видео». Проверяйте сохраненный актив перед его связыванием с контентом приложения. Правила подписи.
Аутентификация загрузки и конфиденциальность воспроизведения — это разные вещи. По умолчанию ресурсы, использующие тип доставки upload, общедоступны; подписание загрузки этого не меняет. Для конфиденциальных видео выберите подходящее ограничение доставки перед загрузкой. Методы доступа к медиафайлам Cloudinary.
SDK для Node.js полезен, когда видео уже находится на вашем бэкенде, например при контролируемом импорте или задаче обработки. Он обрабатывает аутентификацию загрузки на основе конфигурации на стороне сервера.
Установите пакет:
Создайте файл .env, доступный только для сервера, замените эти заполнители и исключите файл из системы контроля версий:
Сохраните конфигурацию как cloudinary.mjs:
Затем сохраните upload-video.mjs. Этот пример командной строки принимает доверенный путь к локальному файлу и применяет собственный лимит в 50 МБ перед загрузкой:
Запустите его с вашим собственным тестовым файлом:
Явно укажите resource_type: "video", поскольку в противном случае стандартные методы загрузки SDK по умолчанию считают файлы изображениями. Эквивалент в REST использует эндпоинт video/upload; вы можете вызывать его напрямую при создании кастомного клиента. Параметры загрузки видео, Справочник Upload API.
Указанный выше префикс public-ID не означает то же самое, что папка Media Library в любой среде. В режиме фиксированной папки он определяет путь к папке. В режиме динамической папки используйте asset_folder для организации библиотеки; общедоступный идентификатор (public ID) остается отдельным. Режимы папок.
Для общедоступного приложения рассмотрите возможность подписанной загрузки из браузера в Cloudinary вместо пропуская через веб-сервер большие тела запросов. Если ваш сервер принимает потоки файлов, используйте потоковые методы SDK вместо загрузки всего видео в память.
Используйте метод пошаговой загрузки (chunked) для видео размером более 100 МБ в рамках максимального размера видео для вашего аккаунта. Меньший размер чанка не увеличивает этот лимит. Пошаговые методы Node.js в Cloudinary по умолчанию используют чанки по 20 МБ и поддерживают размеры от 5 МБ. Методы загрузки Node.js.
С конфигурацией сервера, приведенной выше, пошаговая загрузка локального файла может использовать эту обертку обратного вызова в Promise:
Протокол пошаговой загрузки возвращает промежуточные ответы с параметром done: false; финальное завершение включает done: true. Убедитесь, что вы не воспринимаете принятый чанк как завершенный актив. Кроме того, upload_large по умолчанию имеет тип raw, а его форма для локального файла возвращает поток (stream), а не Promise, возвращаемый для удаленного URL-адреса. Подходите к выбору метода и обработке завершения осознанно. Поведение пошаговой загрузки.
Разбиение на блоки повышает устойчивость к прерванным передачам. Само по себе оно не реализует возобновление загрузки после перезагрузки браузера или перезапуска вашего приложения.
Используйте Консоль, когда авторизованному члену команды необходимо добавить видео без интеграции интерфейса загрузки.
Откройте Assets > Media Library, выберите нужное место назначения в разделе Folders и нажмите Upload. Используйте My Files для выбора видео или перетащите файл в диалоговое окно. Настройте все доступные параметры Advanced перед выбором файлов. Текущая папка определяет место назначения загрузки; настройки загрузки по умолчанию в Консоли могут отличаться от тех, которые используются вашим API. Загрузка в медиабиблиотеку.
Представление Assets отфильтровано по существующему видеоприеру. Чтобы выбрать место назначения загрузки, используйте Folders перед началом новой загрузки.
Диалоговое окно загрузки в Консоли перед выбором файла. Доступные источники зависят от интеграции и конфигурации.
Вы также можете посмотреть пятисекундную демонстрацию источника загрузки ниже. На ней показано переключение с My Files на Web Address. Никакой файл или URL-адрес не отправляется, а отредактированная длительность не является измерением скорости загрузки.
Виджет Media Library позволяет редактору просматривать ассеты Cloudinary, не покидая систему управления контентом (CMS). Он также может предоставлять возможности загрузки, разрешенные для роли этого пользователя. В отличие от виджета Upload Widget, это аутентифицированный интерфейс управления ассетами, а не публичный загрузчик для клиентов. Каждому пользователю требуется место (seat) в Cloudinary; корпоративным клиентам (Enterprise) требуется план Assets. Требования к виджету Media Library.
В этом примере создается кнопка выбора ассетов и обрабатывается одно выбранное видео:
Имя облака (cloud name) выбирает окружение. Ключ API здесь необязателен, и его указание не заменяет вход пользователя или его разрешения. Никогда не внедряйте секрет API в код. Организации, использующие единый вход (SSO) на основе Security Assertion Markup Language (SAML), должны ознакомиться с документированными требованиями к настройке и файлам cookie браузера. Конфигурация виджета, требования для входа.
Обратный вызов выбора (selection callback) обновляет интерфейс; это не проверка разрешения на публикацию. Ваш бэкенд должен проверить выбранный ассет и разрешения приложения редактора перед сохранением его в запись.
Рассматривайте успешную передачу, завершенную обработку и разрешение на публикацию как разные проверки. Обратный вызов браузера является полезной обратной связью, но для персистентности приложения нужны надежные подтверждения.
Для примера серверной загрузки добавьте чтение через Admin API с использованием возвращенного неизменяемого идентификатора ассета:
Идентификатор asset_id остается стабильным, даже если общедоступный ID (public ID) ассета меняется. Чтение позволяет проверить фактический формат, размер в байтах, длительность и другие сохраненные свойства. Выполняйте этот вызов на стороне сервера и учитывайте лимиты запросов (rate limits) Admin API. Для загрузок из браузера дополнительно проверьте ожидаемое пространство имен, запись о поступлении (ingestion record) и принадлежность (ownership) перед связыванием ассета с контентом. Чтение ассета по идентификатору ассета, лимиты использования Admin API.
Используйте ответ, соответствующий операции:
Для async: true предоставьте notification_url. Для асинхронных немедленных (eager) выводов используйте eager_notification_url. Проверяйте подписи уведомлений и временные метки на соответствие исходному телу запроса перед изменением состояния приложения, а также делайте повторяющиеся события завершения безопасными для обработки. Асинхронные загрузки, немедленные (eager) трансформации, проверка уведомлений.
Загрузка файла MOV не означает, что каждый браузер сможет воспроизвести его исходное кодирование. Выберите формат доставки или рабочий процесс потоковой передачи, подходящий для вашей аудитории, а затем протестируйте фактический результат. Преобразованная копия является производной, а не заменой сохраненного оригинала, если вы явно не примете входящую трансформацию. Лучшие практики доставки видео.
Cloudinary Video Player поддерживает такие функции, как субтитры и адаптивная потоковая передача битрейта. Для более длинного контента оцените рабочий процесс потоковой передачи, вместо того чтобы полагаться на один URL-адрес исходного файла как на идеальное воспроизведение. Проверяйте необходимые трансформации, доступность и поведение доставки отдельно. Cloudinary Video Player, адаптивная потоковая передача битрейта.
Используйте этап сбоя (failure stage), чтобы выбрать способ устранения проблемы. Повторная загрузка не может решить проблему с неверной политикой доступа или с производным файлом, который все еще обрабатывается.
Примеры обучают механике загрузки, а не полноценной службе общедоступной загрузки. Прежде чем принимать публичный трафик, добавьте аутентификацию приложения там, где это необходимо, квоты, средства защиты от злоупотреблений, ограниченную параллельность, правила хранения и очистку отклоненных ассетов. Не предполагайте, что принятие формата гарантирует безопасность контента, лицензионные права или одобрение публикации. См. руководство Cloudinary по устранению неполадок при загрузке для ошибок, специфичных для сервиса.
Выбирайте путь загрузки в зависимости от пользователя и системы, выполняющих работу: Upload Widget для клиентов, API для операций, управляемых приложением, Консоль для ручной загрузки командой и виджет Media Library для редакторов внутри CMS.
Затем проверьте сохраненный ассет, дождитесь необходимой обработки и протестируйте предполагаемый результат доставки. Такое разделение дает вам рабочий процесс, который легко объяснить и отладить, а не средство выбора файлов, которое сообщает об успехе до того, как приложение будет готово использовать видео.
Готовы начать создание лучших визуальных медиа-интерфейсов? Зарегистрируйте бесплатную учетную запись Cloudinary сегодня.
