Custom Actions

Durch Frame.io-Actions erhalten Sie schnellen Zugriff auf gängige Medienvorgänge wie Herunterladen, Umbenennen und Duplizieren von Elementen. Außerdem ist die Integration von Drittanbieter-Tools und -Services direkt in die Bedienoberfläche von Frame.io möglich.

Über Actions

Mit der Einführung von Custom Actions können Entwickelnde in Frame.io V4 ihre eigenen Actions konfigurieren und verwalten. Auf Basis desselben zugrunde liegenden Ereignissystems wie bei Webhooks sind Custom Actions ein alternativer Mechanismus für Entwickelnde, um ihre Assets mit den Tools zu verknüpfen, die für die Benutzenden in ihrem Frame.io-Konto am wichtigsten sind.

Actions können von allen Benutzenden ausgeführt werden, die Mitglied des Frame.io-Arbeitsbereichs sind, in dem die Action aktiviert ist.Bei der Ausführung einer Action wird von Frame.io eine Payload an eine bereitgestellte URL gesendet.Die empfangende Anwendung reagiert zur Empfangsbestätigung mit einem HTTP-Statuscode oder mit einem selbstdefinierten Rückruf, um zusätzliche Formularfelder in der Frame.io-Bedienoberfläche zu rendern.Bei der empfangenden Anwendung kann es sich um Ihr eigenes gehostetes Programm handeln, einen Dienst oder sogar ein Low-Code/No-Code-IPaaS-Tool wie Workfront Fusion oder Zapier.

Mit Custom Actions erstellen Sie Integrationen direkt in Frame.io als programmierbare UI-Komponenten. Dies ermöglicht Workflows, die von Benutzenden innerhalb der App ausgelöst werden können und dabei dasselbe zugrunde liegende Ereignisrouting nutzen wie Webhooks.Sie können von Benutzenden ausgelöste ein- oder mehrstufige Formulare erstellen, die als weiteres Formular oder als einfache Antwort an Frame.io zurückgesendet werden.Wenn Benutzende bei einem Asset auf eine Custom Action klicken, wird von Frame.io eine Payload an eine bereitgestellte URL gesendet.Die empfangende Anwendung reagiert zur Empfangsbestätigung mit einem HTTP-Statuscode oder mit einem selbstdefinierten Rückruf, mit dem in Frame.io zusätzliche Bedienoberfläche gerendert werden kann.

Verbesserungen an Actions in V4

Basierend auf den Erkenntnissen von Benutzenden unserer Vorgängerversion haben wir in Frame.io V4 eine Reihe von Verbesserungen am Leistungsumfang der Actions vorgenommen:

Migrierte Actions

Es gibt ein paar Dinge zu beachten, wenn Sie nach einem Frame.io V4-Konto migrieren, das Custom Actions enthält, die zuvor in der älteren Version von Frame.io erstellt wurden.

Action-Status

Nach der Kontomigration nach Frame.io V4 haben alle Custom Actions, die in früheren Versionen erstellt wurden, den Status „null“ und werden automatisch deaktiviert.Dies gibt Benutzenden die Möglichkeit, zuerst Ihre Actions für die Verwendung der V4-API zu aktualisieren, bevor sie aktiviert werden, da alle nicht aktualisierten Actions fehlschlagen werden.Um Actions in diesem Zustand zu identifizieren, besuchen Sie die Actions-Einstellungsseite und sehen Sie in der Spalte „Status“ nach. Falls Sie die API nutzen, überprüfen Sie das Feld is_active.

Ausführbare Ressourcen: Dateien, Ordner und Versionsstapel

Aufgrund der Abspaltung von Medientypen als separate Ressourcen in der Frame.io V4-API gilt es möglicherweise, das Verhalten zu berücksichtigen, wenn Sie die Ressourcen-ID interpretieren, die in der Payload Ihrer Action empfangen wird.Das Verhalten bei einzelnen Dateien ist unkompliziert, da die ID die spezifische Datei widerspiegelt, an der die Action ausgeführt wurde.Ebenso erhalten Sie bei Ordnern die ID für den Ordner, an dem die Action ausgeführt wurde. Je nach Anwendungsfall jedoch haben Sie bei der Definition des Verhaltens Ihrer Action mehrere Optionen.Senden Sie mithilfe der Ordner-ID nachfolgende Aufrufe an die Frame.io-API, wenn Sie mit der Ordner-Ressource selbst interagieren möchten.Alternativ möchten Sie vielleicht die untergeordneten Elemente dieses Ordners abrufen, um die Assets darin weiter zu verarbeiten.Wenn eine Action an einem Versionsstapel ausgeführt wird, enthält die Payload die ID für das „Head Asset“. Dies ist die oberste Datei im Stapel, die in der Bedienoberfläche von Frame.io angezeigt wird.

