Guida pratica: Autorizzazione (hardware) | Frame.io API Documentation

Introduzione

In questa guida imparerai ad autenticare e autorizzare un dispositivo hardware Camera to Cloud (C2C) su un progetto Frame.io. Illustreremo sia il metodo di associazione tradizionale mediante inserimento manuale del codice sia il nuovo metodo di associazione mediante codice QR per migliorare l’esperienza utente.

Cosa serve?

Se non hai letto la guida Prima di iniziare l’implementare, dalle un’occhiata veloce prima di proseguire. Inoltre, dovresti aver ricevuto dal nostro team un client_secret che sarà utilizzato per identificare la tua integrazione. Se non hai ricevuto un client_secret, leggi questa introduzione all’ecosistema C2C e contatta il nostro team.

Prerequisiti per l’associazione mediante codice QR

Prima di iniziare con l’associazione mediante codice QR, assicurati che siano soddisfatti i seguenti prerequisiti:

Attivazione del flag di funzione: un flag di funzione specifico (v4.c2c_qr_code_activate) deve essere abilitato nel tuo account Frame.io. Questo flag di funzione consentirà l’accesso al metodo di associazione basato su codice QR. Il referente designato di Frame.io ti aiuterà ad attivare questa funzione per l’account che scegli.
Compatibilità della fotocamera: assicurati che l’hardware della fotocamera sia aggiornato per supportare la generazione di codici QR durante il processo di associazione del dispositivo.

Guida al flusso di autorizzazione hardware

Assicuriamoci di avere una comprensione generale dell’esperienza utente prevista per il flusso di autorizzazione che vogliamo implementare. Consulta le seguenti risorse per vedere questo flusso dal punto di vista dell’utente:

Articolo dell’assistenza sulla procedura per aggiungere nuovi dispositivi hardware.
Video didattico su come autorizzare un Teradek Cube.

Il flusso di autorizzazione hardware è progettato per alleggerire il più possibile il lavoro di chi esegue l’implementazione e, di conseguenza, l’interfaccia utente del dispositivo. Con questo flusso non dovrai preoccuparti di:

Reindirizzare a un browser.
Gestire l’accesso e l’autenticazione utente a Frame.io.
Elencare e selezionare l’account e il progetto a cui connettersi.
Elementi dell’interfaccia utente oltre alle visualizzazioni di informazioni di base.

Migliorare l’esperienza utente con l’associazione mediante codice QR

Data la crescente richiesta di efficienza e facilità d’uso, gli utenti si aspettano sempre più che le interazioni con i propri dispositivi siano fluide. Il processo attuale per associare le fotocamere al servizio C2C di Frame.io richiede diversi passaggi, incluso l’inserimento manuale di un codice di associazione. Pur essendo funzionale, questo processo può essere semplificato.

Sfruttando i codici QR (un po’ come accade per l’associazione dei dispositivi per servizi di streaming come Netflix o Disney+) possiamo semplificare il processo, eliminare errori causati dall’inserimento manuale e ridurre il tempo necessario per associare una fotocamera.

Identificazione del dispositivo (client_id)

Al momento di connettersi a Camera to Cloud, ogni dispositivo hardware fisico deve identificarsi in modo univoco affinché sia possibile elencare le connessioni dei dispositivi nel progetto di un utente.

Per i dispositivi hardware, questo è il client_id del dispositivo, a seconda del modello di autorizzazione che scegli di utilizzare. Quando configuri l’implementazione, devi pensare a come farlo. Potresti utilizzare un numero di serie del dispositivo hardware, un UUID o una stringa identificativa univoca. Fai attenzione a non divulgare informazioni di identificazione personale. L’e-mail dell’utente, ad esempio, non è un valore valido da utilizzare come client_id.

Allo stesso modo, assicurati di possedere l’identificatore univoco. Se stai implementando l’API C2C come dispositivo software, non utilizzare l’indirizzo MAC del dispositivo, ad esempio. L’indirizzo MAC non è di proprietà del tuo software e potrebbe anche essere considerato un’informazione di identificazione personale.

Se non sei sicuro del valore che vorresti utilizzare, possiamo discutere insieme questa scelta e assicurarci che venga scelto un valore adatto, in grado di semplificare il più possibile l’integrazione.

Passaggio 1: richiedi un codice dispositivo

Iniziamo con l’implementazione. La prima cosa che dobbiamo fare è richiedere un codice dispositivo da fornire all’utente per un dispositivo. Per farlo, occorre chiamare l’endpoint /v2/auth/device/code:

Metodo di associazione tradizionale

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Abilitazione dell’associazione mediante codice QR

Per abilitare l’associazione basata su codice QR, è necessaria una piccola modifica nella chiamata API. In particolare, è necessario aggiungere due nuove intestazioni alla richiesta del codice dispositivo. Ciò consente ai dispositivi di collegarsi direttamente alla pagina di associazione e semplificare il processo di associazione.

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Nota: stiamo utilizzando dati del modulo, invece di dati JSON. Gli endpoint di autenticazione C2C accettano solo dati di modulo. Una volta effettuata l’autenticazione, gli altri endpoint accetteranno i payload JSON, ma gli endpoint di autenticazione restituiranno un errore se vengono inviati payload JSON.

