Leitfaden: Status und Zustand verwalten

Einführung

In diesem Leitfaden erfahren Sie, wie Sie den Gerätestatus verwalten und die Synchronisierung mit Frame.io beibehalten.Wir verwenden ein WebSocket-Protokoll, das eine Echtzeitkommunikation zwischen Frame.io und Ihrem Gerät ermöglicht.Falls Sie mit WebSockets noch nicht vertraut sind, hilft Ihnen dieser Leitfaden dabei, deren Umsetzung für C2C-Integrationen zu verstehen.

Dank WebSockets kann Frame.io Nachrichten an Ihr Gerät senden und bietet durch die Aufrechterhaltung einer dauerhaften Verbindung einen effizienteren Kommunikationskanal als herkömmliche HTTP-Anfragen.

In diesem Leitfaden behandeln wir folgende Punkte:

• Eine Socket-Verbindung öffnen, um anzuzeigen, dass Ihr Gerät „online“ ist
• Informationen über die Geräteverbindung abrufen
• Verfügbarkeit von Frame.io-Backend prüfen

Voraussetzungen

Wenn Sie es noch nicht getan haben, lesen Sie bitte den Leitfaden C2C implementieren: Einrichtung, bevor Sie fortfahren.Sie benötigen den access_token, den Sie während des Authentifizierungs- und Autorisierungsprozesses erhalten haben.Bitte beachten Sie, dass Token nach 8 Stunden ablaufen. Daher müssen Sie Ihren Token möglicherweise aktualisieren oder den Autorisierungsvorgang erneut durchlaufen.Für die WebSocket-Verbindungsbeispiele in diesem Leitfaden empfehlen wir die Verwendung von websocat, einem CLI-Tool mit umfassenden Installationsleitfäden für verschiedene Betriebssysteme.

Verbindungsinformationen abrufen

Nach jeder neuen Autorisierung oder Tokenaktualisierung sollte das Gerät sofort den identity-Endpunkt abrufen.Hier finden Sie wichtige Informationen zu Ihrer Verbindung:

$
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

Die Antwort sieht wie folgt aus (einige Daten sind abgekürzt):

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

Dieser Endpunkt hilft bei der Prüfung der Verbindungsdetails.Ihr Gerät sollte Benutzenden diese Informationen anzeigen:

• project.name – Name des verbundenen Projekts

• authorization.creator.name – Person, die das Gerät autorisiert hat

• authorization.expires_at (optional) – Ablaufzeit der Verbindung, falls festgelegt

• status (optional) – Gerätestatus, der wie folgt lauten kann:

• online – Gerät ist online und gekoppelt * offline – Gerät hat seit über 5 Minuten keine Verbindung hergestellt (durch Abfrage dieses Endpunkts wird der Status auf online gesetzt) * paused – Gerät wurde im Frame.io-Fenster „C2C-Verbindungen“ vorübergehend deaktiviert

Da sich der Ablauf- und Pausenstatus in Frame.io jederzeit ändern kann, sollten Sie diese Informationen regelmäßig abrufen, wenn Sie sie den Benutzenden anzeigen.Wir empfehlen, die Abfragehäufigkeit auf höchstens einmal alle 60 Sekunden zu beschränken.

WebSocket-Verbindung herstellen

Der Bereich „C2C-Verbindungen“ in Frame.io zeigt den Verbindungsstatus jedes Geräts an.Wenn ein Gerät über eine aktive Socket-Verbindung verfügt, wird es als online angezeigt, wobei in der oberen linken Ecke der Karte ein grünes Symbol erscheint.Geräte ohne aktive Verbindung werden als offline angezeigt und sind ausgegraut.

Der Server trennt Socket-Verbindungen automatisch, wenn 60 Sekunden lang keine „Heartbeat“-Nachricht empfangen wird.Obwohl dieses Intervall ausreichend ist, empfehlen wir aus Gründen der Zuverlässigkeit, alle 15 Sekunden Heartbeats zu senden.Wenn die Verbindung unerwartet geschlossen wird, stellen Sie sie einfach wieder her.

Die Verbindung zum WebSocket von Frame.io erfolgt in zwei Schritten:

1. Aufbau des TCP/IP-Handshakes und Öffnen der physischen WebSocket-Verbindung
2. Dem gerätespezifischen Kanal beitreten, um Ihr Gerät gegenüber unserem Backend zu identifizieren

So öffnen Sie die WebSocket-Verbindung:

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

