Actions personnalisées version bêta

Les actions Frame.io permettent d’accéder rapidement aux opérations courantes sur les médias, telles que le téléchargement, le renommage et la duplication d’éléments. Elles permettent également d’intégrer des outils et services tiers directement dans l’interface utilisateur de Frame.io.

À propos des actions

Grâce à l’introduction des actions personnalisées (en version bêta), les développeurs peuvent configurer et gérer leurs propres actions dans Frame.io V4. S’appuyant sur le même système d’événements sous-jacent que les webhooks, les actions personnalisées constituent un autre moyen pour les développeurs de relier leurs ressources aux outils les plus importants pour les utilisateurs de leur compte Frame.io.

Les actions peuvent être exécutées par tout utilisateur membre de l’espace de travail Frame.io dans lequel l’action est activée. Lorsqu’une action est exécutée, Frame.io envoie une payload à l’URL que vous indiquez. L’application destinataire répond par un code d’état HTTP pour accuser réception, ou par un rappel personnalisé afin d’afficher des champs de formulaire supplémentaires dans l’interface utilisateur de Frame.io. L’application destinataire peut être votre propre programme hébergé, un service, ou même un outil IPaaS de type low-code ou no-code comme Workfront Fusion ou Zapier.

Utilisez la version bêta des actions personnalisées pour créer des intégrations directement dans Frame.io sous forme de composants d’interface utilisateur programmables. Cela permet de mettre en place des workflows pouvant être déclenchés par les utilisateurs au sein de l’application, en s’appuyant sur le même système de routage des événements que les webhooks. Vous pouvez créer des formulaires à une ou plusieurs étapes, déclenchés par l’utilisateur, qui renvoient vers Frame.io sous la forme d’un autre formulaire ou d’une réponse simple. Et lorsqu’un utilisateur clique sur une action personnalisée associée à un élément, Frame.io envoie une payload à l’URL que vous avez indiquée. L’application destinataire renvoie un code d’état HTTP pour accuser réception, ou renvoie un rappel personnalisé permettant d’afficher une interface utilisateur supplémentaire dans Frame.io.

Améliorations apportées aux actions dans la version 4

En nous appuyant sur les retours d’expérience des utilisateurs de notre version héritée, nous avons intégré plusieurs améliorations à l’ensemble des fonctionnalités Actions de Frame.io V4 :

Actions migrées

Il y a quelques points à garder à l’esprit lors de la migration vers un compte Frame.io V4 contenant des actions personnalisées créées précédemment, dans la version héritée de Frame.io.

Statut de l’action

Lors de la migration du compte vers Frame.io V4, toutes les actions personnalisées créées dans les versions antérieures auront le statut « null » et seront automatiquement désactivées. Cela permet aux utilisateurs de mettre d’abord à jour leurs actions afin d’utiliser l’API V4 avant de les activer, car toute action non mise à jour ne fonctionnera pas. Pour identifier les actions ayant ce statut, rendez-vous sur la page des paramètres des actions et consultez la colonne « Statut » ou, si vous utilisez l’API, vérifiez le champ is_active.

Ressources pratiques : fichiers, dossiers et piles de versions

Étant donné que les différents types d’éléments sont traités comme des ressources distinctes dans l’API Frame.io V4, il convient de tenir compte de certains comportements lors de l’interprétation de l’identifiant de ressource reçu dans la payload de votre action. Le fonctionnement pour les fichiers individuels est simple, car l’identifiant correspond au fichier sur lequel l’action a été exécutée. De même, pour les dossiers, vous recevez l’identifiant du dossier sur lequel l’action a été exécutée ; toutefois, selon votre cas d’utilisation, plusieurs options s’offrent à vous pour définir le comportement de votre action. Utilisez l’ID du dossier pour effectuer des appels ultérieurs à l’API Frame.io si vous souhaitez interagir avec la ressource Dossier elle-même. Vous pouvez également récupérer les sous-dossiers de ce dossier afin d’effectuer d’autres opérations sur les ressources qu’ils contiennent. Lorsqu’une action est exécutée sur une pile de versions, votre payload contiendra l’ID de l’« élément principal », c’est-à-dire le fichier situé tout en haut de la pile et qui s’affiche dans l’interface utilisateur de Frame.io.

