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

Введение

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

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

В этом руководстве мы рассмотрим:

Открытие сокет-подключения для указания того, что ваше устройство находится в сети.
Получение информации о подключении вашего устройства
Проверка доступности сервера Frame.io

Требования

Если вы еще не сделали этого, просмотрите руководство Реализация C2C: настройка перед продолжением. Вам понадобится access_token, полученный в процессе аутентификации и авторизации. Помните, что срок действия токенов истекает через 8 часов, поэтому вам может потребоваться обновить токен или снова пройти процесс авторизации. Для примеров подключения Websocket в этом руководстве мы рекомендуем использовать websocat — инструмент CLI с подробными инструкциями по установке для различных операционных систем.

MacOS

Установите с помощью: brew install websocat

Получение информации о подключении

После любой новой авторизации или обновления токена ваше устройство должно немедленно запросить конечную точку identity. Это предоставляет важную информацию о вашем подключении:

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

Ответ будет похож на этот (с некоторыми сокращенными данными):

{
    "_type": "project_device",
    "id": "a7e95254-8cd6-4d59-b54d-28c58570a8de",
    "asset_type": "video",
    "authorization": {
        "_type": "project_device_authorization",
        "creator": {
            "_type": "user",
            "id": "e7e96254-8bd6-4d59-b54d-28c58570a8de",
            "name": "Harry Potter"
        },
        "expires_at": null,
        "id": "7b2b68e5-788d-497c-8597-f9362cb1a75e",
        ...
        "project_device_id": "14856308-46e0-4d7d-8438-320262eec74e",
        "scopes": {
            ...
            "asset_create": true,
            ...
            "id": "0fe0accb-447f-44f6-b2af-177d913b3a29",
            "offline": true,
            ...
        }
    },
    ...
    "name": "Frameio-BPEAKE-TEST-DEVICE",
    "project": {
        "_type": "project",
        "id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
        "name": "Testbed"
    },
    "project_id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3",
    "status": "online",
    ...
}

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

project.name — имя подключенного проекта.
authorization.creator.name — пользователь, который авторизовал устройство.
authorization.expires_at (необязательно) — время истечения подключения, если установлено.
status (необязательно) — состояние устройства, которое может быть:
онлайн — устройство онлайн и сопряжено * офлайн — устройство не отвечало более 5 минут (запрос к этой конечной точке изменит состояние на онлайн) * приостановлено — устройство временно отключено на панели подключений C2C в Frame.io.

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

ИД

Запомните значение ИД, поскольку оно понадобится для подключения Websocket в следующем разделе.

Установка подключения Websocket

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

Сервер автоматически завершает сокет-подключения через 60 секунд без сообщения «heartbeat». Хотя этого интервала достаточно, рекомендуется отправлять heartbeats каждые 15 секунд для надежности. Если подключение неожиданно закрывается, просто установите его заново.

Подключение к Websocket через Frame.io включает два этапа:

Установление рукопожатия TCP/IP и открытие физического подключения Websocket
Подключение к специальному каналу устройства для идентификации вашего устройства в нашей серверной части

Чтобы открыть подключение Websocket:

$ websocat -n "wss://api.frame.io/devices/websocket?Authorization=Bearer ACCESS_TOKEN"

Заголовок авторизации

В отличие от стандартных конечных точек API-интерфейса, где токен доступа передается в заголовке Authorization, для подключений Websocket он указывается как URL-кодированный параметр запроса. Обратите внимание, что вы по-прежнему должны включать Bearer (с пробелом) перед вашим токеном доступа. В строках с URL-кодировкой пробелы отображаются как %20, поэтому такое форматирование ожидаемо.

Успешное подключение возвращает код состояния 101, указывающий на переключение протокола на wss. Ваша библиотека Websocket может обрабатывать это автоматически. Токен с истекшим сроком действия выдаст ответ 403. Затем подключитесь к каналу вашего устройства, отправив это сообщение JSON, используя id из информации о подключении:

1 {"topic":"devices:YOUR_DEVICE_ID", "event":"phx_join", "payload":"", "ref":"channel_connect"}

Вы получите подтверждение:

1 {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"channel_connect","topic":"devices:YOUR_DEVICE_ID"}

Поля ref и payload

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

Проверьте панель управления C2C — теперь ваше устройство должно отображаться онлайн! Мы рекомендуем реализовать фоновый процесс для поддержания этого подключения:

Python

1 def heartbeat_task():
2     """
3     Task that emits heartbeats every 15 seconds.
4     """
5 
6     while True:
7         c2c.emit_socket_heartbeat()
8         sleep(15)

Формат сообщения heartbeat:

1 {"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"}

Которое получает этот ответ:

1 {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"heartbeat","topic":"phoenix"}

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

Отображение состояния устройства

Вместо отображения необработанных значений состояния (онлайн, офлайн, приостановлено) мы рекомендуем преобразовывать их в более понятные пользователю индикаторы:

Приостановлено: true/false — показывать true, если состояние приостановлено, в противном случае false.
Подключено: true/false — указывает, может ли устройство подключиться к серверу Frame.io (см. тестирование подключения к серверу ниже)

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

Хотя отображение состояния приостановки необязательно, важно понимать его функцию.

Функция приостановки предназначена для временной блокировки добавления конфиденциального контента. Она не блокирует сетевой трафик, но предотвращает попадание определенных медиафайлов в Frame.io. Это полезно в таких ситуациях, как съемка сцен с конфиденциальным материалом, где мгновенное добавление в облачное хранилище может быть неуместным.

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

Важные сведения

Не полагайтесь исключительно на конечную точку идентификации для проверки права на добавление — наш сервер обрабатывает это автоматически.
События сокета будут уведомлять вас об изменениях состояния с помощью event: "status_updated" и payload: "paused" или "resumed"
Хотя события могут помочь управлять состоянием, они могут быть пропущены или доставлены не в том порядке
Получение ошибки 409 во время добавления не обязательно означает, что устройство в данный момент приостановлено — это может указывать на то, что медиафайл создан во время предыдущего окна приостановки.
Если отображается состояние приостановки, проверьте его точность, периодически проверяя информацию о подключении.

Проверка подключения к серверу

Чтобы проверить доступность сервера Frame.io, используйте эту конечную точку:

$ curl -X GET https://api.frame.io/health \
>     | python -m json.tool

Эта конечная точка не требует авторизации. Ответ указывает на подключение:

1 {
2     "ok": true
3 }

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

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

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