Obsolète

Comment faire : Autoriser (Matériel)

Présentation

Dans ce Guide, nous allons apprendre comment authentifier et autoriser un périphérique matériel Camera to Cloud (C2C) sur un Projet Frame.io. Nous couvrirons à la fois la méthode d’appariement traditionnelle utilisant la saisie manuelle de code et la nouvelle méthode d’appariement par code QR pour une expérience client améliorée.

De quoi ai-je besoin ?

Si vous n’avez pas lu le Guide Avant de commencer la mise en œuvre, jetez-y un coup d’œil rapide avant de continuer ! De plus, vous devriez avoir reçu un client_secret de notre équipe qui sera utilisé pour identifier votre intégration. Si vous n’avez pas reçu de client_secret, veuillez consulter cette présentation du réseau C2C et contactez notre équipe.

Prérequis pour l’appariement par code QR

Avant de commencer avec l’appariement par code QR, assurez-vous que les prérequis suivants sont remplis :

  • Activation d’indicateur de fonctionnalité : Un indicateur de fonctionnalité spécifique (v4.c2c_qr_code_activate) doit être activé dans votre compte Frame.io. Cet indicateur de fonctionnalité permettra l’accès à la méthode d’appairage basée sur le code QR. Votre contact désigné Frame.io peut vous aider à activer cette fonctionnalité pour le compte de votre choix.
  • Compatibilité de la caméra : Assurez-vous que le matériel de votre caméra est mis à jour pour prendre en charge la génération de code QR pendant le processus d’appairage de l’appareil.

Parcourir le flux d’authentification matériel

Assurons-nous d’avoir une compréhension de haut niveau de l’expérience utilisateur attendue pour le flux d’autorisation que nous souhaitons implémenter. Consultez les ressources suivantes pour voir ce flux du point de vue de l’utilisateur :

  • Article d’assistance sur l’ajout de nouveaux équipements matériels.
  • Vidéo de formation sur l’autorisation d’un Teradek cube.

Le flux d’autorisation matériel est conçu pour décharger autant de détails que possible de l’implémenteur, et donc de l’interface utilisateur de l’appareil. Avec ce flux, vous n’avez pas à vous soucier de :

  • Rediriger vers un navigateur web.
  • Gérer la connexion/authentification utilisateur Frame.io.
  • Affichage/sélection du compte et du Projet à connecter.
  • Tout élément d’interface utilisateur au-delà des affichages d’informations de base.

Amélioration de l’expérience utilisateur avec l’appairage par code QR

Avec la demande croissante d’efficacité et de facilité d’utilisation, les utilisateurs s’attendent de plus en plus à des interactions fluides avec leurs appareils. Le processus actuel d’appairage des caméras au service C2C de Frame.io nécessite plusieurs étapes, notamment la saisie manuelle d’un code d’appairage. Bien que fonctionnel, ce processus peut être rationalisé.

En utilisant les codes QR—similaires aux expériences d’appairage d’appareils vues avec les services de streaming comme Netflix ou Disney+—nous pouvons simplifier le processus, éliminer les erreurs causées par la saisie manuelle et réduire le temps nécessaire pour appairer une caméra.

Identification de l’appareil (client_id)

Lors de la connexion à Camera to cloud, chaque appareil matériel physique devra s’identifier de manière unique afin que nous puissions répertorier les connexions d’appareils dans le Projet d’un utilisateur.

Pour les appareils matériels, nous appelons ceci le client_id de l’appareil, selon le modèle d’autorisation que vous choisissez d’utiliser. Lors de la configuration de votre implémentation, vous devez réfléchir à la façon dont vous allez procéder. Vous pouvez utiliser un numéro de série de l’appareil matériel, un UUID ou une chaîne d’identification unique. Veillez à ne pas divulguer d’informations personnellement identifiables. L’e-mail de l’utilisateur, par instance, n’est pas une Valeur valide à utiliser comme client_id.

De même, assurez-vous de posséder l’identifiant unique. Si vous implémentez l’API C2C comme un appareil logiciel, n’utilisez pas l’adresse MAC de l’appareil, par instance. L’adresse MAC n’appartient pas à votre logiciel et pourrait également être considérée comme une information personnellement identifiable.

Si vous n’êtes pas sûr de la Valeur que vous souhaitez utiliser, nous pouvons discuter de ce choix ensemble et nous assurer qu’une Valeur appropriée est choisie qui rend l’intégration aussi facile que possible.

Étape 1 : Demande d’un code d’appareil

Commençons l’implémentation. La première chose que nous devons faire est demander un code d’appareil à donner à l’utilisateur pour un appareil. Nous le faisons en appelant le point d’entrée /v2/auth/device/code :

Méthode d’appairage traditionnelle

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

Activation de l’appairage par code QR

