Instruções: Gerenciar status e estado | Frame.io API Documentation

Introdução

Este guia explica como gerenciar o status do dispositivo e manter a sincronização com o Frame.io. Utilizamos um protocolo WebSocket que permite a comunicação em tempo real entre o Frame.io e o seu dispositivo. Se você não estiver familiarizado com WebSockets, este guia o ajudará a entender sua implementação para integrações C2C.

Os WebSockets permitem que o Frame.io envie mensagens para o seu dispositivo e, ao manter uma conexão persistente, proporcionam um canal de comunicação mais eficiente do que as solicitações HTTP tradicionais.

Neste guia, abordaremos:

Como abrir uma conexão de socket para indicar que seu dispositivo está ‘online’
Como recuperar informações sobre a conexão do seu dispositivo
Como verificar a disponibilidade do back-end do Frame.io

Pré-requisitos

Caso ainda não tenha feito isso, revise o guia Implementação do C2C: Configuração antes de prosseguir. Você precisará do access_token obtido durante o processo de autenticação e autorização. Lembre-se de que os tokens expiram após 8 horas. Portanto, talvez seja necessário atualizar seu token ou passar pelo processo de autorização novamente. Para os exemplos de conexão via WebSocket deste guia, recomendamos o uso do websocat, uma ferramenta de linha de comando (CLI) com instruções de instalação completas para diversos sistemas operacionais.

MacOS

Instale com: brew install websocat

Recuperar informações de conexão

Após qualquer nova autorização ou atualização do token, seu dispositivo deve consultar imediatamente o ponto de acesso identity. Isso fornece informações essenciais sobre sua conexão:

$ 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

A resposta será semelhante a esta (com alguns dados abreviados):

{
    "_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",
    ...
}

Esse ponto de acesso ajuda a verificar os detalhes da conexão. Seu dispositivo deve exibir essas informações aos usuários:

project.name – o nome do projeto conectado
authorization.creator.name – o usuário que autorizou o dispositivo
authorization.expires_at (opcional) – hora de expiração da conexão, se definida
status (opcional) – status do dispositivo, que pode ser:
online – o dispositivo está conectado e emparelhado * offline – o dispositivo não se comunica há mais de 5 minutos (ao consultar este ponto de acesso, o status será alterado para online) * paused – o dispositivo foi desativado temporariamente no painel Conexões C2C do Frame.io

Como o status de validade e de pausa pode mudar a qualquer momento no Frame.io, considere consultar essas informações periodicamente caso as exiba aos usuários. Recomendamos limitar a frequência de consulta a no máximo uma vez a cada 60 segundos.

id

Anote o valor do id, pois você precisará dele para a conexão via WebSocket na próxima seção

Estabelecer a conexão via WebSocket

O painel Conexões C2C no Frame.io exibe o status de conexão de cada dispositivo. Quando um dispositivo possui uma conexão de socket ativa, ele aparece como online com um indicador verde no canto superior esquerdo do cartão. Dispositivos sem conexões ativas aparecem como offline com a exibição em cinza.

O servidor encerra automaticamente as conexões de socket após 60 segundos sem uma mensagem de “heartbeat”. Embora esse intervalo seja suficiente, recomendamos enviar heartbeats a cada 15 segundos para garantir a confiabilidade. Se a conexão for encerrada inesperadamente, basta restabelecê-la.

A conexão com o WebSocket do Frame.io envolve duas etapas:

Estabelecer o handshake TCP/IP e abrir a conexão física do WebSocket
Entrar no canal específico do dispositivo para identificá-lo em nosso back-end

Para abrir a conexão do WebSocket:

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

O cabeçalho de autorização

Ao contrário dos pontos de acesso API padrão, nos quais o token de acesso é inserido no cabeçalho Authorization, nas conexões WebSocket ele é incluído como um parâmetro de consulta codificado por URL. Observe que você ainda deve incluir Bearer (com um espaço) antes do seu token de acesso. Em strings codificadas por URL, os espaços aparecem como %20, portanto, essa formatação é esperada.

