Управление стеками версий

Обзор

Стеки версий — это принцип систематизации в Frame.io, который позволяет размещать ресурсы вертикально в «стеки», не помещая их в папки. Стеки версий упрощают навигацию от актива к активу в пользовательском интерфейсе Frame.io и поддерживают параллельный просмотр.

В настоящее время мы не поддерживаем прямое добавление в стек, поэтому последовательность API-интерфейса для управления базовым рабочим процессом стека версий будет следовать той же последовательности, что и в пользовательском интерфейсе Frame.io:

1. Добавление ресурса (по желанию: пометьте как частный).
2. Назначение ресурса в стек.

Существующие стеки версий можно переупорядочить, а отдельные версии можно исключить из стека. Наконец, стеки версий можно удалить, не удаляя ни один из составляющих их ресурсов.

Основные концепции

Стеки версий, как и папки, — это специальные типы ресурсов. Вы можете получить их с помощью тех же конечных точек, и на основе значения ключа тип в ответе API-интерфейса выполнять анализ и маршрутизацию соответствующим образом. Как правило, на практике это просто, но может представлять некоторые сложности при масштабном управлении стеками. Ключ к работе со стеками версий заключается в разделении четырех наиболее распространенных сценариев:

1. Ресурс можно добавить к ресурсу, что создаст стек с новым ИД.
2. Ресурс можно добавить к существующему стеку.
3. Стек можно переупорядочить.
4. Отдельные версии можно удалить.

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

1. Стеки должны совпадать по asset_type (например, нельзя разместить image в стеке со stream).
2. Действующий пользователь должен иметь разрешения как для исходного ресурса, так и для целевого ресурса или стека.
3. Последовательное размещение ресурсов в стеке.
4. Нельзя наложить стек на стек.
5. Папки исключены.

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

Необходимые области доступа

Перед началом работы с этим руководством убедитесь, что у вас есть токен, который включает следующие области доступа:

Добавление ресурсов в стеки версий

Шаг 1. Поиск места назначения

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

Если вы знаете, что работаете с неверсированным ресурсом, или у вас уже есть ИД стека версий, можете переходить к шагу 2.

Если нет, далее представлен самый простой способ определить, является ли целевой ресурс уже частью стека:

1. Выполнить запрос GET к вашему целевому ресурсу по адресу /v2/assets/:id​

2. Проверьте возвращаемый тип.

• Если это version_stack, uuid, который вы только что проверили, — это ваш целевой uuid. Переходите к шагу 2.

3. Если тип — это файл, возьмите parent_id.
4. Выполните запрос GET к родительскому элементу через ту же конечную точку и проверьте его тип.

Если тип родительского элемента — version_stack, используйте его ИД как место назначения. Если тип — это что-то другое, это обычный ресурс и можно использовать исходный ИД как место назначения.

Шаг 2. Подготовка полезной нагрузки

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

1. Если вы добавляете новый ресурс, просто используйте идентификатор, полученный в ответе о выполнении, когда вы создаете ресурс.
2. Если вы добавляете существующий ресурс в стек, у вас должен быть идентификатор, полученный в результате процесса, описанного выше.

Единственный параметр тела, необходимый для добавления в стек версий, — это next_asset_id:

1
{
2
    "next_asset_id": "<source-asset-id>"
3
}

Шаг 3. Добавление исходного ресурса к целевому

Теперь, когда у вас есть оба параметра идентификатора ресурса, вы готовы выполнить запрос POST по адресу /assets/:id/version, где :id — это ваш целевой ресурс или стек версий, а исходный (новый) ресурс находится в теле запроса.

Переупорядочение стеками версий

Стеки версий основаны на простой порядковой концепции, где у каждого ресурса есть соседи next_asset_id и prev_asset_id, при этом порядок относится не к нумерации версий, а к атрибуту index каждого ресурса. index идет в противоположном направлении от номеров версий, соответственно:

• Первая (с наименьшим номером) версия в стеке имеет предыдущий ресурс, но не имеет следующего ресурса.
• Более новая (с наибольшим номером) версия в стеке имеет следующий ресурс, но не имеет предыдущего ресурса.
• Все «внутренние» версии имеют как предыдущий, так и следующий ресурс, которые являются ресурсами с более высокими и более низкими идентификаторами версий соответственно.

Это дает нам три различных сценария, все из которых используют один и тот же вызов конечной точки:

Вызов:

PUT https://api.frame.io/v2/asset/:id/tween

Тело:

1
{
2
  "prev_asset_id": "<asset_id>",
3
  "next_asset_id": "<asset_id>"
4
}

Во всех случаях ИД в пути URL-адреса будет ресурсом, который вы перемещаете.

Удаление ресурсов и удаление стеков версий

Удаление ресурсов

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

1. Выполните запрос GET к стеку версий с помощью вызова /v2/assets/:id
2. Возьмите parent_id стека (который станет вашим новым ИД целевой папки)
3. Переместите целевой ресурс в папку следующим образом:

Вызов:

POST https://api.frame.io/v2/assets/:parent_id/move

Тело:

1
{
2
    "id":"<asset_id>"
3
}

Удаление стеков версий

Удаление стека версий выполняется очень просто:

DELETE https://api.frame.io/v2/assets/:version_stack_id/unversion

Вот и все. При удалении стека все составляющие его ресурсы возвращаются в папку, где располагался стек.

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

Для получения дополнительной информации о конечной точке стекирования версий см. документацию по ресурс ам.