Рабочие процессы — ресурсы

Чтение дерева файлов

Обзор

Независимо от того, является ли конечной целью публикация, редактирование или продвижение ресурсов по этапам рабочего процесса, многие глубокие интеграции с Frame.io будут включать получение списка пользовательского контекста и, в конечном итоге, представление в виде каталогов.

Вот основная иерархия ресурсов (или файлов) в Frame.io:

Учетная запись > Команда > Проект > Ресурсы

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

Важные понятия

У каждого проекта есть уникальный корневой ресурс

RESTful API обычно описывают ресурсы, используя уникальные идентификаторы; root_asset_id — это уникальный идентификатор дерева ресурсов вашего проекта. Рассматривайте его как специальную конструкцию, действующую как корневой узел для проекта: остальные ресурсы располагаются под корнем в виде нисходящего дерева. root-asset-id

В обычных рабочих процессах пользователям API-интерфейса необходимо спускаться по дереву для более глубокого взаимодействия с ресурсами в иерархии файлов.

Соавторы и общие проекты

Соавтор — это ключевая пользовательская роль в Frame.io: такие пользователи имеют доступ к рабочей среде проекта, но могут не принадлежать к общей учетной записи этого проекта. Если не учитывать различные разрешения для соавторов и участников команды, основное отличие заключается в том, что участие соавтора строго относится к проекту и может не иметь отношения к команде.

Это создает небольшую сложность для рабочих процессов, где списки каталогов имеют первостепенное значение. Хотя базовая иерархия выше (Учетная запись > Команда > Проект > Ресурсы) должна работать для большинства случаев использования, она не будет описывать проекты, где аутентифицированный пользователь является соавтором, но не участником команды. Чтобы обойти это при составлении списков каталогов, можно:

  • получить общие проекты пользователя, распаковать иерархию команды и учетной записи и объединить все вместе или
  • получить общие проекты пользователя и перечислить их все вместе как отдельный контекст.

Любой метод подходит; последний немного проще, но первый ближе к тому, как веб-приложение Frame.io представляет подобную информацию. В любом случае методы, рассмотренные в этом руководстве, применимы к обоим.

Составление списка каталога

1. Получение учетных записей пользователя

GET https://api.frame.io/v2/accounts

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

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

  • ИД
  • display_name
  • owner (адрес электронной почты, имя)
  • (необязательно) image
URL-адреса изображений учетных записей временны

Примечание. Изображение учетной записи, возвращаемое нашим API-интерфейсам, будет предварительно подписанным ключом S3, поэтому срок действия возвращенного URL-адреса истечет примерно через день. Чтобы обойти это, вы должны либо повторно получать изображение каждый раз при загрузке вашего сервиса, либо, в идеале, сохранять его локально.

Обратите внимание, что ИД и owner.email являются единственными обязательными полями в учетной записи пользователя. Если вы отображаете пользователей в другом приложении, рассмотрите возможность написания условной логики для представления учетных записей пользователей. Мы рекомендуем проверить, и если не null, отображать учетную запись в следующем порядке:

  1. “display_name”
  2. “Учетная запись пользователя owner.name”
  3. “Учетная запись owner.email”

После того как ваш пользователь выберет учетную запись, вы захотите представить команды. Это требует дополнительного запроса API-интерфейса.

2. Получение команд в учетной записи

GET https://api.frame.io/v2/accounts/{{account_id}}/teams Группы в Frame.io могут быть «общедоступными» (т.е. доступными для обнаружения любым участником команды в учетной записи) или «частными» (доступными для обнаружения только конкретным участникам команды). API-интерфейс обработает контекст за вас, поэтому все, что вам нужно сделать, это выполнить действительный вызов, указав account_id в указанном выше запросе.

Не забудьте о разбивке на страницы

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

Дополнительную информацию о разбивке на страницы можно найти в разделе Разбивка на страницы и ошибки. Из каждой команды получите следующие атрибуты:

  • ИД
  • имя
  • (необязательно) team_image