Uma conexão bem-sucedida retorna um código de status 101, indicando a mudança do protocolo para wss. Sua biblioteca de WebSocket pode lidar com isso automaticamente Um token expirado gerará uma resposta 403. Em seguida, entre no canal do seu dispositivo enviando esta mensagem JSON, usando o id das suas informações de conexão:

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

Você receberá uma confirmação:

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

Os campos ref e payload

O campo ref correlaciona as respostas com os eventos que as iniciaram. Como a ordem dos eventos não é garantida, esse identificador ajuda a associar as respostas do servidor aos eventos que as acionaram. O Frame.io não usa esse campo para eventos recebidos. Ele serve exclusivamente como referência para o cliente. O campo payload deve estar sempre presente, mas muitas vezes pode ser uma string em branco (especificaremos quando um payload exigir conteúdo específico).

Verifique o painel do C2C. Seu dispositivo já deve estar aparecendo como online! Recomendamos implementar um processo em segundo plano para manter essa conexão:

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)

O formato da mensagem de heartbeat:

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

Que recebe esta resposta:

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

Com uma conexão de socket ativa e uma assinatura de canal, seu dispositivo aparecerá como online no painel Conexões C2C do Frame.io. Quando a conexão for encerrada, ele aparecerá como offline.

Exibir status do dispositivo

Em vez de exibir os valores brutos de status (online, offline, paused), recomendamos traduzi-los em indicadores mais significativos para o usuário:

Paused: true/false – exibe true se o status for paused, caso contrário false
Connected: true/false – indica se o dispositivo consegue se conectar ao back-end do Frame.io (consulte o teste de conexão com o back-end abaixo)

Gerenciar o status pausado

Embora a exibição do status de pausa seja opcional, é importante compreender sua função.

O recurso de pausa foi projetado para bloquear temporariamente o envio de conteúdo sensível. Ele não bloqueia o tráfego de rede, mas impede que mídias específicas cheguem ao Frame.io. Isso é útil em situações como a filmagem de cenas que contenham material sensível, nas quais o armazenamento imediato na nuvem pode ser inadequado.

A pausa é controlada por meio da interface do Frame.io, e não por meio da sua integração. Quando um dispositivo está em pausa, apenas os arquivos de mídia criados durante o período de pausa são bloqueados. Os arquivos capturados anteriormente continuam aptos para upload.

Considerações importantes:

Não confie exclusivamente no ponto de acesso de identidade para validar a elegibilidade do upload. Nosso back-end lida com isso automaticamente
Os eventos do socket notificam você sobre mudanças de status com event: "status_updated" e payload: "paused" ou "resumed"
Embora os eventos possam ajudar a gerenciar o status, eles podem ser perdidos ou entregues fora de ordem
Receber um erro 409 durante o upload não significa necessariamente que o dispositivo esteja pausado no momento. Isso pode indicar que a mídia foi criada durante um período de pausa anterior
Se for exibido um status de pausa, verifique se ele está correto, conferindo periodicamente as informações de conexão

Verificar a conectividade do back-end

Para verificar a disponibilidade do back-end do Frame.io, use este ponto de acesso:

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

Este ponto de acesso não requer autorização. Uma resposta bem-sucedida indica conectividade:

1 {
2     "ok": true
3 }

Essa verificação de integridade é particularmente valiosa, pois confirma a conectividade especificamente com o Frame.io, em vez da disponibilidade geral da rede. Pode haver cenários em que sua rede funcione, mas o Frame.io esteja inacessível devido a problemas de serviço ou de roteamento.

Próximas etapas

Recomendamos que você entre em contato com nossa equipe caso tenha alguma dúvida e consulte o guia básico de upload. Esperamos poder apoiar o andamento da sua integração. Para obter mais informações sobre como gerenciar a autorização de dispositivos, consulte o guia de gerenciamento de autorização.