Architettura di integrazione
Introduzione
Prima di iniziare a fare delle richieste API, devi comprendere l’architettura di base delle integrazioni C2C. Non preoccuparti: nel prossimo articolo lavorerai nel terminale. Per ora, esaminiamo questi concetti essenziali.
Il modello dati semplificato per l’integrazione sarà simile a questo:
App OAuth
L’integrazione è definita da un’app OAuth, ovvero un’entità registrata con il nostro backend che consente ai dispositivi di autorizzarsi con Frame.io utilizzando OAuth 2. L’app OAuth definisce la strategia di autorizzazione per l’intera integrazione. Ogni dispositivo che gli utenti connettono a Frame.io viene autorizzato tramite la stessa app OAuth (anche se gli integratori con più linee di dispositivi potrebbero voler usare una singola app OAuth per ogni linea).
Per le integrazioni C2C, utilizziamo un flusso OAuth specializzato e progettato specificatamente per dispositivi con capacità di interfaccia utente limitate.
Autenticazione per dispositivi C2C
L’API C2C è progettata per dispositivi con capacità di interfaccia utente limitate. Questi dispositivi consentono a un utente di connetterli a Frame.io mediante la visualizzazione di un codice a 6 cifre, che l’utente inserisce poi sul sito web Frame.io utilizzando il proprio browser.
Ai dispositivi viene rilasciato un client_secret che deve essere fornito al nostro backend per ricevere un codice di autorizzazione a 6 cifre. Questo approccio semplificato garantisce un’esperienza di autenticazione coerente e sicura in tutte le integrazioni C2C.
Modelli di dispositivo
Il modello di dispositivo configura il comportamento del dispositivo durante l’interazione con il backend C2C, incluse le funzionalità supportate. Le seguenti impostazioni sono configurate dal modello di dispositivo:
Indica se l’integrazione utilizza dei socket a bassa latenza per comunicare il proprio stato corrente oppure delle chiamate REST con latenza superiore.
Il nome dell’integrazione come deve apparire nel percorso di qualsiasi risorsa caricata.
C2C consente di caricare risorse solo in percorsi file root specifici, ma al di sotto di questo requisito il dispositivo può essere configurato per caricare risorse in un percorso file calcolato dinamicamente in base ai metadati forniti della risorsa.
Indica quali metadati saranno obbligatori quando carichi una risorsa su Frame.io, soprattutto per supportare il percorso file tokenizzato.
Indica se l’integrazione utilizza dei socket a bassa latenza per comunicare il proprio stato corrente oppure delle chiamate REST con latenza superiore.
Le funzionalità supportate dal dispositivo possono cambiare nelle diverse versioni del firmware. Per abilitare la compatibilità con le versioni precedenti e offrire un’esperienza utente fluida, la configurazione del dispositivo viene selezionata dinamicamente in base alla versione del firmware rilevata. Nel prossimo futuro, un’integrazione potrà avere più di un DeviceModel. Il modello di dispositivo da utilizzare verrà determinato confrontando la versione del firmware del dispositivo con il requisito della versione minima del firmware di un modello di dispositivo specifico.
Dispositivi di progetto e identificazione
Il ProjectDevice rappresenta ogni istanza fisica di un dispositivo collegato a Frame.io. Un ProjectDevice si identifica utilizzando un valore di identificazione univoco chiamato client_id. Questo valore dovrebbe essere qualcosa che sicuramente non verrà condiviso tra due dispositivi. Può essere il numero di serie di un dispositivo o una stringa casuale che il dispositivo ha generato una volta e ha poi salvato. Il client_id NON dovrebbe essere un valore che il tuo dispositivo non possiede, come l’indirizzo MAC di un computer.
Il nostro backend tiene traccia di ogni dispositivo di progetto e salva le rispettive informazioni, come la versione del firmware attuale.
A ogni ProjectDevice sarà associato un project Frame.io specifico e un’OauthAuthorization che concede al dispositivo accesso al progetto e un insieme di ambiti che dettagliano cosa un dispositivo può fare. Per maggiori informazioni sugli ambiti disponibili, consulta le guide dettagliate sull’implementazione dell’autenticazione e dell’autorizzazione. Il ProjectDevice è il valore che viene restituito dall’endpoint /me. Un dispositivo può essere collegato attivamente solo a un singolo ProjectDevice alla volta, perciò a un singolo progetto alla volta.
Versioni firmware
Il tuo dispositivo deve fornire la sua versione firmware attuale con l’intestazione HTTP x-client-version ogni volta che chiami un endpoint su https://api.frame.io. Le prossime guide API includeranno questa intestazione in ogni esempio. In alcuni casi, il nostro backend deve ordinare più versioni firmware. Per farlo, richiediamo che i valori siano OBBLIGATORIAMENTE una versione semantica valida. Tra gli altri, sono inclusi valori come 0.1.2, 2.1.3-preview.01 e 2.1.3-preview.01+build_19770504.01.
Viene restituito un errore se i valori della versione del firmware non sono versioni semantiche valide. Comprendiamo che non tutte le integrazioni tengono traccia del firmware utilizzando il controllo delle versioni semantico e, in questi casi, chiediamo di tenere traccia di una versione semantica da fornire al nostro backend per ogni versione interna che viene creata.
Fornendo l’intestazione, release diverse del firmware possono supportare funzionalità diverse (e talvolta contrastanti) all’interno di Frame.io.
Host di intestazione
La versione del firmware viene gestita solo dalle chiamate a https://api.frame.io; quando si effettuano chiamate a https://applications.frame.io, l’intestazione non ha alcun effetto.
Requisito attuale
L’intestazione HTTP x-client-version è ora obbligatoria e verrà applicata dai server di Frame.
Passaggi successivi
È il momento di effettuare alcune chiamate API! Scopriamo come eseguire l’autenticazione e l’autorizzazione con C2C. Segui la guida di configurazione per iniziare.