Leitfaden: Kanäle verwalten

Was passiert, wenn Sie Geräte in Ihrem Ökosystem haben, die keine Verbindung zum Internet herstellen und nicht direkt mit Frame.io kommunizieren können, aber mit Ihrem C2C-fähigen Gerät kommunizieren können?Manche Integrationen möchten möglicherweise Aktionen im Namen solcher Geräte ausführen, beispielsweise ein Tonaufzeichnungsgerät, das im Namen eines Mikrofons Daten hochlädt, oder eine Kamera, die im Namen der Schaltflächen eines Anhangs Echtzeitkommentare abgibt.

Diese Anfragen werden durch die Kenntnis der Kanäle eines Geräts erfüllt.Wenn Ihre Integration keine untergeordneten Geräte verwaltet, können Sie diesen Leitfaden überspringen.

Was benötige ich?

Falls Sie den Leitfaden C2C implementieren: Einrichtung noch nicht gelesen haben, werfen Sie bitte einen kurzen Blick darauf, bevor Sie fortfahren!Sie benötigen den access_token, den Sie mit dem Leitfaden zur Authentifizierung und Autorisierung des Geräts erhalten haben.

Außerdem benötigen Sie eine Liste der Gerätemodell-IDs für die untergeordneten Geräte, die sich über Ihr primäres Gerät mit Frame.io verbinden können.

Was ist ein Kanal?

Die Kanäle werden in unserer Architekturübersicht kurz erläutert.Jedes Projektgerät verfügt über mindestens einen Kanal, und obwohl wir diese bisher im Allgemeinen als ein und dasselbe betrachtet haben, müssen wir nun ihre Konzepte voneinander trennen.Lassen Sie uns tiefer einsteigen.

Ein Projektgerät kann direkt mit Frame.io kommunizieren.Ein Kanal erfasst Daten für die Kommunikation mit dem Projektgerät.In den meisten Fällen sind ProjectDevice und der erste Kanal identisch.Betrachten wir einmal eine Kamera: Konzeptionell entspricht das Projektgerät der Netzwerkkarte der Kamera, die Daten direkt an Frame.io sendet, während der Kanal den CMOS-Sensor der Kamera darstellt, der Videodaten erfasst, um sie über die Netzwerkkarte (das Projektgerät) zu übertragen.

Vor allem wird das Projektgerät über eine OauthApp mit Frame authentifiziert, Kanäle hingegen nicht.Sie verwenden die Authentifizierung ihres übergeordneten Projektgeräts.

Unser Modell ermöglicht es einem Projektgerät, mehrere Kanäle zu haben, die Teil des physischen Geräts sein können oder nicht.Kanäle können Hardwarekomponenten sein, die über TCP/IP, Bluetooth, SDI usw. mit dem Hauptgerät kommunizieren. Das Projektgerät fungiert als Router, um diese Daten an Frame.io zu senden.Wie diese Daten von den Kanälen an das Projektgerät bereitgestellt werden, liegt bei Ihnen, dem Integrator.

Stellen Sie sich ein Aufnahmegerät vor, das als Projektgerät mit Frame.io verbunden ist und über viele Mikrofone verfügt, die jeweils als separate Kanäle angeschlossen sind.Das Aufnahmegerät kann die Mix-Datei auf seinem primären Kanal und die Titel einzelner Mikrofone auf den Kanälen des jeweiligen Geräts senden.Wie Sie Kanäle nutzen und was jeder repräsentiert, bleibt Ihnen überlassen.Kanäle werden nicht authentifiziert; sie können jederzeit vom Gerät hinzugefügt und subtrahiert werden.

Da Kanäle zu separaten physischen, untergeordneten Geräten gehören können, wird jeder Kanal wie jede andere Hardware- oder Softwareintegration einem Gerätemodell zugeordnet.Dadurch kann Frame.io das Modell des Untergeräts anzeigen, das sich vom Host-Gerät unterscheiden kann, und Integrationen ermöglichen es, das Verhalten für jedes Untergerät separat zu definieren.Welche Gerätemodelle einer bestimmten Integration als Kanäle hinzugefügt werden können, muss im Voraus definiert werden.

Es gibt einige Gründe, warum Sie neue Kanäle mit Ihrem C2C-Gerät verbinden möchten:

• Lassen Sie je nach Kanal- und Gerätemodell mehrere Konfigurationen für eine Integration zu.Dazu gehörten eine feste Ordnerstruktur für Assets, tokenisierte Ordnerpfade, die Weiterleitung von Dateiendungen usw. Stellen Sie sich eine DIT-Station vor, die verschiedene Kanäle nutzt, um redaktionelle Proxys oder Camera Raw hochzuladen.
• Gibt den Benutzenden in Frame.io Einblick in Ihre untergeordneten Geräte.
• Kanäle können mit manuellen Eingaben, also Schaltflächen, konfiguriert werden, die für Echtzeitprotokollierungsfunktionen eingerichtet werden können.