Parametri payload

client_id: un identificatore univoco per il dispositivo hardware fisico. Questo valore deve essere garantito come univoco per il dispositivo. Potrebbe essere un numero di serie o un UUID generato casualmente.
client_secret: verrà rilasciato dall’assistenza Frame.io e identifica il modello del dispositivo. Questo valore non deve essere divulgato all’utente e deve essere crittografato quando non è in uso.
scope: le autorizzazioni che stiamo richiedendo; gli spazi vengono utilizzati come delimitatori. I dispositivi hardware possono richiedere solo i seguenti due ambiti:
asset_create: consente al dispositivo di creare e caricare risorse.
offline: consente al dispositivo di aggiornare la propria autorizzazione utilizzando un token di aggiornamento. I token di autorizzazione scadono dopo 8 ore perciò, senza questo ambito, l’utente dovrebbe autorizzare nuovamente il dispositivo ogni 8 ore.

In pratica, i dispositivi vorranno quasi sempre richiedere entrambi gli ambiti.

Informazioni sulla risposta API

Quando effettuiamo la richiesta, otteniamo una risposta simile alla seguente:

Risposta di associazione tradizionale

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

Risposta di associazione mediante codice QR

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

Spiegazione della risposta

device_code: il codice del dispositivo deve essere nascosto all’utente e serve per identificare questa richiesta di autorizzazione durante il polling per verificare se l’utente ha inserito correttamente il codice.
expires_in: il numero di secondi prima della scadenza di questo codice.
interval: quanto tempo deve attendere l’utente tra le richieste di polling per verificare se ha inserito il codice.
name: il nome del dispositivo che si sta cercando di connettere.
user_code: il codice a sei cifre che l’utente inserirà in Frame.io per associare il dispositivo a un progetto.
verification_uri: questo è l’URL che gli utenti inseriranno manualmente nel caso in cui il codice QR non venga scansionato. Dovrebbe essere conciso e facile da ricordare.
verification_uri_complete: questo URL contiene il codice di associazione ed è destinato alla trasmissione non testuale (ad esempio, il codice QR). Una volta scansionato, indirizza automaticamente l’utente all’esperienza di associazione per scegliere un account e un progetto a cui connettere il dispositivo.

Mostrare il codice QR all’utente

Dopo aver ottenuto verification_uri_complete, è possibile generare un codice QR da questo URL e mostrarlo all’utente sullo schermo del dispositivo. Ciò permette all’utente di scansionare semplicemente il codice QR con il dispositivo mobile o la fotocamera, semplificando il processo di associazione.

Esempio: schermata della fotocamera con codice QR visualizzato

Inserisci l’immagine o l’illustrazione di una schermata della fotocamera che mostra il codice QR.

Se l’utente non può scansionare il codice QR per qualsiasi motivo, occorre mostrare anche user_code e verification_uri in modo che possa inserire manualmente il codice di associazione. In alternativa, puoi anche mostrare verification_uri come codice QR statico che l’utente può scansionare con i dispositivi mobili. Se l’integrazione è un’app su dispositivo mobile, è obbligatorio mostrare verification_uri_complete come link ipertestuale che gli utenti possono toccare per facilitare la connettività, dato che l’utente non può scansionare il codice QR con il dispositivo su cui si trova l’applicazione.

Passaggio 2: polling dell’autorizzazione utente

Una volta consegnato il codice di associazione o aver mostrato il codice QR all’utente, occorre verificare se l’ha inserito. Per farlo, possiamo effettuare la seguente richiesta:

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

Parametri payload

client_id: lo stesso client_id inviato nel passaggio 1.
device_code: il device_code restituito da /v2/auth/device/code.
grant_type: il tipo di concessione dell’autorizzazione che il sistema OAuth sta rilasciando. Questo valore sarà sempre urn:ietf:params:oauth:grant-type:device_code.

Le prime volte che viene effettuata questa richiesta, probabilmente si otterrà una risposta di questo tipo:

{
  "error": "authorization_pending"
}

Non c’è problema! Non si tratta di un errore irreversibile. Significa semplicemente che l’utente non ha ancora inserito il codice utente nella UI di Frame.io. Occorre semplicemente continuare il polling fino a quando non l’ha fatto.

Se, invece, compare un errore come questo:

{
  "error": "expired_token"
}

Significa che il codice è scaduto prima che l’utente potesse inserirlo. In questo caso, occorre generare un nuovo codice di associazione o codice QR utilizzando il passaggio 1, mostrarlo all’utente e quindi riprendere il polling.

Alla fine, la risposta dovrebbe essere questa:

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

Se il payload della risposta ha questo aspetto: complimenti! Hai autorizzato il tuo primo dispositivo Camera to Cloud. È il momento di festeggiare!

Adesso però diamo un’occhiata al payload di risposta per comprenderlo:

