Пользовательские действия

Действия Frame.io обеспечивают быстрый доступ к часто используемым операциям с медиафайлами, таким как загрузка, переименование и дублирование элементов, а также позволяют осуществлять интеграцию со сторонними инструментами и сервисами прямо в пользовательском интерфейсе Frame.io.

О действиях

С появлением функции «Пользовательские действия» разработчики могут настраивать собственные действия и управлять ими в Frame.io V4. Используя ту же базовую систему событий, что и веб-перехватчики, пользовательские действия предоставляют разработчикам альтернативный механизм для связывания своих ресурсов с наиболее важными для пользователей инструментами в их учетной записи Frame.io.

Действия может выполнять любой пользователь, являющийся участником рабочей среды Frame.io, в которой это действие включено. При выполнении действия Frame.io отправляет полезную нагрузку на указанный вами URL-адрес. Принимающее приложение отвечает кодом состояния HTTP для подтверждения получения или специальным обратным вызовом для рендеринга дополнительных полей формы в интерфейсе Frame.io. В качестве принимающего приложения может выступать как ваша собственная размещенная на сервере программа, так и сторонний сервис или даже малокодовый/бескодовый инструмент IPaaS, например Workfront Fusion или Zapier.

Используйте пользовательские действия для создания интеграций непосредственно в Frame.io в качестве программируемых компонентов интерфейса. Это позволяет получить рабочие процессы, запускаемые пользователями в приложении, используя ту же базовую систему маршрутизации событий, что и веб-перехватчики. Вы можете создавать запускаемые пользователями одно- или многошаговые формы, которые возвращаются в Frame.io в виде новой формы или базового ответа. Когда пользователь нажимает пользовательское действие для ресурса, Frame.io отправляет полезную нагрузку на указанный вами URL-адрес. Принимающее приложение отвечает кодом состояния HTTP для подтверждения получения или специальным обратным вызовом для рендеринга дополнительных элементов интерфейса в Frame.io.

Улучшение действий в версии V4

Опираясь на опыт пользователей нашей предыдущей версии, мы внесли ряд улучшений в набор функций «Действия» в Frame.io V4.

Перенесенные действия

При переносе в версию Frame.io V4 учетной записи с пользовательскими действиями, созданными в предыдущей версии Frame.io, следует учесть несколько моментов.

Статус действий

После переноса учетной записи в Frame.io V4 все пользовательские действия, созданные в более ранних версиях, получат статус null и будут автоматически отключены. Это дает пользователям возможность сначала обновить свои действия для работы с API-интерфейсом V4 перед их включением, любые необновленные действия будут завершаться ошибкой. Чтобы определить действия, имеющие этот статус, перейдите на страницу настроек действий и посмотрите их состояние в столбце «Статус» или, если вы используете API-интерфейс, проверьте поле is_active.

Доступные для действий ресурсы: файлы, папки и стеки версий

Учитывая разделение типов ресурсов в API-интерфейсе Frame.io V4, следует учитывать логику поведения при интерпретации идентификатора ресурса, полученного в полезной нагрузке вашего действия. Логика для отдельных файлов предельно проста: идентификатор будет указывать на конкретный файл, для которого было выполнено действие. Аналогично и для папок — вы получите идентификатор той папки, для которой было выполнено действие. Однако, в зависимости от сценария использования, есть несколько вариантов при определении поведения вашего действия. Используйте идентификатор папки для выполнения последующих вызовов к API-интерфейсу Frame.io, если хотите взаимодействовать с самим ресурсом папки. В качестве альтернативы можно получить дочерние элементы этой папки для выполнения дальнейшей обработки ресурсов внутри нее. Когда действие выполняется для стека версий, ваша полезная нагрузка будет содержать идентификатор «головного ресурса» — файла, который находится на самом верху стека и отображается в интерфейсе.

Подробнее о различиях между предыдущей версией API-интерфейса Frame.io и версией V4 — в нашем руководстве по миграции.

Для пользовательского действия требуются следующие поля.

Настройка пользовательского действия

