Guía práctica: Autorizar (Hardware) | Frame.io API Documentation

Introducción

En esta guía, aprenderemos a autenticar y autorizar un dispositivo de hardware Camera to Cloud (C2C) en un proyecto de Frame.io. Veremos tanto el método de emparejamiento tradicional con la entrada manual de código como el método de emparejamiento nuevo con código QR, que ofrece una experiencia de usuario mejorada.

¿Qué necesitaré?

Si no ha leído la guía Antes de empezar la implementación, échele un vistazo rápido antes de continuar. Además, debería haber recibido un client_secret de nuestro equipo, que se utilizará para identificar su integración. Si no ha recibido un client_secret, consulte esta introducción al ecosistema de C2C y póngase en contacto con nuestro equipo.

Requisitos previos para el emparejamiento con código QR

Antes de comenzar con el emparejamiento con código QR, asegúrese de que se cumplan los siguientes requisitos previos:

Activación del indicador de función: Debe estar habilitado un indicador de función específico (v4.c2c_qr_code_activate) en su cuenta de Frame.io. Este indicador de función permitirá el acceso al método de emparejamiento basado en código QR. Su punto de contacto designado de Frame.io puede ayudarle a activar esta función para la cuenta que elija.
Compatibilidad de la cámara: Asegúrese de que el hardware de su cámara esté actualizado para que sea compatible con la generación de código QR durante el proceso de emparejamiento del dispositivo.

Descripción detallada del flujo de autorización de hardware

Vamos a asegurarnos de que tiene una comprensión de alto nivel de la experiencia del usuario esperada para el flujo de autorización que queremos implementar. Consulte los siguientes recursos para ver este flujo desde el punto de vista del usuario:

Artículo de asistencia sobre cómo añadir dispositivos de hardware nuevos.
Vídeo de formación sobre cómo autorizar un dispositivo Teradek Cube.

El flujo de autorización de hardware está diseñado para realzar tantos detalles como sea posible del implementador y, por lo tanto, de la UI del dispositivo. Con este flujo, no necesita preocuparse por:

Redirigir a un explorador web.
Gestionar el inicio de sesión/autenticación del usuario de Frame.io.
Enumerar/seleccionar la cuenta y el proyecto al que conectarse.
Cualquier elemento de la IU más allá de las pantallas básicas de información.

Mejora de la experiencia del usuario mediante el emparejamiento con código QR

A medida que crece la demanda de eficiencia y facilidad de uso, los usuarios esperan cada vez más interacciones fluidas con sus dispositivos. El proceso actual para emparejar cámaras con el servicio C2C de Frame.io requiere varios pasos, incluida la entrada manual de un código de emparejamiento. Aunque este proceso es funcional, se puede optimizar.

Al usar códigos QR de manera similar a como se usan en las experiencias de emparejamiento de dispositivos de servicios de streaming como Netflix o Disney+, podemos simplificar el proceso, eliminar los errores que pueden producirse por la entrada manual y reducir el tiempo que lleva emparejar una cámara.

Identificación del dispositivo (client_id)

Al conectarse a Camera to Cloud, cada dispositivo de hardware físico deberá identificarse de manera única para que podamos enumerar las conexiones de dispositivos en el proyecto de un usuario.

En el caso de los dispositivos de hardware, llamamos a esto el client_id del dispositivo, dependiendo del patrón de autorización que elija usar. Al configurar su implementación, debe pensar en cómo va a hacer esto. Podría usar un número de serie del dispositivo de hardware, un UUID o alguna cadena de identificación única. Tenga cuidado de no filtrar información de identificación personal. El correo electrónico del usuario, por ejemplo, no es un valor válido para usarse como client_id.

Del mismo modo, asegúrese de que el identificador único es de su propiedad. Si está implementando la API de C2C como un dispositivo de software, no use la dirección MAC del dispositivo, por ejemplo. La dirección MAC no es propiedad de su software y también podría considerarse información de identificación personal.

Si no tiene claro qué valor le gustaría usar, podemos analizar esta elección juntos y asegurarnos de que se elija un valor adecuado que haga que la integración sea lo más fácil posible.

Paso 1: Solicitar un código de dispositivo

Comencemos la implementación. Lo primero que necesitamos hacer es solicitar un código de dispositivo y dárselo al usuario para un dispositivo. Esto lo hacemos llamando al punto final /v2/auth/device/code:

Método de emparejamiento tradicional

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

Habilitación del emparejamiento con código QR