Sehen wir uns nun genauer an, wie Kanäle mit der C2C-API verwaltet werden.

Kanäle auflisten

Eine Liste der vorhandenen Kanäle kann vom Identitätsendpunkt im Feld „Kanäle“ abgerufen werden.Sehen wir uns nun das Feld "channels" der Antwort-Payload an:

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
}

Beachten Sie, dass die device_id für den ersten Kanal mit der device_id unseres Projektgeräts als Ganzes übereinstimmt.

Kanäle verbinden

Mit der folgenden Anfrage können wir einen neuen Kanal verbinden:

$
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

Wir erhalten folgende Antwort:

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
}

Diese Antwort spiegelt das Kanalfeld des identity-Endpunkts wider.

Die client_id bestimmt die Eindeutigkeit, daher muss sie ein stabiler Wert sein, wie z. B. die Seriennummer.

Die „device_model_id“ teilt Frame.io mit, um welchen Typ von Hardwaregerät es sich bei diesem Kanal handelt, beispielsweise um ein bestimmtes Mikrofonmodell.Diese wurden von Ihrem Partner Manager eingerichtet.

Wenn ein Kanal bereits deklariert wurde, erhalten Sie die Fehlermeldung 409 mit dem Fehlertitel „Already Exists“.

Wenn ein Kanal mit denselben Kennungen wie ein zuvor verbundener und anschließend getrennter Kanal erstellt wird, werden alle früheren Benutzereinstellungen für diesen Kanal wiederhergestellt.

Kanäle trennen

Ein Kanal wurde von der Frame.io-definierten ID getrennt.Nicht durch client_ID oder 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

Dadurch wird eine 204-Antwort mit einer leeren Payload zurückgegeben.

Wenn Sie einen Kanal löschen, der nicht vorhanden ist, erhalten Sie eine 404-Nachricht.Sie können den ersten primären Kanal für das übergeordnete Gerät nicht trennen.

Untergeordnete Gerätekanäle trennen

Sie können alle aktuellen untergeordneten Gerätekanäle auf einem Projektgerät mit dem folgenden Aufruf trennen:

$
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

Dadurch wird eine 204-Antwort mit einer leeren Payload zurückgegeben.Dieser Aufruf wird immer erfolgreich sein, auch wenn das Projektgerät keine Client-Gerätekanäle hat.Über den identity-Endpunkt können wir nun alle unsere Kanäle auflisten; dabei bleibt nur der primäre Kanal des Host-Geräts erhalten.

Kanal-Management-Flow

Es wird nicht empfohlen, den Kanalstatus von ProjectDevice intern zu verwalten, um Datenintegritätsprobleme zu vermeiden, die auf ein Aus- und Einschalten zu weniger als idealen Zeiten zurückzuführen sein könnten.Zum Beispiel:

• Das System wird heruntergefahren, nachdem ein Channel-Connect-Aufruf verarbeitet wurde, jedoch bevor die zurückgegebene id in einem Datenspeicher festgeschrieben werden kann.
• Untergeordnete Geräte, die an das Host-Gerät angeschlossen oder von diesem getrennt werden, während das Gerät ausgeschaltet ist.

Stattdessen wird empfohlen, dass alle Host-Geräte beim ersten Starten die folgenden Schritte ausführen:

• Rufen Sie den Bulk Channel Disconnect-Endpunkt auf, um alle vorhandenen untergeordneten Gerätekanäle zu löschen
• Rufen Sie den Channel Connect-Endpunkt für jedes derzeit verbundene untergeordnete Gerät auf

Nach der Ersteinrichtung MUSS ein Host-Gerät den Endpunkt „Channel Disconnect“ aufrufen, sobald ein untergeordnetes Gerät getrennt wird, und den Endpunkt „Channel Connect“, sobald ein neues untergeordnetes Gerät hinzugefügt wird.Host-Geräte löschen untergeordnete Geräte MÖGLICHERWEISE NICHT jedes Mal, wenn ein neues Gerät angeschlossen wird.

Host-Geräte MÜSSEN bei der Verwaltung von Geräten mit schlechten Netzwerkbedingungen ordnungsgemäß umgehen und aktuell verbundene Geräte nach der Wiederherstellung der Verbindung zum Netzwerk ordnungsgemäß hinzufügen/entfernen.

Als Nächstes

Falls Sie dies noch nicht getan haben, empfehlen wir Ihnen, sich an unser Team zu wenden und anschließend mit dem nächsten Leitfaden fortzufahren.Wir freuen uns darauf, von Ihnen zu hören!