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

Что происходит, когда в вашей экосистеме есть устройства, которые не могут подключиться к интернету и напрямую связаться с Frame.io, но могут взаимодействовать с вашим устройством с поддержкой C2C? Некоторые интеграции могут выполнять действия от имени таких устройств — например, звукозаписывающее устройство, которое добавляет файлы от имени микрофона, или камера, которая оставляет комментарии в реальном времени от имени кнопок, закрепленных на устройстве.

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

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

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

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

Что такое канал?

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

Устройство проекта имеет возможность напрямую взаимодействовать с frame.io. Канал собирает данные для передачи устройством проекта. В большинстве случаев ProjectDevice и первый канал — это одно и то же. Рассмотрим камеру. Концептуально устройство проекта представляет сетевую карту камеры, которая отправляет данные напрямую в Frame.io, в то время как канал представляет датчик CMOS камеры, собирающий видеоданные для отправки через сетевую карту (устройство проекта).

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

Наша модель позволяет устройству проекта иметь несколько каналов, которые могут быть или не быть частью физического устройства. Каналы могут представлять собой аппаратные компоненты, которые связываются с основным устройством по TCP/IP, Bluetooth, SDI и т. д. Устройство проекта выступает в роли маршрутизатора для отправки этих данных в frame.io. То, как данные передаются от каналов к устройству проекта, зависит от вас как от интегратора.

Представьте звукозаписывающее устройство, подключенное к Frame.io как устройство проекта, с множеством микрофонов, каждый из которых подключен как отдельный канал. Записывающее устройство может отправлять комбинированный файл на свой основной канал, а треки отдельных микрофонов — на каналы своих подчиненных устройств. Как использовать каналы и что каждый из них представляет — решать вам! Каналы не требуют аутентификации, устройство может добавлять и удалять их в любое время.

Поскольку каналы могут принадлежать отдельным физическим подчиненным устройствам, каждый канал будет связан с моделью устройства, как и любая другая аппаратная или программная интеграция. Это позволяет frame.io отображать модель подчиненного устройства, которая может отличаться от основного устройства, и позволяет интеграциям определять поведение для каждого подчиненного устройства отдельно. Необходимо заранее определить, какие модели устройств можно добавить к данной интеграции в качестве каналов.

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

• Обеспечить несколько конфигураций для интеграции в зависимости от канала + модели устройства. Это включает фиксированную структуру папок ресурсов, токенизированные пути к папкам, маршрутизацию по расширениям файлов и т. д. Представьте станцию DIT, которая использует разные каналы для добавления монтажных прокси или Camera Raw.
• Это дает пользователю frame.io возможность видеть ваши подчиненные устройства.
• Каналы могут быть настроены с помощью ввода данных человеком (например, кнопок), которые можно настроить для функций ведения журнала в реальном времени.

Узнаем больше о том, как управлять каналами с помощью API-интерфейса C2C.

Список каналов

Список существующих каналов можно получить через конечную точку identity в поле channels. Посмотрите на поле channels в ответе полезной нагрузки:

1
{
2
    "_type": "project_device",
3
    ...
4
    "channels": [
5
        {
6
            "_type": "project_device_channel",
7
            "actor_id": null,
8
            "asset_type": "video",
9
            "device_id": "98e9367a-b26b-4c60-8e64-da83dfd9540b",
10
            "external_index": 0,
11
            "id": "5919e9bc-7fc2-4629-97e5-852ce27cfa1a",
12
            "inserted_at": "2023-07-14T19:11:43.217565Z",
13
            "name": "Test Host Device",
14
            "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
15
            "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
16
            "real_time_logging_capable": false,
17
            "status": "online",
18
            "updated_at": "2023-07-14T19:11:43.217565Z"
19
        },
20
        {
21
            "_type": "project_device_channel",
22
            "actor_id": null,
23
            "asset_type": "video",
24
            "device_id": "057b33c4-9f92-4eeb-a3d5-2fd0f4932292",
25
            "external_index": 0,
26
            "id": "0b17e1e3-588c-4365-be51-5cf097c8f004",
27
            "inserted_at": "2023-07-14T19:11:43.217565Z",
28
            "name": "Test Client Device 01234",
29
            "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
30
            "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
31
            "real_time_logging_capable": false,
32
            "status": "offline",
33
            "updated_at": "2023-07-14T19:11:43.217565Z"
34
        }
35
    ],
36
    ...
37
    "device_id": "98e9367a-b26b-4c60-8e64-da83dfd9540b",
38
    ...
39
    "id": "bf30fc66-f126-4336-bdfc-75d3e659b95am"
40
}

