Практическое руководство: добавление (базовое)

Введение

Мы достигли важного этапа в нашем процессе интеграции: добавление ресурсов в Frame.io. Это руководство поможет вам пройти через базовый процесс добавления.

Требования

Если вы еще не сделали этого, просмотрите руководство Реализация C2C: настройка перед продолжением. Вам понадобится access_token, полученный в процессе аутентификации и авторизации. Для этого руководства мы используем образец тестового ресурса, доступный по этой ссылке Frame.io. Загрузите этот файл, чтобы следовать нашим примерам, поскольку это позволит вам сопоставить значения в наших образцах команд.

Шаг 1. Создание ресурса

Добавим наш образец файла, который, как мы предполагаем, создан 10 секунд назад. Сначала нам нужно создать ссылку на ресурс в Frame.io:

$
{
>
curl -X POST https://api.frame.io/v2/devices/assets \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__' 
>
        {
>
            "name": "C2C_TEST_CLIP.mp4", 
>
            "filetype": "video/mp4", 
>
            "filesize": 21136250,
>
            "offset": 10
>
        }
>
__JSON__
>
} | python -m json.tool

Рассмотрим параметры полезной нагрузки JSON:

имя: отображаемое имя ресурса в Frame.io. Оно не должно совпадать с именем файла на диске. filetype: тип файла MIME. Большинство языков программирования предоставляют утилиты для определения типа MIME (примеры: Go, Python). filesize: размер файла в байтах. Размер нашего образца файла приблизительно 21,1 МБ. offset: количество секунд с момента создания файла. По умолчанию 0, если не указано. Этот параметр должен быть предоставлен, поскольку он помогает определить, следует ли отклонить файлы из-за приостановки устройства. Мы рассмотрим это более подробно в расширенном руководстве по добавлению.

Ответ будет выглядеть примерно так (некоторые поля опущены):

1
{
2
    "_type": "file",
3
    ...
4
    "id": "9a280f99-8f4f-46b0-a4b4-ec4c2f95138e",
5
    ...
6
    "upload_urls": [
7
        "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path]",
8
        "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path]"
9
    ],
10
    ...
11
}

На данном этапе мы только уведомили Frame.io о нашем намерении добавить файл; никакие фактические данные файла не были переданы. Если вы проверите папку вашего устройства в проекте, то увидите заполнитель ресурса в состоянии «добавление».

Поле upload_urls содержит URL-адреса, по которым мы будем добавлять фрагменты нашего файла. Для нашего тестового файла мы должны получить два URL-адреса добавления.

Шаг 2. Разделение файла на фрагменты

Ответ содержал несколько URL-адресов добавления. При добавлении в Frame.io мы разделяем файлы на фрагменты и добавляем их отдельно, что дает несколько преимуществ:

• Улучшенная надежность: если один фрагмент не добавляется, нам не нужно перезапускать весь процесс добавления.
• Более быстрые операции добавления: мы можем добавлять несколько фрагментов параллельно (рассматривается в руководстве по расширенным добавлениям)

Чтобы определить оптимальный размер фрагмента, используйте эту формулу:

1
# We use math.ceil() to ensure we get the upper bound in the division
2
chunk_size = math.ceil(float(file.size) / float(len(response.upload_urls)))

Для нашего образца файла расчет выглядит так:

1
math.ceil(21136250 / 2)
2
# 10568125

Это означает, что каждый фрагмент должен быть 10 568 125 байтов. Размеры фрагментов обычно составляют около 25 МБ, точные расчеты рассматриваются в руководстве по расширенным операциям добавления.

Для этой демонстрации мы будем использовать команды head и tail, чтобы извлекать фрагменты файла.

Шаг 3. Добавление фрагментов

Добавление первого фрагмента:

$
head -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \
>
curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path] \
>
        --include \
>
        --header 'content-type: video/mp4' \
>
        --header 'x-amz-acl: private' \
>
        --data-binary @-

Запрос требует следующих заголовков:

content-type: то же значение типа MIME, которое использовалось при создании ресурса x-amz-acl. Для разрешений AWS S3 всегда задавайте значение частный

Если добавление выполнено, возвращается:

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
...

Таким же способом добавьте второй фрагмент:

$
tail -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \
>
curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path] \
>
        --include \
>
        --header 'content-type: video/mp4' \
>
        --header 'x-amz-acl: private' \
>
        --data-binary @-

После выполнения обеих операций добавления ваш ресурс должен воспроизводиться в Frame.io! 🎉

Объединение

Вот упрощенный пример псевдокода на Python для полного процесса добавления:

1
file = open("~/Downloads/C2C_TEST_CLIP.mp4")
2
mimetype = mimetypes.for_file("~/Downloads/C2C_TEST_CLIP.mp4")[0]
3
created_at = time.ctime(file.stat.ST_CTIME)
4
5
asset = c2c.asset_create(
6
    name="C2C_TEST_CLIP.mp4", 
7
    filetype=mimetype, 
8
    filesize=file.size,
9
    offset=datetime.now() - created_at,
10
    channel=0,
11
)
12
13
chunk_size = math.ceil(float(file.size) / float(len(asset.upload_urls)))
14
15
for chunk_url in asset.upload_urls:
16
   chunk = file.read(bytes=chunk_size)
17
   c2c.upload_chunk(chunk, chunk_url, mimetype)

Этот пример показывает базовый поток без обработки ошибок или параллельных операций добавления, которые будут рассмотрены в руководствах по обработке ошибок и расширенным добавлениям.

Дальнейшие шаги

Поздравляем с добавлением первого ресурса в Frame.io! В руководстве по расширенным операциям добавления будут более сложные техники и требования для готовых к использованию реализаций. Мы рекомендуем обращаться к нашей команде с любыми вопросами и переходить к руководству по добавлению в реальном времени, чтобы узнать о добавлении ресурсов такими, какими они созданы.