Para habilitar el emparejamiento basado en código QR, se requiere un cambio menor en la llamada API. Específicamente, hay que añadir dos encabezados nuevos a la solicitud de código de dispositivo. Esto permite que los dispositivos se vinculen directamente a la página de emparejamiento y optimizar el proceso de emparejamiento.

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: En este caso estamos usando datos de formulario en lugar de datos JSON. Los puntos finales de autenticación de C2C solo aceptan datos de formulario. Una vez que se haya autenticado, otros puntos finales aceptarán cargas útiles JSON, pero los puntos finales de autenticación devolverán un error si se envían cargas útiles JSON.

Parámetros de carga útil

client_id: Un identificador único para el dispositivo de hardware físico. Es necesario garantizar que este valor sea único para el dispositivo. Puede ser un número de serie o un UUID generado aleatoriamente.
client_secret: Lo emitirá el servicio de asistencia de Frame.io para usted e identifica su modelo de dispositivo. Este valor debe mantenerse en secreto para el usuario y debe cifrarse en reposo.
scope: Los permisos que solicitamos, con el uso de espacios como delimitadores. Los dispositivos de hardware solo pueden solicitar los dos ámbitos siguientes:
asset_create: Permite al dispositivo crear y cargar activos.
offline: Permite al dispositivo actualizar su propia autorización con un token de actualización. Los tokens de autorización caducan después de 8 horas, así que, sin este ámbito, un usuario tendría que volver a autorizar su dispositivo cada 8 horas.

En la práctica, los dispositivos casi siempre querrán solicitar ambos ámbitos.

Comprensión de la respuesta de la API

Cuando hacemos la solicitud, obtendremos una respuesta similar a la siguiente:

Respuesta de emparejamiento tradicional

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

Respuesta de emparejamiento con código 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"
}

Desglose de la respuesta

device_code: El código del dispositivo debe permanecer oculto y se usa para identificar esta solicitud de autorización al hacer sondeos para ver si el usuario ha introducido el código correctamente.
expires_in: El número de segundos hasta que este código caduque.
interval: Cuánto tiempo debe esperar el usuario entre solicitudes de sondeo para ver si el usuario ha introducido el código.
name: El nombre del dispositivo que estamos intentando conectar.
user_code: El código de seis dígitos que el usuario introducirá en Frame.io para emparejar el dispositivo con un proyecto.
verification_uri: Esta es la URL que los usuarios introducirán manualmente en caso de que el código QR no se escanee. Debe ser conciso y fácil de recordar.
verification_uri_complete: Esta URL contiene el código de emparejamiento y está destinada a la transmisión no textual (por ejemplo, el código QR). Al escanearse, dirigirá automáticamente al usuario a la experiencia de emparejamiento para que elija la cuenta y el proyecto a los que desea conectar su dispositivo.

Cómo mostrar el código QR al usuario

Ahora que tenemos el verification_uri_complete, podemos generar un código QR a partir de esta URL y mostrárselo al usuario en la pantalla del dispositivo. Esto permite que el usuario simplemente escanee el código QR con su dispositivo móvil o cámara para optimizar el proceso de emparejamiento.

Ejemplo: Pantalla de la cámara en la que se muestra un código QR

Insertar imagen o ilustración de la pantalla de una cámara en la que se muestra el código QR.

Si el usuario no puede escanear el código QR por algún motivo, también debe mostrar el user_code y el verification_uri para que pueda introducir manualmente el código de emparejamiento como opción de reserva. También puede mostrar el verification_uri como un código QR estático para que el usuario lo escanee con sus dispositivos móviles. Si su integración es una aplicación en un dispositivo móvil, mostrar el verification_uri_complete como un hipervínculo en el que los usuarios pueden pulsar es imprescindible para facilitar la conectividad, ya que el usuario no puede escanear el código QR con el dispositivo en el que está la aplicación.

Paso 2: Sondear para obtener la autorización del usuario

Una vez que hayamos entregado el código de emparejamiento o mostrado el código QR al usuario, necesitamos comprobar si lo han introducido. Para eso, podemos realizar la siguiente solicitud:

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

Parámetros de carga útil

client_id: El mismo client_id enviado en el paso 1.
device_code: El device_code devuelto por /v2/auth/device/code.
grant_type: El tipo de concesión de autorización que está emitiendo nuestro sistema OAuth. Este valor siempre será urn:ietf:params:oauth:grant-type:device_code.

Las primeras veces que realicemos esta solicitud, probablemente obtendremos una respuesta como esta:

{
  "error": "authorization_pending"
}