Pour activer l’appairage basé sur le code QR, un changement mineur dans l’appel API est requis. Plus précisément, deux nouveaux en-têtes doivent être ajoutés à la demande de code d’appareil. Cela permet aux appareils de se lier directement à la page d’appariement et de rationaliser le processus d’appariement.

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

Remarque : Nous utilisons ici des données de formulaire plutôt que des données JSON. Les points d’entrée d’authentification C2C acceptent uniquement les données de formulaire. Une fois que vous êtes authentifié, d’autres points d’entrée acceptent les charges utiles JSON, mais les points d’entrée d’authentification renvoient une erreur si des charges utiles JSON sont envoyées.

Paramètres de charge utile

  • client_id : Un identifiant unique pour l’appareil matériel physique. Cette valeur doit être garantie comme étant unique pour l’appareil. Il peut s’agir d’un numéro de série ou d’un UUID généré de manière aléatoire.
  • client_secret : Cette valeur vous sera fournie par l’assistance Frame.io et identifie votre modèle d’appareil. Cette valeur doit rester secrète pour l’utilisateur et doit être chiffrée au repos.
  • scope : Les autorisations que nous demandons, avec des espaces utilisés comme délimiteurs. Les équipements matériels peuvent uniquement demander les deux portées suivantes :
  • asset_create : permet à l’équipement de créer et de charger des assets.
  • offline : permet à l’équipement d’actualiser sa propre autorisation à l’aide d’un jeton d’actualisation. Les jetons d’autorisation expirent au bout de 8 heures. Sans cette portée, un utilisateur devrait donc réautoriser son équipement toutes les 8 heures.

En pratique, les équipements voudront presque toujours demander les deux portées.

Comprendre la réponse de l’API

Lorsque nous effectuons la demande, nous obtenons une réponse similaire à la suivante :

Réponse de couplage traditionnel

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

Réponse de couplage par code 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"
}

Répartition de la réponse

  • device_code : le code d’équipement doit être masqué à l’utilisateur et est utilisé pour identifier cette demande d’autorisation lors de l’interrogation pour vérifier si l’utilisateur a saisi le code avec succès.
  • expires_in : le nombre de secondes avant l’expiration de ce code.
  • interval : la durée que l’utilisateur doit attendre entre les demandes d’interrogation pour vérifier si l’utilisateur a saisi le code.
  • name : nom de l’appareil que nous essayons de connecter.
  • user_code : code à six chiffres que l’utilisateur saisira dans Frame.io pour associer l’appareil à un projet.
  • verification_uri : URL que les utilisateurs saisiront manuellement si le code QR n’est pas scanné.Il doit être concis et facile à retenir.
  • verification_uri_complete : cette URL contient le code d’association et est destinée à la transmission non textuelle (par exemple, le code QR).Une fois scanné, il dirigera automatiquement l’utilisateur vers l’expérience d’association, pour choisir un compte et un projet auxquels connecter son appareil.

Affichage du code QR à l’utilisateur

Maintenant que nous avons le verification_uri_complete, nous pouvons générer un code QR à partir de cette URL et l’afficher à l’utilisateur sur l’écran de l’appareil.Cela permet à l’utilisateur de simplement scanner le code QR avec son appareil mobile ou sa caméra, simplifiant ainsi le processus d’association.

Exemple : écran de caméra avec code QR affiché

Insérez une image ou une illustration d’un écran de caméra affichant le code QR.

Si l’utilisateur ne peut pas scanner le code QR pour une raison quelconque, vous devez également afficher le user_code et verification_uri pour qu’il puisse saisir manuellement le code d’association comme solution de repli.Vous pouvez également afficher le verification_uri sous forme de code QR statique à scanner avec les appareils mobiles.Si votre intégration est une application sur un appareil mobile, afficher le verification_uri_complete sous forme de lien hypertexte sur lequel appuyer est indispensable pour faciliter la connectivité, car l’utilisateur ne peut pas scanner le code QR avec l’appareil sur lequel l’application se trouve.

Étape 2 : vérification de l’autorisation utilisateur

Une fois que nous avons fourni le code d’association ou affiché le code QR à l’utilisateur, nous devons vérifier s’il l’a saisi.Pour ce faire, nous pouvons effectuer la requête suivante :

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

Paramètres de charge utile

  • client_id : même client_id envoyé à l’étape 1.
  • device_code : device_code renvoyé par /v2/auth/device/code.
  • grant_type : type d’octroi d’autorisation que notre système OAuth émet.Cette valeur sera toujours urn:ietf:params:oauth:grant-type:device_code.

Les premières fois que nous effectuons cette requête, nous obtiendrons probablement une réponse comme celle-ci :

{
  "error": "authorization_pending"
}