Eine erfolgreiche Verbindung gibt den Statuscode 101 zurück, der darauf hinweist, dass das Protokoll auf wss umschaltet.Dies wird möglicherweise automatisch von Ihrer WebSocket-Bibliothek verarbeitet.Ein abgelaufener Token erzeugt eine 403-Antwort.Schließen Sie sich dann dem Kanal Ihres Geräts an, indem Sie diese JSON-Nachricht senden und dabei die id aus Ihren Verbindungsinformationen verwenden:

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

Sie erhalten eine Bestätigung:

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

Überprüfen Sie das C2C-Dashboard – Ihr Gerät sollte jetzt als online angezeigt werden.Wir empfehlen die Implementierung eines Hintergrundprozesses, um diese Verbindung zu erhalten:

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)

Das Format der Heartbeat-Nachricht:

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

So sieht die Antwort darauf aus:

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

Wenn eine aktive Socket-Verbindung und ein Kanalabonnement bestehen, wird Ihr Gerät im Bereich „C2C-Verbindungen“ von Frame.io als online angezeigt.Wenn die Verbindung beendet wird, wird sie als offline angezeigt.

Gerätestatus anzeigen

Anstatt die reinen Statuswerte (online, offline, paused) anzuzeigen, empfehlen wir, diese in aussagekräftigere, für Benutzende verständliche Anzeigen umzuwandeln:

• Paused: true/false – true anzeigen, wenn der Status paused lautet, andernfalls false
• Connected: true/false – zeigt an, ob das Gerät das Frame.io-Backend erreichen kann (siehe Backend-Verbindungstest unten)

Den Status „Paused“ verwalten

Die Anzeige des Status „Pause“ ist optional. Es ist jedoch wichtig, die Funktion zu verstehen.

Mit der „Pause“-Funktion wird das Hochladen sensibler Inhalte vorübergehend blockiert.Sie blockiert nicht den Netzwerkverkehr, verhindert jedoch, dass bestimmte Medien Frame.io erreichen.Dies ist nützlich in Situationen wie beispielsweise beim Drehen von Szenen mit sensiblen Inhalten, in denen eine sofortige Speicherung in der Cloud möglicherweise nicht angebracht ist.

Die Pause wird über die Frame.io-Schnittstelle gesteuert, nicht über Ihre Integration.Wenn ein Gerät angehalten wird, werden nur Medien blockiert, die während der Pause erstellt wurden – zuvor aufgenommene Medien können weiterhin hochgeladen werden.

Wichtige Aspekte:

• Verlassen Sie sich bei der Überprüfung der Upload-Berechtigung nicht ausschließlich auf den „identity“-Endpunkt – unser Backend erledigt dies automatisch
• Socket-Ereignisse benachrichtigen Sie über Statusänderungen mit event: "status_updated" und payload: "paused" oder "resumed"
• Ereignisse können zwar zur Statusverwaltung beitragen, sie können jedoch übersehen oder in falscher Reihenfolge übermittelt werden
• Ein 409-Fehler beim Hochladen bedeutet nicht zwangsläufig, dass das Gerät gerade pausiert ist – er kann darauf hindeuten, dass die Mediendatei während eines früheren Pausenzeitraums erstellt wurde
• Wenn der Status „paused“ angezeigt wird, überprüfen Sie dessen Richtigkeit, indem Sie die Verbindungsdaten regelmäßig kontrollieren

Backend-Konnektivität überprüfen

Um die Verfügbarkeit des Frame.io-Backends zu prüfen, verwenden Sie diesen Endpunkt:

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

Für diesen Endpunkt ist keine Autorisierung erforderlich.Eine erfolgreiche Antwort zeigt die Verbindung an:

1
{
2
    "ok": true
3
}

Diese Konsistenzprüfung ist besonders wertvoll, da sie die Konnektivität speziell mit Frame.io anstelle der allgemeinen Netzwerkverfügbarkeit bestätigt.Es kann Szenarien geben, in denen Ihr Netzwerk funktioniert, aber Frame.io aufgrund von Dienstproblemen oder Routing-Problemen nicht erreichbar ist.

Nächste Schritte

Wir empfehlen Ihnen, sich bei Fragen an unser Team zu wenden und mit dem Leitfaden zu einfachen Uploads fortzufahren.Wir freuen uns darauf, Ihren Integrationsprozess zu unterstützen.Weitere Informationen zur Verwaltung der Geräteautorisierung finden Sie im Leitfaden zur Autorisierungsverwaltung.