Обратите внимание, что device_id для первого канала соответствует device_id нашего устройства проекта в целом.

Подключение канала

Можно подключить новый канал с помощью следующего запроса:

$
curl -X POST https://api.frame.io/v2/devices/channels/connect \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'Content-Type: application/json' \
>
    --header 'x-client-version: 2.0.0' \
>
    --data-binary @- <<'__JSON__'{
>
            "client_id": [client_id],
>
            "device_model_id": [device_model_id]
>
        }
$
__JSON__
$
    | python -m json.tool

Отображается следующий ответ:

1
{
2
   "_type": "project_device_channel",
3
   "actor_id": null,
4
   "asset_type": "video",
5
   "device_id": "057b33c4-9f92-4eeb-a3d5-2fd0f4932292",
6
   "external_index": 0,
7
   "id": "0b17e1e3-588c-4365-be51-5cf097c8f004",
8
   "inserted_at": "2023-07-14T19:11:43.217565Z",
9
   "name": "Test Client Device 01234",
10
   "project_device_id": "bf30fc66-f126-4336-bdfc-75d3e659b95a",
11
   "project_id": "1eb3587f-6bca-4e8d-a2f6-e7413d82c1ad",
12
   "real_time_logging_capable": true,
13
   "status": "offline",
14
   "updated_at": "2023-07-14T19:11:43.217565Z"
15
}

Этот ответ отражает поле channels из конечной точки identity.

client_id — это то, что определяет уникальность, поэтому это должно быть стабильное значение, например серийный номер.

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

Если канал уже был объявлен, вы получите ошибку 409 с заголовком «Уже существует».

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

Отключение канала

Канал отключается по идентификатору, определенному Frame.io. Не по client_id или device_model_id.

$
curl -X POST https://api.frame.io/v2/devices/channels/:channel_id/disconnect \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'x-client-version: 2.0.0' \
>
    | python -m json.tool

Возвращается ответ 204 с пустой полезной нагрузкой.

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

Отключение всех каналов подчиненных устройств

Можно отключить все текущие каналы подчиненных устройств на устройстве проекта с помощью следующего вызова:

$
curl -X POST https://api.frame.io/v2/devices/channels/disconnect \
>
    --header 'Authorization: Bearer [access_token]' \
>
    --header 'x-client-version: 2.0.0' \
>
    | python -m json.tool

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

Поток управления каналом

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

• Выключение питания после обработки вызова Channel Connect, но до того, как возвращенный ИД может сохраняться в хранилище данных.
• Подключение подчиненных устройств к основному устройству при выключенном устройстве или их отключение.

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

• Вызовите конечную точку Bulk Channel Disconnect для очистки всех существующих каналов подчиненных устройств.
• Вызовите конечную точку Channel Connect для каждого подключенного в данный момент подчиненного устройства.

После первоначальной настройки основного устройства ДОЛЖНО вызывать конечную точку Channel Disconnect при каждом отключении подчиненного устройства и конечную точку Channel Connect при каждом добавлении нового подчиненного устройства. Основным устройствам ЗАПРЕЩАЕТСЯ очищать подчиненные устройства при каждом подключении нового устройства.

Хост-устройства ДОЛЖНЫ корректно обрабатывать плохие сетевые условия при управлении устройствами, а также надлежащим образом добавлять/удалять подключенные в данный момент устройства при восстановлении подключения к сети.

Далее

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