Практические руководства

Практическое руководство: систематизация ресурсов

Введение

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

Что потребуется?

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

Структура папок ресурсов

По умолчанию ресурсы создаются со следующей структурой папок:

Облачные устройства > {YYYY}_{MM}_{DD} > {ASSET_TYPE} > {YOUR_DEVICE} > {ASSET_NAME}, где {ASSET_TYPE} является ВИДЕО, АУДИО или ДАННЫМИ (настроенными для вашей модели устройства поканально), {YOUR_DEVICE} — это название устройства проекта, подключенного к проекту пользователя, а {ASSET_NAME} — это название добавленного вами ресурса и сам ресурс, который воспроизводится в Frame.io.

Перенаправление по расширению

Вы можете настроить устройство так, чтобы различные ресурсы направлялись в разные пользовательские папки {ASSET_TYPE} в зависимости от расширения файла в {ASSET_NAME}. Например, предположим, что ваша интеграция производит какое-то количество различных типов файлов, каждый из которых принадлежит к определенному происхождению. Можно указать, что эти ресурсы следует сопоставлять следующим образом:

.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans

Теперь, когда вы создаете следующий ресурс:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_codes]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "IMAGE_0001.jpeg", 
>            "filetype": "image/jpeg", 
>            "filesize": 21136250,
>            "offset": 10
>        }
>__JSON__
>} | python -m json.tool
Спецификация конечной точки API-интерфейса

Документацию для /v2/assets можно найти здесь

… будет перенаправлен в такое расположение, как: Облачные устройства > 2022_04_01 > STILLS > MY_DEVICE > IMAGE_0001.jpeg. Если файл вместо этого назван A001_C001.mov, его бы перенаправили в: Облачные устройства > 2022_04_01 > ВИДЕО > MY_DEVICE > A001_C001.mov.

Токенизированные пути добавления

Для некоторых интеграций может потребоваться больший контроль над структурой папок, которую создает их устройство. В свою очередь, мы в Frame.io должны убедиться, что существует определенный уровень согласованности в том, как файлы добавляются в Frame.io с устройства C2C, и конкретно гарантировать клиентам Frame.io, с какой частью их проекта может взаимодействовать устройство C2C. С этой целью мы позволяем интеграторам настраивать местоположения для добавления ресурсов в папке {YOUR_DEVICE}, но не разрешаем добавлять ресурсы за пределы этой папки.

Для добавления в пользовательскую структуру папок нужно обратиться к менеджеру по работе с партнерами. Пользовательские структуры папок — это набор токенизированных метаданных, которые должны предоставляться при создании ресурса. Рассмотрим простой пример:

Допустим, у нас есть материалы, снятые с помощью 3D-установки из двух камер, с такими значениями reel_name, как &quot;A001&quot;, &quot;A002&quot;, &quot;A003&quot; и т. д., и такими значениями clip_number, как &quot;C001&quot;, &quot;C002&quot; и т. д. Мы хотим создать папки для каждого клипа и заполнить их файлами левого и правого глаза, чтобы файлы в проекте выглядели следующим образом: Токенизированный путь к папке — пример для 3D-камеры

Для этого нужно настроить два параметра:

  • Обязательные поля метаданных
  • Токенизированный путь к файлу

Обязательные поля метаданных — это простой список ключей, которые должны быть заданы при создании ресурса для вашей интеграции:

[reel_name, clip_number]

Затем любой из этих ключей можно использовать для создания пути с разделителями /, используя {field_name} для обозначения места, куда должно быть вставлено значение поля:

REEL_{reel_name}/{reel_name}_{clip_number}

Оба эти параметра необходимо предоставить нашей команде в Frame.io, чтобы они были добавлены в сведения о вашей интеграции. После настройки эти значения необходимо указать при создании ресурса в корне полезной нагрузки, чтобы создание ресурса прошло успешно:

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

Приведенный выше код создаст файл с полным путем, например: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4

Ошибки метаданных

Если ваше устройство не настроено явно для работы с этими полями, вы получите ошибку при попытке выполнить тот же вызов. Аналогичным образом, если вы настроили обязательные поля метаданных, вы ДОЛЖНЫ указать их в полезной нагрузке создания ресурса, иначе будет возвращена ошибка.

Полезная нагрузка принимает любое допустимое значение JSON. Нестроковые значения отображаются следующим образом:

  • integers: отображаются в десятичной системе счисления: 10 -> &quot;10&quot;
  • floats: используется самое короткое представление в соответствии с алгоритмом, описанным в «Printing Floating-Point Numbers Quickly and Accurately» в материалах конференции SIGPLAN ‘96 Conference on Programming Language Design and Implementation.
  • booleans: true и false отображаются как &quot;true&quot; и &quot;false&quot;
  • null: отображается как пустая строка. Если reel_name задано как null, то первая пользовательская папка будет отображена как REEL_

В целом мы рекомендуем ограничиться строковыми значениями и форматировать другие значения по своему усмотрению (например, целые числа всегда выводятся без ведущих нулей, но вы можете изменить эту настройку).

В целом следует использовать только поля, которые имеют допустимое значение для каждого клипа; если поле не всегда имеет допустимое значение, у вас должен быть план представления незаданных значений или значений null.

Стекирование версий

Frame.io поддерживает стеки версий — способ объединения нескольких итераций одного и того же контента в пользовательском интерфейсе. API-интерфейс C2C позволяет устройствам добавлять новые итерации ресурса, которые будут помещены в стек версий с предыдущими версиями. Чтобы cоздать стек версий, необходимо указать autoversion_id для определения стека версий, к которому принадлежат ресурсы. Это значение может быть любым: UUID, имя файла и т. д. Будьте осторожны и используйте только значения, которые никогда не могут случайно повториться в папке ресурсов. Например, если ваша интеграция может cоздать одинаковое имя файла несколько раз, то имя файла не подходит для использования в качестве autoversion_id.

Мы указываем autoversion_id следующим образом:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v01.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 10,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

Теперь при добавлении нового ресурса с тем же autoversion_id он будет добавлен как последняя версия в стек с исходным ресурсом:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v02_with_color.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 10,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

Ресурсы будут объединяться в стек только при загрузке в ту же папку, поэтому при реализации стекирования версий учитывайте следующее:

  • Токенизированные метаданные должны разрешаться в ту же родительскую папку для создания стека версий.
  • Поскольку дата создания является частью пути к файлу, новые версии, созданные после полуночи по UTC, могут группироваться некорректно, если при создании исходной загрузки не указать смещение по времени.

Этот второй момент важен. Допустим, новая версия ресурса создается через 48 часов после первоначального добавления. Чтобы объединить ее с исходным ресурсом, необходимо указать смещение на 48 часов назад: 172800 секунд.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v03_with_color.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 172800,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

Без такого смещения текущий ресурс был бы загружен в 2022_04_03, а теперь он будет добавлен в 2022_04_01 и объединен с правильным ресурсом.

Далее

Это последнее руководство по созданию отличной интеграции C2C! Сейчас самое подходящее время похвалить себя! Можно съесть что-нибудь вкусное. Осталось только ознакомиться с контрольным списком интегратора: там есть сводка всего необходимого для создания надежной интеграции.

Если вы еще этого не сделали, рекомендуем связаться с нашей командой, а затем перейти к следующему руководству. Надеемся на скорую обратную связь!