Mais ne vous inquiétez pas !Il ne s’agit pas d’une erreur fatale.Cela signifie simplement que l’utilisateur n’a pas encore saisi le code utilisateur dans l’interface utilisateur de Frame.io.Il suffit de continuer l’enquête jusqu’à ce qu’il l’ait fait.

Si nous obtenons plutôt une erreur comme celle-ci :

{
  "error": "expired_token"
}

Cela signifie que le code a expiré avant que l’utilisateur puisse le saisir.Dans ce cas, nous devrons générer un nouveau code d’appairage ou code QR en utilisant l’Étape 1, l’afficher à l’utilisateur, puis reprendre l’enquête.

Au final, nous devrons obtenir une réponse comme :

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

Si la charge utile de réponse ressemble à cela : Félicitations !Vous avez autorisé le premier appareil Camera to cloud.Prenez un moment pour célébrer !

Après avoir célébré, examinons cette charge utile de réponse pour nous assurer de bien la comprendre :

  • access_token : Il s’agit de la clé d’accès au reste du backend Frame.io.Nous devrons l’ajouter à l’en-tête du reste des requêtes que nous allons effectuer dans ces tutoriels.
  • expires_in : Le nombre de secondes avant l’expiration du access_token.Une fois le délai du jeton écoulé, il devra être actualisé, ce que nous aborderons dans un prochain tutoriel.
  • refresh_token : Un jeton que nous pouvons utiliser pour gérer notre access_token.Il sera le plus souvent utilisé pour actualiser notre autorisation, mais il peut également servir à la révoquer.
  • token_type : Sera toujours bearer pour l’API C2C et n’est pas exploitable.

Assembler les étapes

Maintenant que nous connaissons les appels à effectuer, assemblons-les dans un pseudocode de type Python.N’oubliez pas qu’il est possible que notre code d’appareil expire, nous devons donc gérer cette possibilité lors de la configuration de notre logique :

Python
1def 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

Remarque : Dans ce pseudocode, nous avons ajouté une boucle externe pour gérer le cas où les codes d’appairage expirent et nous devons en demander de nouveaux.La dernière chose à faire est de récupérer les informations sur le Projet auquel nous nous sommes connectés depuis Frame.io et de les afficher à l’utilisateur pour une couche supplémentaire de confirmation que l’appareil a été appairé au Projet prévu.Nous le montrerons dans le prochain tutoriel.

Résolution des problèmes

Si vous vous retrouvez ici, c’est que quelque chose s’est mal passé ! Qu’est-ce qu’une intégration avec un tiers sans une forme d’erreur ? Cette section répertorie un ensemble de problèmes courants et vous guidera à travers les étapes les plus susceptibles de les résoudre. Parcourez la liste suivante et voyez si quelque chose correspond au problème que vous rencontrez.

Si vous ne trouvez pas de solution ici, nous aimerions connaître le problème que vous avez rencontré afin de pouvoir l’ajouter ici.

  • Je ne vois pas de bouton « Connecter l’appareil » : Si vous accédez au panneau de gestion C2C et ne voyez pas de bouton « Connecter l’appareil », alors l’une des deux situations suivantes se produit :
  • C2C n’est pas activé pour votre compte : Si l’écran est vide et qu’il y a un message indiquant que C2C n’est pas disponible pour votre compte, le gestionnaire de compte doit l’activer pour votre projet dans les paramètres du compte.
  • Vous n’êtes pas gestionnaire d’appareil : Si l’écran est vide et qu’il y a un message concernant l’absence d’autorisations, alors le gestionnaire de compte doit soit modifier les autorisations pour qui est autorisé à connecter des appareils C2C, soit vous ajouter à un rôle qui possède ces autorisations.
  • Vous avez déjà un appareil connecté : Une fois le premier appareil connecté, le grand bouton bleu « Ajouter un nouvel appareil » disparaît, et vous devez plutôt accéder au menu à trois points dans le coin supérieur droit du panneau Connexions C2C.
  • Erreur de client non valide : invalid_client est renvoyé lorsque les informations que vous nous fournissez concernant l’appareil ne correspondent à rien de ce que nous avons dans nos dossiers. Cela signifie très probablement que votre client_secret est incorrect.
  • Erreur de demande incorrecte : bad_request est renvoyé lorsque les données de la demande sont mal formées d’une manière ou d’une autre. Vérifiez que vous n’avez pas mal orthographié un nom de champ ou oublié d’ajouter un champ requis.

À suivre

Si ce n’est pas déjà fait, nous vous encourageons à contacter notre équipe, puis à continuer vers le guide suivant : LINK. Nous avons hâte de vous entendre !

Zone de stationnement

À faire

Ajouter une solution de secours aux partenaires qui ne peuvent pas générer un code QR dynamique

c’est-à-dire leur faire afficher « Accédez à **verification_uri** pour saisir ce code » comme plan de secours