Pero no se preocupe. Este no es un error grave. Simplemente significa que el usuario aún no ha introducido el código de usuario en la IU de Frame.io. Todo lo que tenemos que hacer es seguir sondeando hasta que lo haya hecho.

En cambio, si obtenemos un error como este:

{
  "error": "expired_token"
}

Esto significa que nuestro código caducó antes de que el usuario pudiera introducirlo. En tal caso, deberíamos generar un código de emparejamiento o código QR nuevo siguiendo el paso 1, mostrárselo al usuario y luego reanudar el sondeo.

Con el tiempo, deberíamos obtener una respuesta como la siguiente:

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

Si la carga útil de su respuesta tiene ese aspecto, enhorabuena. Ha autorizado su primer dispositivo Camera to Cloud. Tómese su tiempo para celebrarlo.

Cuando haya terminado de celebrar su logro, echemos un vistazo a esa carga útil de respuesta para asegurarnos de que la entendemos:

access_token: Esta es su clave para el resto del backend de Frame.io. Tendremos que añadir esto al encabezado del resto de las solicitudes que vamos a hacer en estos tutoriales.
expires_in: El número de segundos hasta que el access_token caduque. Una vez que haya terminado el tiempo de vigencia del token, tendrá que actualizarse. Este proceso lo veremos en un tutorial futuro.
refresh_token: Un token que podemos usar para administrar nuestro access_token. Generalmente, se usará para actualizar nuestra autorización, pero también se puede usar para revocarla.
token_type: Siempre será bearer para la API de C2C y no es procesable.

Unión de todos los pasos

Ahora que conocemos las llamadas que necesitamos hacer, vamos a juntarlas en un pseudocódigo similar a Python. Recuerde que es posible que nuestro código de dispositivo caduque, por lo que tenemos que gestionar esa posibilidad al configurar nuestra lógica:

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: En este pseudocódigo, hemos añadido un bucle externo para gestionar el caso en el que los códigos de emparejamiento caducan y necesitamos solicitar nuevos. Lo último que deberíamos hacer es recuperar la información sobre el proyecto al que nos hemos conectado desde Frame.io y mostrársela al usuario para obtener una capa adicional de confirmación de que el dispositivo se ha emparejado al proyecto previsto. Veremos eso en el próximo tutorial.

Solución de problemas

Si está aquí, es porque algo ha salido mal. Que surja algún error al realizar la integración con un tercero es muy normal. En esta sección aparece un conjunto de problemas comunes y los pasos que debe seguir para resolverlos. Eche un vistazo a la siguiente lista y compruebe si algo coincide con el problema que está experimentando.

Si no encuentra una solución aquí, nos encantaría que nos dijera cuál es el problema que ha tenido para poder añadirlo.

No veo ningún botón “Dispositivo conectado”: Si va al panel de administración de C2C y no ve ningún botón “Dispositivo conectado”, puede que se deba a una de estas dos cosas:
C2C no está habilitado para su cuenta: Si la pantalla está en blanco y hay un mensaje en el que se indica que C2C no está disponible para su cuenta, el administrador de cuentas tiene que habilitarlo para su proyecto en la configuración de la cuenta.
No es un administrador de dispositivos: Si la pantalla está en blanco y hay un mensaje en el que se indica que no tiene los permisos necesarios, entonces el administrador de cuentas tiene que cambiar los permisos para añadir a la persona que puede conectar dispositivos de C2C o añadirle a una función que tenga esos permisos.
Ya tiene un dispositivo conectado: Cuando se conecta el primer dispositivo, el botón azul grande “Añadir dispositivo nuevo” desaparece y tiene que ir al menú de tres puntos situado en la esquina superior derecha del panel Conexiones de C2C.
Error de cliente no válido: La respuesta invalid_client se devuelve cuando la información que nos proporciona sobre el dispositivo no coincide con nada de lo que tenemos registrado. Lo más probable es que su client_secret es incorrecto.
Error de solicitud incorrecta: La respuesta bad_request se devuelve cuando los datos de la solicitud tienen un formato incorrecto. Compruebe que no haya escrito mal el nombre de un campo o que no haya olvidado añadir un campo necesario.

Próximos pasos

Si aún no lo ha hecho, le recomendamos que se ponga en contacto con nuestro equipo y que luego continúe con la siguiente guía: LINK. Quedamos a la espera de tener noticias suyas.

Estacionamiento

Tareas pendientes

Añadir contingencia para socios que no pueden generar un código QR dinámico.

Es decir, que muestren “Vaya al **verification_uri** para introducir este código” como plan de reserva.