In unserem Migrationsleitfaden erfahren Sie mehr über die Unterschiede zwischen der älteren Version der Frame.io-API und V4.

Für eine Custom Action ist Folgendes erforderlich:

Konfigurieren der Custom Action

Wenn Benutzende eine Custom Action auslösen, wird von Frame.io eine Payload an eine bereitgestellte URL gesendet.Die empfangende Anwendung kann zur Empfangsbestätigung mit einem HTTP-Statuscode reagieren oder mit einem selbstdefinierten Rückruf, mit dem in Frame.io zusätzliche Bedienoberfläche gerendert wird.

Multi-Asset-Konfiguration

Multi-Asset-Unterstützung ist konfigurationsgesteuert und muss explizit über das Konfigurations-Modal der Action im Web aktiviert werden.Dies kann während der Erstellung einer neuen Action oder beim Aktualisieren einer vorhandenen Action erfolgen. 

Wenn die Multi-Asset-Unterstützung aktiviert wird, wird das Payload-Format sofort umgestellt.Die älteren und von mehreren Assets unterstützten Payloads schließen sich gegenseitig aus.

Payload von Frame.io

Wenn Benutzende auf Ihre Custom Action klicken, wird eine Payload an die URL gesendet, die Sie im URL-Feld festgelegt haben.Mit dieser Payload identifizieren Sie Folgendes:

1
  POST /your/url
2
  {
3
    "account_id": "1a94720e-f7f5-4c41-ab62-d11eebe3d504",
4
    "action_id": "0aeb9feb-f8eb-4100-a8c2-b39b66d354ab",
5
    "data": {
6
        "description": "Pretty cool video.",
7
        "title": "Hey there!"
8
    },
9
    "interaction_id": "985559de-865a-40e5-a687-2bbed4497eaa",
10
    "project": {
11
        "id": "3e34e7cb-5c21-49f5-8ca9-a1419584c2ea"
12
    },
13
    "resources": [
14
        {
15
            "id": "fe41c5a8-1b8d-417d-a7df-0b88bc19b476",
16
            "type": "file"
17
        },
18
        {
19
            "id": "fe81fb2b-1316-4a76-9cf6-0630f474fc39",
20
            "type": "file"
21
        }
22
    ],
23
    "type": "some.event",
24
    "user": {
25
        "id": "68093c1c-4b05-41ce-a3c9-e64d195b1935"
26
    },
27
    "workspace": {
28
        "id": "629086c0-f6aa-4d63-a284-f39bcd415b9f"
29
    }
30
  }

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

Migration von der älteren Payload

Interaktionen, Wiederholungen und Timeouts

Die interaction_id ist ein eindeutiger Bezeichner zur Verfolgung der Interaktion während ihrer Entwicklung im Zeitverlauf.Wenn Sie dem Benutzer bzw. der Benutzerin nicht antworten müssen, geben Sie den Statuscode 200 zurück, dann sind Sie fertig.Obwohl optional, empfehlen wir, Informationen über das Ergebnis der Action einzubeziehen, etwa eine Erfolgsmeldung oder eine Fehlermeldung.Mit Custom Actions sind Nachrichtenrückrufe möglich.

Erstellen eines Nachrichtenrückrufs

In Ihrer HTTP-Antwort auf das Webhook-Ereignis können Sie ein JSON-Objekt zurückgeben, in dem eine Nachricht beschrieben wird, die in der Frame.io-Bedienoberfläche an initiierende Benutzende zurückgegeben wird.

1
{
2
  "title": "Success!",
3
  "description": "The thing worked! Nice."
4
}

Mit Nachrichten können Sie Benutzenden direkt in der Frame.io-Bedienoberfläche Feedback geben.Wenn Sie zusätzliche Informationen von Benutzenden sammeln müssen, verwenden Sie stattdessen Formularrückrufe.

Erstellen eines Formularrückrufs

Angenommen, Sie benötigen mehr Informationen, bevor Sie Ihren Prozess starten.Sie laden z. B. möglicherweise Inhalte in ein System hoch, das zusätzliche Details erfordert.Sie können in Ihrer Antwort ein Formular abbilden, das von Benutzenden ausgefüllt und an Sie zurückgesendet wird.Es folgt ein Beispiel:

1
{
2
  "title": "Need some more info!",
3
  "description": "Getting ready to submit this file!",
4
  "fields": [
5
    {
6
      "type": "text",
7
      "label": "Title",
8
      "name": "title",
9
      "value": "MyVideo.mp4"
10
    },
11
    {
12
      "type": "select",
13
      "label": "Captions",
14
      "name": "captions",
15
      "options": [
16
        {
17
          "name": "Off",
18
          "value": "off"
19
        },
20
        {
21
          "name": "On",
22
          "value": "on"
23
        }
24
      ]
25
    }
26
  ]
27
}