Pour en savoir plus sur les différences entre l’API Frame.io héritée et la version V4, consultez notre guide de migration.

Une action personnalisée nécessite :

Configurer une action personnalisée

Lorsqu’un utilisateur déclenche une action personnalisée, Frame.io envoie une payload à l’URL que vous avez indiquée. L’application destinataire peut répondre par un code d’état HTTP pour accuser réception, ou par un rappel personnalisé qui affiche des éléments d’interface utilisateur supplémentaires dans Frame.io.

Configuration avec plusieurs ressources

La prise en charge de plusieurs ressources dépend de la configuration et doit être activée explicitement depuis la fenêtre de configuration de l’action sur le Web. Vous pouvez effectuer cette opération lors de la création d’une nouvelle action ou lors de la mise à jour d’une action existante. 

Si la prise en charge de plusieurs ressources est activée, le format de la payload est immédiatement modifié. Les payloads héritées et celles prenant en charge plusieurs ressources s’excluent mutuellement.

Payload depuis Frame.io

Lorsque l’utilisateur clique sur votre action personnalisée, une payload est envoyée à l’URL que vous avez définie dans le champ URL. Utilisez cette payload pour identifier :

  POST /your/url
  {
    "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
    "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab",
    "data": {
        "description": "Pretty cool video.",
        "title": "Hey there!"
    },
    "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa",
    "project": {
        "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
    },
    "resources": [
        {
            "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476",
            "type": "file"
        },
        {
            "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
            "type": "file"
        }
    ],
    "type": "some.event",
    "user": {
        "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
    },
    "workspace": {
        "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
    }
  }

  POST /your/url
  {
      "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
      "action_id": "0e38b93a-9f10-4bc7-90bc-bd07a16e510a",
      "data": {
          "description": "Wow look at this.",
          "title": "Hey there!!"
      },
      "interaction_id": "dff6d369-7150-41f9-8e6f-4f0895f6b416",
      "project": {
          "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
      },
      "resource": {
          "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
          "type": "file"
      },
      "type": "some.event",
      "user": {
          "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
      },
      "workspace": {
          "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
      }
  }                                  

Migration depuis la payload héritée

Interactions, tentatives et délais d’expiration

L’interaction_id est un identifiant unique permettant de suivre l’évolution de l’interaction au fil du temps. Si vous n’avez pas besoin de répondre à l’utilisateur, renvoyez un code d’état 200, et le tour est joué. Bien que cela soit facultatif, nous vous recommandons d’inclure des informations sur le résultat de l’action, par exemple un message de réussite ou une alerte d’erreur. Les actions personnalisées prennent en charge les rappels de message.

Créer un rappel de message

Dans votre réponse HTTP à l’événement webhook, vous pouvez renvoyer un objet JSON décrivant un message qui sera affiché à l’utilisateur à l’origine de la requête dans l’interface utilisateur de Frame.io.

{
  "title": "Success!",
  "description": "The thing worked! Nice."
}

Les messages vous permettent de faire part de vos commentaires à l’utilisateur directement dans l’interface utilisateur de Frame.io. Si vous avez besoin de recueillir des informations supplémentaires auprès de l’utilisateur, utilisez plutôt les rappels de formulaire.

Créer un rappel de formulaire

Imaginons que vous ayez besoin de plus d’informations avant de vous lancer dans cette démarche. Par exemple, il se peut que vous deviez charger du contenu vers un système qui nécessite des informations supplémentaires. Vous pouvez inclure un formulaire dans votre réponse, que l’utilisateur remplit puis vous renvoie. Voici un exemple :

{
  "title": "Need some more info!",
  "description": "Getting ready to submit this file!",
  "fields": [
    {
      "type": "text",
      "label": "Title",
      "name": "title",
      "value": "MyVideo.mp4"
    },
    {
      "type": "select",
      "label": "Captions",
      "name": "captions",
      "options": [
        {
          "name": "Off",
          "value": "off"
        },
        {
          "name": "On",
          "value": "on"
        }
      ]
    }
  ]
}

