Integrationsarchitektur

Einführung

Bevor wir mit der Erstellung von API-Anfragen beginnen, müssen Sie die grundlegende Architektur von C2C-Integrationen kennen.(Keine Sorge – im nächsten Artikel werden Sie im Terminal arbeiten.Im Moment wollen wir uns mit diesen grundlegenden Konzepten befassen.)

Das vereinfachte Datenmodell für Ihre Integration sieht etwa folgendermaßen aus:

                                   ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 01 │ -> │ Project │
┌───────────┐    ┌──────────────┐  └───────────────────┘    └─────────┘
│ Oauth App │ -> │ Device Model │ ──────────⭥
└───────────┘    └──────────────┘  ┌───────────────────┐    ┌─────────┐
                                   │ Project Device 02 │ -> │ Project │
                                   └───────────────────┘    └─────────┘

OAuth-Apps

Ihre Integration wird durch eine OAuth-App definiert, eine bei unserem Backend registrierte Instanz, die es Ihren Geräten ermöglicht, sich mithilfe von OAuth 2 bei Frame.io zu authentifizieren.Ihre OAuth-App definiert die Autorisierungsstrategie für Ihre gesamte Integration.Jedes Gerät, das Ihre Benutzenden mit Frame.io verbinden, wird über dieselbe OAuth-App autorisiert (Integratoren mit mehreren Gerätezeilen benötigen jedoch möglicherweise jeweils eine OAuth-App).

Für C2C-Integrationen verwenden wir einen speziellen OAuth-Workflow, der speziell für Geräte mit eingeschränkten UI-Funktionen entwickelt wurde.

C2C-Geräteauthentifizierung

Die C2C-API wurde für Geräte mit eingeschränkten UI-Funktionen entwickelt.Diese Geräte ermöglichen es Benutzenden, sich mit Frame.io zu verbinden, indem ein 6-stelliger Code angezeigt wird, den der Benutzende dann über seinen eigenen Browser auf der Frame.io-Website eingibt.

Geräte erhalten ein client_secret, das an unser Backend bereitgestellt werden muss, um einen 6-stelligen Autorisierungscode zu erhalten.Dieser optimierte Ansatz sorgt für eine konsistente und sichere Authentifizierung über alle C2C-Integrationen hinweg.

Gerätemodelle

Das Gerätemodell konfiguriert, wie sich Ihr Gerät bei der Interaktion mit dem C2C-Backend verhält, einschließlich der unterstützten Funktionen.Die folgenden Einstellungen werden vom Gerätemodell konfiguriert:

Die von Ihrem Gerät unterstützten Funktionen können sich über verschiedene Firmware-Versionen hinweg ändern.Um Abwärtskompatibilität und ein sauberes Benutzererlebnis zu ermöglichen, wird die Konfiguration für Ihr Gerät dynamisch basierend auf der erkannten Firmware-Version ausgewählt.In naher Zukunft wird eine Integration mehr als ein Gerätemodell haben.Welches Gerätemodell verwendet wird, wird durch einen Vergleich der Firmware-Version des Geräts mit der Mindestanforderung an die Firmware-Version für ein bestimmtes Gerätemodell ermittelt.

Projektgeräte und Kennzeichnung

Das ProjectDevice stellt jede physische Instanz eines Geräts dar, das mit Frame.io verbunden ist.Ein ProjectDevice identifiziert sich anhand eines eindeutigen Identifikationswerts namens client_id.Dieser Wert sollte so gewählt werden, dass er garantiert nicht von zwei Geräten gemeinsam genutzt wird.Es kann sich um die Seriennummer eines Geräts handeln oder um eine zufällige Zeichenfolge, die das Gerät einmalig generiert und gespeichert hat.Die client_id sollte KEIN Wert sein, über den Ihr Gerät nicht verfügt, wie beispielsweise die MAC-Adresse eines Computers.

Unser Backend erfasst jedes Projektgerät und speichert Informationen dazu, wie beispielsweise die aktuelle Firmware-Version.

Jedem ProjectDevice ist ein bestimmtes Frame.io-Project und eine OauthAuthorization zugeordnet, die dem Gerät Zugriff auf das Projekt gewährt, sowie eine Reihe von Gültigkeitsbereichen, die genau beschreiben, was ein Gerät tun darf.Weitere Informationen zu den verfügbaren Gültigkeitsbereichen finden Sie in den detaillierten Leitfäden zur Implementierung von Authentifizierung und Autorisierung.Das ProjectDevice wird vom /me--Endpunkt zurückgegeben.Ein Device kann jeweils nur mit einem einzelnen ProjectDevice und somit gleichzeitig nur mit einem einzelnen Project verknüpft werden.

Firmware-Versionen

Ihr Gerät muss bei jedem Aufruf eines Endpunkts unter https://api.frame.io die aktuelle Firmware-Version im HTTP-Header x-client-version angeben.Spätere API-Leitfäden enthalten diesen Header in jedem Beispiel.In einigen Fällen muss unser Backend mehrere Firmware-Versionen sortieren. Um dies zu unterstützen, MÜSSEN die Werte eine gültige semantische Version sein.Dazu gehören (unter anderem) Werte wie 0.1.2, 2.1.3-preview.01 und 2.1.3-preview.01+build_19770504.01.

Es wird ein Fehler zurückgegeben, wenn die Werte der Firmware-Version keine gültigen semantischen Versionen sind.Uns ist bewusst, dass nicht alle Integrationen ihre Firmware nach dem Prinzip der semantischen Versionierung verwalten. In solchen Fällen bitten wir Sie, für jede von Ihnen erstellte interne Version eine semantische Versionsnummer zu vergeben und diese an unser Backend zu übermitteln.

Durch die Bereitstellung des Headers können verschiedene Versionen Ihrer Firmware unterschiedliche (und manchmal miteinander in Konflikt stehende) Funktionen innerhalb von Frame.io unterstützen.

Nächste Schritte

Es ist Zeit für API-Aufrufe.Erfahren Sie, wie Sie sich mit C2C authentifizieren und autorisieren können.Folgen Sie dem Leitfaden zur Einrichtung, um zu beginnen.