Wenn Benutzende das Formular absenden, erhalten Sie auf derselben URL wie der ursprüngliche POST ein Ereignis:

1
POST /your/url
2
{
3
  "type": "your-specified-event-name",
4
  "interaction_id": "the-same-id-as-before",
5
  "action_id": "unique-id-for-this-custom-action",
6
  "data":{
7
    "title": "MyVideo.mp4",
8
    "captions": "off"
9
  }
10
}

Alle selbstdefinierten Felder, die einem Formular hinzugefügt wurden, erscheinen in der von Frame.io gesendeten JSON-Payload im Abschnitt data.Mit der interaction_id ordnen Sie die ursprüngliche Anfrage und diese neuen Formulardaten einander zu.Sie können mit einer Nachricht antworten oder ein weiteres Formular verknüpfen.Durch die Verkettung von Actions, Formularen und Nachrichten können Sie in Frame.io effektiv mehrstufige Workflows mit Geschäftslogik von einem externen System programmieren.

Formulardetails

Wie bei Nachrichten werden die Attribute title und description unterstützt, die oben im Formular angezeigt werden.Darüber hinaus werden von jedem Formularfeld die folgenden Basisattribute akzeptiert:

Unterstützte Feldtypen

Textfeld

Ein einfaches Textfeld ohne zusätzliche Parameter.

1
{  
2
  "type": "text",
3
  "label": "Title",
4
  "name": "title",
5
  "value": "MyVideo.mp4"
6
}

Textbereich

Ein einfacher Textbereich ohne zusätzliche Parameter.

1
{  
2
  "type": "textarea",
3
  "label": "Description",
4
  "name": "description",
5
  "value": "This video is really, really popular."
6
}

Auswahlliste

Definiert eine Auswahlliste, in der Benutzende wählen können.Muss eine options-Liste enthalten, deren Mitglieder jeweils einen von Menschen lesbaren name und einen maschinenlesbaren value enthalten sollten.

1
{
2
  "type": "select",
3
  "label": "Captions",
4
  "name": "captions",
5
  "value": "off",
6
  "options": [
7
       {
8
         "name": "Off",
9
         "value": "off"
10
       },
11
       {
12
         "name": "On",
13
         "value": "on"
14
      }
15
   ]
16
}

Kontrollkästchen

Ein einfaches Kontrollkästchen ohne zusätzliche Parameter.

1
{ 
2
   "type": "boolean", 
3
   "name": "enabled", 
4
   "label": "Enabled", 
5
   "value": "false"
6
}

Verknüpfen

Ein einfacher Link ohne zusätzliche Parameter.

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

Das Frame.io-Berechtigungsmodell

Bei Custom Actions gibt es ein besonderes Berechtigungsmodell: Sie gehören zu einem Arbeitsbereich, nicht zu bestimmten Benutzenden, die in einem Konto existieren.Das bedeutet:

Sicherheit und Verifizierung

Standardmäßig wird für alle Custom Actions während ihrer Erstellung ein Signaturschlüssel generiert.Das ist nicht konfigurierbar.Mit diesem Schlüssel kann verifiziert werden, dass die Anfrage von Frame.io stammt.In der POST-Anfrage ist Folgendes enthalten:

Signatur verifizieren

1
import hmac
2
import hashlib
3
4
def verify_signature(curr_time, req_time, signature, body, secret):
5
    """
6
    Verify webhook/custom action signature
7
    :Args:
8
        curr_time (float): Current epoch time
9
        req_time (float): Request epoch time
10
        signature (str): Signature provided by the frame.io API for the given request
11
        body (str): Custom Action body from the received POST
12
        secret (str): The secret for this Custom Action that you saved when you first created it
13
    """
14
    if int(curr_time) - int(req_time) < 500:
15
        message = 'v0:{}:{}'.format(req_time, body)
16
        calculated_signature = 'v0={}'.format(hmac.new(
17
            bytes(secret, 'latin-1'),
18
            msg=bytes(message, 'latin-1'),
19
            digestmod=hashlib.sha256).hexdigest())
20
        if calculated_signature == signature:
21
            return True
22
    return False

Feedback

Wir möchten gerne von Entwickelnden und Benutzenden erfahren, wie sie Actions in Frame.io V4 nutzen möchten.Wenden Sie sich gerne mit Ihren Fragen, Ideen und Anwendungsfällen an uns, um unsere Priorisierung mitzugestalten.