access_token: questa è la tua chiave per il resto del backend Frame.io. Dovrà essere aggiunto all’intestazione delle altre richieste che faremo in queste esercitazioni.
expires_in: il numero di secondi fino alla scadenza di access_token. Una volta scaduto il token, dovrà essere aggiornato. Tratteremo questo argomento in un’esercitazione futura.
refresh_token: un token che possiamo utilizzare per gestire il nostro access_token. Verrà utilizzato principalmente per aggiornare l’autorizzazione, ma può anche essere utilizzato per revocarla.
token_type: sarà sempre bearer per l’API C2C e non è operativo.

Abbinamento dei passaggi

Ora che sappiamo quali chiamate che dobbiamo effettuare, uniamole in uno pseudocodice in stile Python. Ricorda: è possibile che il codice del dispositivo scada, quindi occorre gestire questa possibilità quando si configura la logica:

Python

1 def authorize_with_frame():
2     """
3     Handles authorizing our device with Frame.io.
4     """
5 
6     # Our client ID can be a serial number, UUID, or some other unique string.
7     client_id = THIS_DEVICE.get_serial_number()
8 
9     while True:
10         # Make the call to Frame.io to get our device codes.
11         pairing_codes = c2c.get_device_codes(client_id)
12 
13         # We need to keep track of how long we have been polling for
14         polling_started = datetime.now()
15 
16         # Now we are going to poll for authorization until the user enters the code.
17         while True:
18 
19             # Re-write this output each time we poll. Note: This message will only update once
20             # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21             # need a different implementation.
22             print(
23                 f"\rPAIRING CODE: {pairing_codes.user_code}, "
24                 f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25             )
26 
27             # Wait for `interval` before polling each time.
28             sleep(pairing_codes.interval)
29 
30             # Make a call to Frame.io to see if the user has entered the code and authorized
31             # the device.
32             authorization, error = c2c.poll_for_authorization(
33                 client_id, pairing_codes.device_code
34             )
35 
36             if error and error.message == "authorization_pending":
37                 # If the authorization is pending, try again.
38                 continue
39             elif error and error.message == "expired_token":
40                 # If the pairing codes have expired, break to generate new codes.
41                 break
42             elif error:
43                 # If we get another error, we should raise it. (advanced error handling will
44                 # be covered in another tutorial)
45                 raise Exception(error.message)
46 
47             return authorization

Nota: in questo pseudocodice abbiamo aggiunto un ciclo esterno per gestire il caso in cui i codici di abbinamento scadano e dobbiamo richiederne di nuovi. L’ultima cosa che dovremmo fare è recuperare le informazioni sul progetto a cui ci siamo connessi da Frame.io e mostrarle all’utente per confermare ulteriormente che il dispositivo è stato associato al progetto previsto. Vedremo come farlo nell’esercitazione successiva.

Risoluzione dei problemi

Se sei qui, allora qualcosa è andato storto! Cosa sarebbe l’integrazione con una terza parte senza qualche tipo di errore? Questa sezione elenca una serie di problemi comuni e ti guida attraverso i passaggi più probabili per risolverli. Dai un’occhiata all’elenco in basso e controlla se qualcosa corrisponde al problema che stai riscontrando.

Se non trovi una soluzione qui, ci farebbe molto piacere conoscere il problema che hai riscontrato per poterlo aggiungere in questa sezione.

Non vedo un pulsante “Connetti dispositivo”: se vai al pannello di gestione C2C e non vedi un pulsante “Connetti dispositivo”, si sta verificando una di queste due situazioni:
C2C non è attivato per il tuo account: se la schermata è vuota e compare un messaggio che dice che C2C non è disponibile per il tuo account, il gestore dell’account deve attivarlo per il tuo progetto nelle impostazioni dell’account.
Non sei un gestore del dispositivo: se la schermata è vuota e compare un messaggio che dice che non hai le autorizzazioni, il gestore dell’account deve cambiare le autorizzazioni per stabilire chi può connettere i dispositivi C2C oppure aggiungerti a un ruolo che ha quelle autorizzazioni.
Hai già un dispositivo connesso: dopo aver connesso il primo dispositivo, il pulsante blu “Aggiungi nuovo dispositivo” scompare e devi accedere al menu con tre puntini in alto a destra del pannello Connessioni C2C.
Errore di client non valido: viene restituito invalid_client quando le informazioni che ci stai fornendo sul dispositivo non corrispondono a quelle registrate. È molto probabile che il tuo client_secret non sia corretto.
Errore di richiesta non valida: viene restituito bad_request quando i dati della richiesta sono in un formato errato. Controlla di non aver scritto male il nome di un campo o di non aver dimenticato di aggiungere un campo obbligatorio.

Avanti

Se non l’hai già fatto, ti incoraggiamo a contattare il nostro team, poi continua con la guida successiva: LINK. A presto!

Parcheggio

Da fare

Aggiungere una soluzione alternativa ai partner che non possono generare un codice QR dinamico,

ovvero mostra “Vai a **verification_uri** per inserire questo codice” come piano di riserva