Lorsque l’utilisateur envoie le formulaire, vous recevez une notification à la même URL que celle de la requête POST initiale :

POST /your/url
{
  "type": "your-specified-event-name",
  "interaction_id": "the-same-id-as-before",
  "action_id": "unique-id-for-this-custom-action",
  "data":{
    "title": "MyVideo.mp4",
    "captions": "off"
  }
}

Tous les champs personnalisés ajoutés à un formulaire apparaissent dans la section data de la payload JSON envoyée par Frame.io. Utilisez l’interaction_id pour associer la requête initiale à ces nouvelles données de formulaire. Vous pouvez répondre par un message ou ajouter un autre formulaire. En enchaînant des actions, des formulaires et des messages, vous pouvez programmer efficacement des workflows en plusieurs étapes dans Frame.io en intégrant la logique métier d’un système externe.

Détails du formulaire

Tout comme les messages, les formulaires prennent en charge les attributs title et description, qui s’affichent en haut du formulaire. De plus, chaque champ du formulaire accepte les attributs de base suivants :

Types de champs pris en charge

Champ de texte

Un champ de texte simple, sans paramètres supplémentaires.

{  
  "type": "text",
  "label": "Title",
  "name": "title",
  "value": "MyVideo.mp4"
}

Zone de texte

Une zone de texte simple, sans paramètres supplémentaires.

{  
  "type": "textarea",
  "label": "Description",
  "name": "description",
  "value": "This video is really, really popular."
}

Liste de sélection

Définit une liste de sélection parmi laquelle l’utilisateur peut faire son choix. Doit comporter une liste d’options, dont chacune doit comporter un attribut name lisible par l’utilisateur et une value analysable par un système informatique.

{
  "type": "select",
  "label": "Captions",
  "name": "captions",
  "value": "off",
  "options": [
       {
         "name": "Off",
         "value": "off"
       },
       {
         "name": "On",
         "value": "on"
      }
   ]
}

Case à cocher

Une simple case à cocher sans paramètres supplémentaires.

{ 
   "type": "boolean", 
   "name": "enabled", 
   "label": "Enabled", 
   "value": "false"
}

Lien

Un simple lien sans paramètres supplémentaires.

{
  "type": "link",
  "name": "videoLink",
  "label": "Video Link",
  "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc"
}

Le modèle d’autorisations de Frame.io

Les actions personnalisées suivent un modèle d’autorisations particulier : elles sont associées à un espace de travail, et non à un utilisateur spécifique appartenant à un compte. Concrètement :

Sécurité et vérification

Par défaut, toutes les actions personnalisées sont associées à une clé de signature générée lors de leur création. Ce paramètre n’est pas configurable. Cette clé permet de vérifier que la requête provient bien de Frame.io. La requête POST contient les éléments suivants :

Vérification de la signature

import hmac
import hashlib
def verify_signature(curr_time, req_time, signature, body, secret):
    """
    Verify webhook/custom action signature
    :Args:
        curr_time (float): Current epoch time
        req_time (float): Request epoch time
        signature (str): Signature provided by the frame.io API for the given request
        body (str): Custom Action body from the received POST
        secret (str): The secret for this Custom Action that you saved when you first created it
    """
    if int(curr_time) - int(req_time) < 500:
        message = 'v0:{}:{}'.format(req_time, body)
        calculated_signature = 'v0={}'.format(hmac.new(
            bytes(secret, 'latin-1'),
            msg=bytes(message, 'latin-1'),
            digestmod=hashlib.sha256).hexdigest())
        if calculated_signature == signature:
            return True
    return False

Commentaires sur la version bêta

Nous serions ravis de connaître les souhaits et attentes des développeurs et des utilisateurs finaux relatifs à l’utilisation des actions dans Frame.io V4. N’hésitez pas à nous faire part de vos questions, idées et cas d’utilisation afin de nous aider à définir nos priorités.