Когда пользователь запускает пользовательское действие, Frame.io отправляет полезную нагрузку на указанный вами URL-адрес. Принимающее приложение отвечает кодом состояния HTTP для подтверждения получения или специальным обратным вызовом для рендеринга дополнительных элементов интерфейса в Frame.io.

Настройка работы с множеством ресурсов

Поддержка множества ресурсов задается в настройках и должна быть прямо включена в модальном окне настроек действия в веб-версии. Это можно сделать как при создании нового действия, так и при обновлении уже существующего. 

При включении поддержки множества ресурсов формат полезной нагрузки сразу переключается. Предыдущий формат полезной нагрузки и формат с поддержкой множества ресурсов являются взаимоисключающими.

Полезная нагрузка от Frame.io

Когда пользователь нажимает ваше пользовательское действие, полезная нагрузка отправляется на URL-адрес, указанный вами в поле URL. Используйте эту полезную нагрузку для определения следующего.

  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"
      }
  }                                  

Переход с устаревшей полезной нагрузки

Взаимодействия, повторные попытки и таймауты

interaction_id — это уникальный идентификатор для отслеживания взаимодействия по мере его развития. Если вам не нужно отвечать пользователю, просто верните код состояния 200, и все готово. Хотя это необязательно, мы рекомендуем включить информацию о результате действия, например сообщение о выполнении или предупреждение об ошибке. Пользовательские действия поддерживают обратные вызовы сообщений.

Создание обратного вызова для сообщений

В своем ответе HTTP на событие веб-перехватчика можно вернуть объект JSON с описанием сообщения, которое отобразится запустившему действие пользователю в интерфейсе Frame.io.

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

Сообщения позволяют отправлять обратную связь пользователю непосредственно в интерфейсе Frame.io. Если вам нужно собрать дополнительную информацию от пользователя, используйте вместо них обратные вызовы форм.

Создание обратного вызова для форм

Допустим, вам требуется получить больше информации перед началом процесса. Например, вы добавляете контент в систему, которая требует ввода дополнительных данных. В таком случае вы можете описать форму в своем ответе — пользователь заполнит ее и отправит обратно вам. Пример

{
  "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"
        }
      ]
    }
  ]
}

Когда пользователь отправит форму, вы получите событие по тому же URL-адресу, что и в исходном запросе POST.

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"
  }
}

Все пользовательские поля, добавленные в форму, отображаются в разделе data полезной нагрузки JSON, которая отправляется Frame.io. Используйте interaction_id для сопоставления исходного запроса с этими новыми данными формы. Вы можете ответить сообщением или вызвать другую форму в цепочке. Связывая в цепочку действия, формы и сообщения, можно эффективно программировать многоэтапные рабочие процессы в Frame.io с бизнес-логикой из внешней системы.

Сведения о форме

Как и сообщения, формы поддерживают атрибуты title и description, которые отображаются в верхней части формы. Помимо этого, каждое поле формы принимает следующие базовые атрибуты.

Поддерживаемые типы полей

Текстовое поле

Простое текстовое поле без дополнительных параметров.

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

Текстовая область

Простая текстовая область без дополнительных параметров.

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

Список выбора

Определяет список вариантов, из которых пользователь может выбирать. Должен включать в себя массив вариантов options. Каждый элемент этого массива должен содержать легко читаемое человеком имя name и считываемое машиной значение value.

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

Флажок

Простой флажок без дополнительных параметров.

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

Ссылка

Простая ссылка без дополнительных параметров.

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

Модель разрешений Frame.io

Пользовательские действия имеют специальную модель разрешений: они принадлежат рабочей среде, а не конкретному пользователю, существующему в учетной записи. Это означает следующее.

Безопасность и проверка

По умолчанию для всех пользовательских действий генерируется ключ подписи при их создании. Эту установку нельзя изменить. Данный ключ можно использовать для проверки того, действительно ли запрос исходит от Frame.io. В запрос POST включается следующее.

Проверка подписи

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

Обратная связь

Мы будем рады узнать от разработчиков и пользователей, как вы бы хотели использовать действия в Frame.io V4. Обязательно делитесь с нами своими вопросами, идеями и сценариями использования, чтобы мы могли правильно определить приоритеты.