Руководство по миграции с устаревшего API-интерфейса Frame.io на версию V4
Руководство по миграции с устаревшего API-интерфейса Frame.io на версию V4
Введение
API-интерфейс Frame.io V4 — это переработанная версия устаревшего API, который часто называют конечными точками V2 или API-интерфейсом Frame.io V3. Новая архитектура в полной мере использует возможности и функции Frame V4, сохраняя при этом всю ключевую функциональность прежней версии. В этом руководстве описываются ключевые различия между старой версией и V4 и даются пошаговые инструкции для плавной миграции.
Контрольный список миграции
Аутентификация
Для учетных записей, переведенных на версию V4, которые еще не управляются через Adobe Admin Console, можно продолжать использовать устаревшие токены разработчика, управление которыми осуществляется на сайте Frame.io Developer, однако потребуется добавить в свои запросы к API заголовок с ключом x-frameio-legacy-token-auth и значением true. В противном случае необходимо выполнить шаги, описанные ниже в разделе Аутентификация.
Обновление существующих вызовов API-интерфейса
Все прежние маршруты API-интерфейса необходимо сопоставить с новыми маршрутами API-интерфейса V4 и полезными нагрузками JSON. Ниже приведена довольно подробная таблица сопоставления, которая поможет в этом процессе.
Тестирование (настоятельно рекомендуется)
Проводите тщательное тестирование. Из-за большого количества изменений в API-интерфейсе рекомендуется использовать для тестирования учетную запись V4. Это позволит убедиться в корректной работе нового API-интерфейса.
Реализация отдельного входа в систему
Реализуйте отдельный метод входа в систему для версии V4, поскольку для нее используются другие URL-адреса аутентификации. URL-адрес аутентификации для V4 отличается от старого API-интерфейса, и в ответе не будут возвращаться учетные записи, еще не перешедшие на V4. Эту логику следует рассматривать как отдельную интеграцию.
Если у вас возникли вопросы по какой-либо конечной точке, не указанной в таблице сопоставления ниже, обратитесь в нашу службу поддержки по адресу support@frame.io.
Управление аутентификацией через Adobe Developer Console
Для учетных записей, переведенных на V4, которые управляются через Adobe Developer Console, необходимо использовать API-интерфейс V4 с протоколом OAuth2.0. Для этого выполните следующие шаги.
Создание проекта Adobe
Создайте проект в Adobe Developer Console и добавьте Frame.io в качестве продукта.
Выбор типа аутентификации
Выполните аутентификацию. Подробнее — в руководстве по аутентификации. Если ваша учетная запись V4 еще не управляется через Adobe Admin Console, вы можете пропустить этот шаг. * Аутентификация пользователя. Подключение к Frame выполняется с помощью идентификатора клиента и/или секретного ключа клиента и требует, чтобы пользователь вошел в систему с использованием имени пользователя и пароля. * Межсерверная аутентификация. Подключение к Frame выполняется с помощью идентификатора клиента и секретного ключа клиента, но не требует участия пользователя для входа в систему через браузер.
Сопоставление конечных точек (устаревшего API-интерфейса и V4)
Если вы используете аутентификацию с помощью устаревшего токена разработчика, вам нужно добавить в свои запросы к API-интерфейсу заголовок с ключом x-frameio-legacy-token-auth и значением true.
Общие примечания по миграции
Команды → рабочие среды
Понятие «команды» в устаревшем API-интерфейсе эквивалентно понятию «рабочие среды» в V4.
ресур.
Понятие «ресурсы» в устаревшем API-интерфейсе теперь разделено на «файлы», «папки» и «стеки версий» в V4.
Разрешения
В версии V4 изменены роли и разрешения, что меняет структуру конечных точек. В V4 используются роли пользователей на уровне рабочей среды и проекта. Подробнее — в разделе Управление разрешениями пользователей.
1. Учетные записи и информация о пользователе
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| GET | /v2/accounts (Получить учетные записи для пользователя) | GET | /v4/accounts (Список учетных записей) | V4 возвращает все учетные записи, к которым у пользователя есть доступ. |
| GET | /v2/accounts/{account_id} (Получить учетную запись по ID) | Н/Д | Н/Д | Информацию о конкретной учетной записи можно найти в конечной точке списка учетных записей. |
| GET | /v2/me (Получить текущего пользователя) | GET | /v4/me (Сведения о пользователе) | Позволяет получить профиль текущего пользователя. |
| GET | /v2/accounts/{account_id}/membership | Н/Д | Н/Д | Роли и права доступа управляются через разрешения на уровне рабочей среды и проекта. |
2. Рабочие среды (заменили конечные точки команд)
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| GET | /v2/accounts/{account_id}/teams (Получить все команды в учетной записи) | GET | /v4/accounts/{account_id}/workspaces (Список рабочих сред) | Понятие «команды» в устаревшем API-интерфейсе → «рабочие среды» в V4. |
| POST | /v2/accounts/{account_id}/teams (Создать команду для указанной учетной записи) | POST | /v4/accounts/{account_id}/workspaces (Создать рабочую среду) | Тело аналогично (название и т. д.). В ответе возвращается объект рабочей среды, а не объект команды. |
| GET | /v2/teams/{team_id} (Получить команду) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id} (Показать рабочую среду) | Идентификатор команды → идентификатор рабочей среды в V4. |
| GET | /v2/teams/{team_id}/members (Получить участников команды) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/users (Получить участников рабочей среды) | Возвращает всех пользователей в рабочей среде. |
| POST | /v2/teams/{team_id}/members (Добавить участника команды)) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/users/{user_id} (Добавить или обновить роль пользователя в рабочей среде) | Позволяет добавлять пользователей в рабочую среду или удалять их. |
| GET | /v2/teams/{team_id}/membership (Получить сведения об участии пользователей в команде) | Н/Д | Н/Д | Роли и права доступа управляются через разрешения на уровне рабочей среды и проекта. |
3. Проекты
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| GET | /v2/teams/{team_id}/projects (Получить проекты по команде) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects (Список проектов) | Необходимо указать account_id и workspace_id в V4. |
| GET | /v2/projects/shared | GET | /v4/accounts/{account_id}/invited_projects (Список проектов с приглашением) | Выводит список только проектов с приглашением. /v4/accounts/{account_id}/projects выводит список всех проектов, включая проекты с приглашением. |
| POST | /v2/teams/{team_id}/projects (Cоздать проект) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects (Cоздать проект) | Тело аналогично: { "name": "MyProject", ... }. |
| GET | /v2/projects/{project_id} (Получить проект по ID) | GET | /v4/accounts/{account_id}/projects/{project_id} (Показать проект) | Требуются account_id и project_id. |
| PUT | /v2/projects/{project_id} (Обновить проект) | PATCH | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id} (Обновить проект) | V4 использует PATCH для частичных обновлений. |
| DELETE | /v2/projects/{project_id} (Удалить проект по ID) | DELETE | /v4/accounts/{account_id}/workspaces/{workspace_id}/projects/{project_id} (Удалить проект) | Удаляет проект. |
| GET | /v2/projects/{project_id}/collaborators (Получить сведения о соавторах в проекте) | GET | /v4/accounts/{account_id}/projects/{project_id}/users (Список ролей пользователей в проекте) | Возвращает всех пользователей в проекте (ближайший эквивалент устаревшей конечной точки для соавторов). |
| POST | /v2/projects/{project_id}/collaborators (Добавить соавтора в проект) | PATCH | /v4/accounts/{account_id}/projects/{project_id}/users/{user_id} (Обновить роли пользователей для указанного проекта) | Позволяет добавлять пользователей в проект или удалять их (ближайший эквивалент устаревшей конечной точки для соавторов). |
4. Папки
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/children (Получить дочерние ресурсы) | GET | /v4/accounts/{account_id}/folders/{folder_id}/children (Список дочерних элементов папки) | Если в устаревшем API ваш идентификатор asset_id относился к папке, то в V4 он заменен на folder_id. |
| POST | /v2/assets/{parent_asset_id}/children (Создать ресурс) | POST | /v4/accounts/{account_id}/folders/{folder_id}/folders (Создать папку) | В устаревшем API вы использовали "type": "folder", а в V4 используется {"data": {"name": "Folder name"}}. |
| GET | /v2/assets/{asset_id} (Получить ресурс) | GET | /v4/accounts/{account_id}/folders/{folder_id} (Показать папку) | В устаревшем API-интерфейсе требуется параметр “type”: “folder”. В API-интерфейсе V4 требуются идентификаторы folder_id и account_id в параметрах пути. |
| PUT | /v2/assets/{asset_id} (Обновить ресурс) | PATCH | /v4/accounts/{account_id}/folders/{folder_id} (Обновить папку) | В устаревшем API asset_id будет идентификатором вашей папки. В API-интерфейсе V4 тело запроса — {"data": {"name": "New Folder Name"}}. |
| DELETE | /v2/assets/{asset_id} (Удалить ресурс) | DELETE | /v4/accounts/{account_id}/folders/{folder_id} (Удалить папку) | Удаляет папку. |
| Н/Д | Н/Д | GET | /v4/accounts/{account_id}/folders/{folder_id}/folders (Список папок) | Выводит список папок внутри указанной папки. (Получите идентификатор root_folder_id из маршрута отображения проекта, после чего сможете использовать его для вывода списка всех папок на самом верхнем уровне.) |
5. Стеки версий
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| POST | /v2/assets/{destination_folder}/copy (Копировать ресурс) | POST | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/copy (Копировать стек версий) | В устаревшем API-интерфейсе папка назначения указывается в параметрах пути; используется со стеком версий в запросе. В V4 копируется стек версий. |
| POST | /v2/assets/{asset_id}/version (Создать версию ресурса) | POST | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks (Создать стек версий) | Создается стек версий. Требуется 2–10 идентификаторов файлов в теле запроса. |
| POST | /v2/assets/{asset_id}/version (Создать версию ресурса) | PATCH | /v4/accounts/{account_id}/files/{file_id}/move (Переместить файл в стек версий) | Файл перемещается в существующий стек версий. Используйте version_stack_id в качестве parent_id в теле запроса. |
| GET | /v2/assets/{asset_id}/children (Получить дочерние ресурсы) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/children (Список дочерних элементов стека версий) | В устаревшем API-интерфейсе используется с идентификатором asset_id стека версий. В V4 — список дочерних элементов (файлов/версий) в стеке версий. |
| Н/Д | Н/Д | GET | /v4/accounts/{account_id}/folders/{folder_id}/version_stacks (Список стеков версий) | Выводится список стеков версий в папке. |
| Н/Д | Н/Д | PATCH | /v4/accounts/{account_id}/version_stacks/{version_stack_id}/move (Переместить стек версий) | Стек версий перемещается в другую папку. |
| GET | /v2/assets/{asset_id} (Получить ресурс) | GET | /v4/accounts/{account_id}/version_stacks/{version_stack_id} (Показать стек версий) | В устаревшем API-интерфейсе используется с идентификатором asset_id стека версий. В V4 отображаются сведения о стеке версий. |
| DELETE | /v2/assets/{asset_id}/unversion (Удалить версию) | Н/Д | Н/Д | Удаление файлов из стека версий в настоящее время не поддерживается в V4. |
6. Файлы
Примечание. Теперь в V4 есть две конечные точки для создания файлов (локально и через добавление в S3). Подробнее — в разделе Добавление файлов.
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| POST | /v2/assets/{parent_asset_id}/children (Создать ресурс) | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/local_upload (Создать файл (локальное добавление)) | В устаревшем API-интерфейсе требуются имя, тип, тип файла, размер файла и идентификатор auto_version_id. В API V4-интерфейсе требуются идентификаторы account_id и folder_id в параметрах пути; в полезной нагрузке требуются размер файла и имя. |
| Н/Д | Н/Д | POST | /v4/accounts/{account_id}/folders/{folder_id}/files/remote_upload (Создать файл (удаленное добавление)) | В параметрах пути требуются идентификаторы account_id и folder_id; в полезной нагрузке требуются URL-адрес источника и имя. |
| GET | /v2/assets/{asset_id} (Получить ресурс) | GET | /v4/accounts/{account_id}/files/{file_id} (Показать файл) | Выводятся сведения о файле. Доступны различные включения, позволяющие получать дополнительные сведения о файле в ответе. |
| Н/Д | Н/Д | GET | /v4/accounts/{account_id}/files/{file_id}/status (Получить метаданные файла) | Выполняется получение статуса удаленного добавления из конечной точки «Создать файл (удаленное добавление)». |
| PUT | /v2/assets/{asset_id} (Обновить ресурс) | PATCH | /v4/accounts/{account_id}/files/{file_id} (Обновить файл) | Обновляется имя файла. |
| DELETE | /v2/assets/{asset_id} (Удалить ресурс) | DELETE | /v4/accounts/{account_id}/files/{file_id} (Удалить файл) | Код состояния 204 (нет содержимого) при успешном выполнении. |
7. Комментарии
На данный момент в API-интерфейсе V4 поддерживается большинство функций работы с комментариями.
Функции, которые появятся в ближайшее время:
- реакции на комментарии, например эмодзи;
- просмотр или изменение статуса выполнения комментария;
- отслеживание того, кто просмотрел комментарий (количества просмотров).
Поле «timestamp» указывает на метку кадра, на котором оставлен комментарий (начиная с 1), а не временную метку
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| GET | /v2/assets/{asset_id}/comments (Получить все комментарии и ответы из цепочки комментариев) | GET | /v4/accounts/{account_id}/files/{file_id}/comments (Список комментариев) | Выводится список комментариев к файлу. |
| POST | /v2/assets/{asset_id}/comments (Создать комментарий) | POST | /v4/accounts/{account_id}/files/{asset_id}/comments (Создать комментарий) | Создается комментарий. Тело аналогично: {"text":"Nice","timestamp":12.3}. |
| GET | /v2/comments/{comment_id} (Получить комментарий по ID) | GET | /v4/accounts/{account_id}/comments/{comment_id} (Показать комментарий) | Выполняется получение отдельного комментария по ID. |
| PUT | /v2/comments/{comment_id} (Обновить комментарий) | PATCH | /v4/accounts/{account_id}/comments/{comment_id} (Обновить комментарий) | Обновляется текст, время и т. д. |
| DELETE | /v2/comments/{comment_id} (Удалить комментарий) | DELETE | /v4/accounts/{account_id}/comments/{comment_id} (Удалить комментарий) | Удаляется комментарий. |
| GET | /v2/comments/{comment_id}/impressions (Получить количество просмотров) | Н/Д | Н/Д | Функция получения количества просмотров в настоящее время не поддерживается в V4. |
8. Общий доступ (ссылки для рецензирования / презентации)
В Frame V4 ссылки общего доступа больше не разделяются на ссылки для рецензирования и ссылки на презентации. Теперь в V4 можно настроить различные стили для таких ссылок, чтобы они соответствовали интерфейсу рецензирования или презентации.
Примечание. Взаимодействие с устаревшими ссылками для рецензирования и презентациями через API-интерфейс V4 не поддерживается.
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| GET | /v2/projects/{project_id}/review_links (Список ссылок на рецензирование в проекте) | GET | /v4/accounts/{account_id}/projects/{project_id}/shares (Список общих ресурсов) | Выводит список общих ресурсов в проекте (обратите внимание, что сюда не входят устаревшие ссылки на рецензирование и презентации). |
| POST | /v2/projects/{project_id}/review_links (Создать ссылку для рецензирования) | POST | /v4/accounts/{account_id}/projects/{project_id}/shares (Создать общий ресурс) | Создает новую ссылку общего доступа. Тело может иметь вид {"data":{"name":"Review Link","type":"review"}}. |
| POST | /v2/review_links/{link_id}/assets (Добавить ресурс в ссылку для рецензирования) | POST | /v4/accounts/{account_id}/shares/{share_id}/assets (Добавить новый ресурс в ссылку общего доступа) | Добавляет ресурс в ссылку общего доступа. Поддерживаются файлы, папки и стеки версий. |
| Н/Д | Не существует | DELETE | /v4/accounts/{account_id}/shares/{share_id}/assets/{asset_id} (Удалить общий ресурс) | Удаляет ресурс из ссылки общего доступа. |
| DELETE | /v2/review_links/{link_id} (Удалить ссылку для рецензирования) | DELETE | /v4/accounts/{account_id}/shares/{share_id} (Удалить общий ресурс) | Удаляет ссылку общего доступа. |
| PUT | /v2/review_links/{review_link_id} (Обновить ссылку для рецензирования) | PATCH | /v4/accounts/{account_id}/shares/{share_id} (Обновить общий ресурс) | Обновляет ссылку общего доступа. |
9. Веб-перехватчики
Веб-перехватчики, которые вы использовали в V3, будут перенесены и в большинстве случаев продолжат работать так же. Сразу после миграции они будут отключены и их нужно будет включить для возобновления работы. Потребуются некоторые изменения для событий ресурсов, которые теперь разделены на файлы и папки. Также обратите внимание на новые события, специфичные для версии V4: события metadata.value.updated, а также события, связанные с коллекциями и общим доступом.
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/hooks (Создать веб-перехватчик) | POST | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks (Создать веб-перехватчик) | Передайте данные в следующем формате: {"data":{"url":"...","events":["file.created",...]}}. |
| GET | /v2/accounts/{account_id}/webhooks (Получить веб-перехватчики для учетной записи) | GET | /v4/accounts/{account_id}/workspaces/{workspaces_id}/webhooks (Список веб-перехватчиков) | Позволяет получить все веб-перехватчики для рабочей среды. Примечание. Чтобы получить все веб-перехватчики для учетной записи, необходимо получить все рабочие среды для данной учетной записи, а затем получить все веб-перехватчики для этих рабочих сред. |
| GET | /v2/hooks/{hook_id} (Получить веб-перехватчик) | GET | /v4/accounts/{account_id}/webhooks/{webhook_id} (Список веб-перехватчиков) | Позволяет получить информацию о веб-перехватчиках. |
| PUT | /v2/hooks/{hook_id} (Обновить веб-перехватчик) | PATCH | /v4/accounts/{account_id}/webhooks/{webhook_id} (Обновить веб-перехватчик) | Обновляет настройки веб-перехватчика. |
| DELETE | /v2/hooks/{hook_id} (Удалить веб-перехватчик) | DELETE | /v4/accounts/{account_id}/webhooks/{webhook_id} (Удалить веб-перехватчик) | Удаляет веб-перехватчик. |
10. Пользовательские действия
Пользовательские действия, которые вы использовали в V3, будут перенесены, но потребуют некоторых изменений в обработке запросов и ответов. Сразу после миграции они будут отключены и их нужно будет включить для возобновления работы. Подробнее — в этом (документе).
Примечание. Конечные точки пользовательских действий в настоящее время находятся в экспериментальном API-интерфейсе и потребуют заголовка «api-version: experimental».
| Метод | Устаревшая конечная точка | Метод | Конечная точка V4 | Примечания |
|---|---|---|---|---|
| POST | /v2/teams/{team_id}/actions (Создать пользовательское действие) | POST | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Создать пользовательское действие) | Создает пользовательское действие в рабочей среде. |
| DELETE | /v2/actions/{action_id} (Удалить пользовательское действие) | DELETE | /v4/accounts/{account_id}/actions/{action_id} (Удалить пользовательское действие) | Удаляет пользовательское действие. |
| PUT | /v2/actions/{action_id} (Обновить пользовательское действие) | PATCH | /v4/accounts/{account_id}/actions/{action_id} (Обновить пользовательское действие) | Обновляет сведения о пользовательском действии. |
| GET | /v2/teams/{team_id}/actions (Получить пользовательские действия для команды) | GET | /v4/accounts/{account_id}/workspaces/{workspace_id}/actions (Список пользовательских действий) | Выводит список пользовательских действий в указанной рабочей среде. |
| GET | /v2/actions/{action_id} (Получить пользовательское действие по ID) | GET | /v4/accounts/{account_id}/actions/{action_id} (Показать сведения о пользовательском действии) | Выводит сведения о пользовательском действии. |
Этапы миграции
Настройка неподдерживаемых конечных точек V2
Настройте любые неподдерживаемые устаревшие конечные точки V2.
Обновление базовых URL-адресов
Обновите базовые URL-адреса с api.frame.io/v2/... до api.frame.io/v4/....
Обновление запросов к API-интерфейсу
Обновите запросы к API-интерфейсу в своем коде, чтобы они ссылались на новую схему конечных точек.
Обновление полезной нагрузки JSON
Обновите полезную нагрузку JSON в схемах запросов/ответов, чтобы создавались и использовались правильные поля.
Обновление терминологии
Обновите терминологию: «команды» → «рабочие среды»; «ресурсы» → «файлы/папки»; «ссылки для рецензирования» или «ссылки на презентацию» → «общие ресурсы» в коде и интерфейсе.
Тестирование конечных точек
Протестируйте все недавно обновленные конечные точки. Если появляются ошибки 403, 404, 422, проверьте конечные точки, структуру полезной нагрузки запроса и другие параметры.
Анализ ответов об ошибках
Проанализируйте новые возвращаемые сведения об ошибках и найдите проблему в ответе JSON {"errors": [...]} в случае неудачного вызова API-интерфейса.
Развертывание в производство
Разверните свое решение в производство после подтверждения корректной работы с учетной записью в Frame.io V4.
Обработка ошибок и распространенные проблемы
Некоторые маршруты могут возвращать ошибки с пользовательскими описаниями, которые могут незначительно отличаться от приведенных ниже примеров.
- 400 (неправильный запрос): проверьте точность полезной нагрузки. * 401 (не авторизован): недействительный или отсутствующий токен авторизации. * 403 (запрещено): отсутствует область доступа или у пользователя нет нужных прав. * 404 (не найдено): подтвердите конечную точку, версию API-интерфейса или идентификаторы. * 422 (необрабатываемая сущность): проверьте данные запроса * 429 (слишком много запросов): выполните повторный запрос с экспоненциальной задержкой.
- 500 (внутренняя ошибка сервера): повторите попытку после небольшой задержки.
Поддержка SDK
Как и для предыдущей версии, разработчикам доступен SDK для Python, а также впервые появился SDK для TypeScript. Эти SDK обладают схожей функциональностью, но используют совершенно разные методы, поэтому, если вы обновляете SDK с устаревших до версии V4, обязательно обновите свой код соответствующим образом. SDK доступны по ссылкам ниже:
Начало работы с SDK, SDK для Python, SDK для Typescript.