SDK Frame.io для Python — руководство по добавлению файлов
SDK Frame.io для Python — руководство по добавлению файлов
В этом руководстве объясняется, как добавлять файлы в Frame.io с помощью SDK Frame.io для Python (frameio). SDK разбивает файлы на фрагменты и добавляет их частями в хранилище S3 через предварительно подписанные URL-адреса. При этом выполняются параллельные рабочие процессы, поддерживаются автоматические повторные попытки и предоставляется возможность отслеживать прогресс. Общие компоненты процесса добавлении файлов через API-интерфейс (URL-адреса для добавления, заголовки, разбиение на фрагменты) — в разделе Как работает локальное и удаленное добавление файлов.
Требования
Аутентификация
У вас есть рабочий клиент Frameio. Подробнее о настройке — в руководстве по аутентификации.
Быстрый старт
Готово. SDK разбивает файл на фрагменты на основе URL-адресов, полученных от API-интерфейса, добавляет их в хранилище в параллельном режиме и автоматически выполняет повторные попытки при сбоях.
Как это работает
Локальное добавление — это двухэтапный процесс.
Создание ресурса для файла
Вызовите метод client.files.create_local_upload() с указанием имени и размера файла. API-интерфейс создает файл-заполнитель и возвращает предварительно подписанные URL-адреса S3 PUT — по одному на фрагмент. Количество URL-адресов (и, следовательно, фрагментов) зависит от размера файла.
Добавление в S3
Компонент FrameioUploader считывает полученные в ответе URL-адреса для добавления, разбивает ваш файл на соответствующие фрагменты и в параллельном режиме отправляет каждый фрагмент по его URL-адресу, используя пул потоков. Каждый такой запрос автоматически включает обязательные заголовки x-amz-acl: private и Content-Type.
Добавление выполняется напрямую из вашего приложения в хранилище S3, минуя серверы API-интерфейса Frame.io. Аналогичную схему используют такие сервисы, как YouTube, Vimeo и Dropbox, для передачи больших файлов.
Использование компонента FrameioUploader
FrameioUploader — это рекомендуемый инструмент для добавления файлов. Он служит оберткой для низкоуровневого механизма добавления файлов и управляет всеми процессами: извлекает URL-адреса из ответа API-интерфейса, добавляет нужные заголовки, разбивает файлы на фрагменты и выполняет их параллельную отправку.
Отслеживание прогресса
Используйте функцию обратного вызова on_progress для отслеживания хода добавления.
Функция обратного вызова срабатывает после завершения отправки каждого фрагмента, отображая общее количество отправленных байтов и общий размер файла.
Индикатор выполнения на базе библиотеки Rich
Для создания эстетичного и информативного интерфейса в терминале используйте библиотеку Rich.
Конфигурация
FrameioUploader принимает несколько дополнительных параметров.
Полный пример
Полный пример кода с аутентификацией, добавлением файлов и отслеживанием прогресса.
Если вам нужен полный контроль над процессом добавления, например, чтобы вручную разбивать файлы на фрагменты, выполнять интеграцию с асинхронными конвейерами или настраивать логику повторных попыток, обратитесь к разделу Как работает локальное и удаленное добавление файлов, где описан прямой процесс работы с API-интерфейсом и приведен пример автономного сценария на Python.
Удаленное добавление
Если файл доступен по публичному URL-адресу, используйте удаленное добавление. В этом случае разбиение на фрагменты не требуется — Frame.io получает файл напрямую.
В настоящее время для удаленного добавления установлено ограничение на размер файла 50 ГБ. Для файлов размером более 50 ГБ используйте локальное добавление.
Проверка статуса отправки
После завершения отправки можно убедиться, что файл был получен.