При выборе команды отображаются ее проекты.

Примечание. Можно также выполнить запрос GET https://api.frame.io/v2/teams для пользователя, и наш API-интерфейс вернет каждую команду, к которой принадлежит пользователь, независимо от контекста учетной записи. Хотя технически это работает, вы рискуете потерять контекст, если не предпримете дополнительный шаг:

  1. Восстановите контекст, указав название учетной записи рядом с каждой командой.
  2. Предоставьте пользователю возможность поиска по тексту списка.

При перечислении общих проектов с уровня учетной записи необходимо сделать дополнительный вызов GET https://api.frame.io/v2/projects/shared. Каждый проект, возвращенный в ответе, будет содержать следующие атрибуты, которые можно использовать при создании каталога:

  • ИД (самого проекта)
  • team_id
  • team.account_id

Или можно создать возможность для «Общих проектов», просто добавив их как «команду» в любом выбранном контексте учетной записи. Если вы решите это сделать, для конечного пользователя будет полезно визуально отделить общие проекты от истинных проектов команды, поскольку единый список общих проектов может включать множество различных контекстов истинных учетных записей и команд.

3. Получение проектов команды

GET https://api.frame.io/v2/teams/{{team_id}}/projects

Далее выполните указанный выше вызов и получите все проекты в команде.

Для каждого проекта потребуется получить:

  • ИД
  • имя
  • root_asset_id
  • (необязательно) частный, если хотите настроить дифференциацию для пользователя в вашем интерфейсе.

Как объяснено в начале статьи, root_asset_id — важная часть архитектуры ресурсов Frame.io, поскольку позволяет перемещаться по каталогу файлов и папок в проекте.

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

Вкратце о том, что уже сделано. Мы установили объединенный контекст:

| * Учетная запись

| * Команда

| * Проекты команды (и root_asset_ids)

| * Общие проекты (и root_asset_ids)

| Этого достаточно для создания или получения ресурсов.

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

4. Создание исходной структуры папок

GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder Отобразит все папки в проекте, начиная с root_asset_id. Если папок нет, вернется пустой список. Чтобы включить файлы и папки (например, если ваш следующий шаг — выполнить запрос GET к ресурсу из Frame.io, просто опустите параметр строки запроса.

Другие два варианта фильтра, доступные для параметра «тип», — это файл и version_stack. Все три фильтра взаимно исключающие, и нефильтрованный вызов вернет все три типа вперемешку.

5. Ознакомление с деревом каталога

Для каждой папки, которая возвращается, вам нужно получить:

  • ИД
  • имя

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

  1. GET https://api.frame.io/v2/assets/{{root_asset_id}}/children?type=folder

  2. Выведите названия папок в списке.

  3. Когда пользователь нажимает на папку, передайте идентификатор папки в следующий запрос:

  4. GET https://api.frame.io/v2/assets/{{folder_id}}/children?type=folder

6. Создайте и добавьте

В папку: POST https://api.frame.io/v2/{{folder_id}}/children После получения идентификатора папки, в которую нужно выполнить добавление, просто выполните запрос POST к ее дочерним элементам, следуя документации по ресурсу и руководству. В результате создается заполнитель ресурса и (в зависимости от выбранного метода) возвращается:

  • uuid, предназначенный для отслеживания случаев использования.
  • Список upload_urls, которые можно использовать для выполнения запроса PUT к файлу непосредственно в серверное хранилище данных Frame.io.

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

  • ИД стека версий
  • parent_id стека версий (например, содержащая его папка или корень проекта)

Сначала выполните запрос POST по адресу https://api.frame.io/v2/assets/{{parent_id}}/children, чтобы создать новый ресурс. Получите новый ИД в ответе. Теперь вы можете использовать новый идентификатор ресурса и выполнять запрос POST по адресу https://api.frame.io/v2/assets/{{version_stack_id}}/version, передав в теле запроса следующее:

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