Интеграции C2C

Архитектура интеграции

Введение

Прежде чем приступать к созданию запросов к API-интерфейсу, необходимо понять базовую архитектуру интеграций C2C. (Не волнуйтесь — в следующей статье вы перейдете к работе в терминале. А пока рассмотрим основные понятия.)

Упрощенная модель данных для вашей интеграции будет выглядеть примерно так:

                                   ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 01 │ -> │ Project │
┌───────────┐    ┌──────────────┐  └───────────────────┘    └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘    └──────────────┘  ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 02 │ -> │ Project │
                                   └───────────────────┘    └─────────┘

Приложения OAuth

Ваша интеграция определяется приложением OAuth — сущностью, которая зарегистрирована на нашем сервере и позволяет вашим устройствам авторизоваться в Frame.io с помощью OAuth 2. Ваше приложение OAuth определяет стратегию авторизации для всей интеграции. Каждое устройство, которое ваши пользователи подключают к Frame.io, будет авторизоваться через одно и то же приложение OAuth (хотя интеграторы с несколькими линейками устройств могут настроить отдельное приложение OAuth для каждой линейки).

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

Аутентификация устройства C2C

API-интерфейс C2C разработан для устройств с ограниченными возможностями пользовательского интерфейса. Эти устройства позволяют пользователю подключить их к Frame.io: они показывают пользователю 6-значный код, который он затем вводит на веб-сайте Frame.io в своем браузере.

Устройствам выдается client_secret, который должен быть предоставлен нашему серверу для получения 6-значного кода авторизации. Такой упрощенный подход обеспечивает единообразный и безопасный процесс аутентификации во всех интеграциях C2C.

Модели устройств

Модель устройства определяет поведение вашего устройства при взаимодействии с сервером C2C, включая функции, которые оно поддерживает. Следующие настройки конфигурируются моделью вашего устройства:

Состояние сокета

Будет ли интеграция использовать сокеты с низкой задержкой для передачи текущего состояния или REST-вызовы с более высокой задержкой.

Имя пути

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

Токенизированный путь к файлу

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

Обязательные метаданные

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

Состояние сокета

Будет ли интеграция использовать сокеты с низкой задержкой для передачи текущего состояния или REST-вызовы с более высокой задержкой.

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

Устройства проекта и идентификация

ProjectDevice представляет каждый физический экземпляр устройства, подключенного к Frame.io. ProjectDevice идентифицирует себя, используя уникальное идентификационное значение под названием client_id. В качестве этого значения следует использовать идентификатор, который гарантированно не будет одинаковым у двух устройств. Это может быть серийный номер устройства или случайная строка, которую устройство однажды сгенерировало и сохранило. client_id НЕ должен быть значением, которым ваше устройство не владеет, например MAC-адресом компьютера.

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

Каждое устройство ProjectDevice будет иметь определенный проект Frame.io (Project), связанный с ним, и авторизацию OauthAuthorization, которая предоставляет устройству доступ к проекту и набор областей, определяющих разрешенные устройству действия. Подробнее о том, какие области доступны, см. подробные руководства по аутентификации и авторизации. ProjectDevice — это то, что возвращает конечная точка /me. Устройство может быть одновременно активно связано только с одним ProjectDevice и, следовательно, только с одним Project одновременно.

Версии микропрограммы

Ваше устройство должно предоставлять информацию о текущей версии микропрограммы с помощью HTTP-заголовка x-client-version при каждом вызове конечной точки по адресу https://api.frame.io. Последующие руководства по API-интерфейсу будут включать этот заголовок в каждый пример. В некоторых случаях нашему серверному модулю приходится сортировать разные версии микропрограммы, поэтому НЕОБХОДИМО, чтобы значения представляли собой действительную семантическую версию. Это могут в том числе такие значения, как 0.1.2, 2.1.3-preview.01 и 2.1.3-preview.01+build_19770504.01.

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

Благодаря передаче заголовка различные релизы вашей микропрограммы могут поддерживать разные (иногда даже конфликтующие) функции в Frame.io.

Хост, указанный в заголовке

Версия прошивки обрабатывается только вызовами к https://api.frame.io, при выполнении вызовов к https://applications.frame.io заголовок не имеет никакого эффекта.

Текущее требование

x-client-version теперь является обязательным заголовком HTTP и будет принудительно применяться серверами Frame.

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

Пора выполнить несколько вызовов API-интерфейса! Узнаем, как пройти аутентификацию и авторизацию с помощью C2C. Чтобы начать работу, следуйте указаниям руководства по настройке.