> This page is for Plataforma, version V4 experimental. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 experimental: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - Herdado: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Ações personalizadas As Ações do Frame.io fornecem acesso rápido a operações de mídia comuns, como fazer download, renomear e duplicar itens, e também permitem que integrações com ferramentas e serviços de terceiros sejam exibidas diretamente na interface do usuário do [Frame.io](https://next.frame.io/). ## Sobre as Ações Com a introdução das Ações personalizadas, os desenvolvedores podem configurar e gerenciar suas próprias Ações no Frame.io V4.Aproveitando o mesmo sistema de eventos subjacente dos [Webhooks](https://developer.adobe.com/frameio/guides/Webhooks/), as Ações personalizadas são um mecanismo alternativo para desenvolvedores conectarem seus ativos às ferramentas mais importantes para os usuários em sua Conta do Frame.io. As Ações podem ser executadas por qualquer usuário que seja Membro do espaço de trabalho do Frame.io em que a Ação está ativada. Ao executar uma Ação, o Frame.io envia um conteúdo para uma URL fornecida por você. O aplicativo receptor responde com um código de status HTTP para confirmar o recebimento ou com um callback personalizado para renderizar campos de formulário adicionais na IU do Frame.io. O aplicativo receptor pode ser um programa ou serviço hospedado por você, ou até mesmo uma ferramenta IPaaS low-code/no-code, como Workfront Fusion ou Zapier. Use as Ações personalizadas para criar integrações diretamente no [Frame.io](https://next.frame.io/) como componentes de interface programáveis.Isso habilita fluxos de trabalho que podem ser acionados por usuários dentro do aplicativo, aproveitando o mesmo roteamento de eventos subjacente dos webhooks. Você pode criar formulários de uma ou várias etapas acionados pelo usuário que retornam ao Frame.io como outro formulário ou uma resposta básica. Quando um usuário clica em uma Ação personalizada em um Ativo, o Frame.io envia um conteúdo para uma URL fornecida por você. O aplicativo receptor responde com um código de status HTTP para confirmar o recebimento ou responde com um callback personalizado que pode renderizar uma IU adicional no Frame.io. ## Melhorias de Ações na V4 Aproveitando aprendizados obtidos com usuários da nossa versão Legacy, incluímos várias melhorias no conjunto de recursos de Ações no Frame.io V4: #### Novos tipos de campo Antes limitados a campos de texto e seleção única, agora também oferecemos suporte a seleção múltipla, área de texto (para uma caixa de texto maior) e campo booleano (para um botão de opção). #### Links clicáveis Campos de texto não facilitam para os usuários copiar/colar URLs. Use nosso novo campo de link para oferecer uma experiência fácil de copiar com 1 clique. #### Modais dinâmicos Dependendo da quantidade de dados retornados, você pode confiar que o modal da sua Ação será redimensionado dinamicamente para melhor acomodar as informações no formulário, incluindo modais roláveis quando necessário. #### Ações multiativo Configure sua Ação para direcionar até 100 ativos em uma solicitação. \ NOVO #### Tipos de ativo mistos Não limitadas a um único tipo de ativo, as Ações podem ser acionadas em uma combinação de arquivos, pastas e pilhas de versões. #### [Formulário de feedback no aplicativo](https://next.frame.io/settings/actions) Queremos ouvir desenvolvedores e usuários finais sobre como vocês usam Ações, então disponibilizamos um formulário de feedback na página de configurações na Web. ## Ações migradas Há alguns pontos a considerar ao migrar para uma Conta Frame.io V4 que contém Ações personalizadas criadas anteriormente na versão legada do Frame.io. ### Status da Ação Após a migração da Conta para o Frame.io V4, todas as Ações personalizadas criadas em versões anteriores terão status "null" e serão desativadas automaticamente. Isso oferece aos usuários a oportunidade de primeiro atualizar suas Ações para usar a API V4 antes de ativá-las, pois qualquer Ação não atualizada falhará. Para identificar Ações nesse estado, acesse a página Configurações de Ações e consulte a coluna "Status" ou, se estiver usando a API, verifique o campo is\_active. ### Recursos acionáveis: arquivos, pastas e pilhas de versões Considerando a separação dos tipos de ativo como recursos separados na API Frame.io V4, pode haver comportamentos a considerar ao interpretar o ID do recurso recebido no conteúdo da sua Ação. O comportamento para Arquivos individuais é direto, pois o ID refletirá o Arquivo específico no qual a Ação foi executada. Da mesma forma, para Pastas, você receberá o ID da Pasta na qual a Ação foi executada. No entanto, dependendo do seu caso de uso, você tem várias opções ao definir o comportamento da Ação. Use o ID da Pasta para fazer chamadas subsequentes à API do Frame.io se quiser interagir com o próprio recurso Pasta. Como alternativa, talvez você queira obter os filhos dessa Pasta para executar processamento adicional nos ativos contidos nela. Quando uma ação é Executada em uma Pilha de versões, o conteúdo conterá o ID do "Ativo principal", que é o Arquivo mais acima na Pilha e o que é mostrado na IU do Frame.io. Você pode ler mais sobre as diferenças entre a API Frame.io Legacy e a V4 no nosso [Guia de migração](/docs/resources/migration). > **Info** > > Configure [Ações personalizadas](/api-reference/custom-actions/actions-show) com a API. Uma Ação personalizada requer: | Nome do campo | Descrição | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- | | Nome | O nome que você escolhe para sua Ação personalizada. Ele será mostrado no menu de Ações personalizadas disponíveis no Frame.io. | | Descrição | Explique o que a Ação faz, para referência (a descrição não aparecerá no aplicativo Web do Frame.io). | | Evento | Chave interna do evento para ajudar você a diferenciar entre eventos de webhook padrão e os seus próprios. | | URL | Onde entregar eventos. | | Espaço de trabalho | O espaço de trabalho que usará a Ação personalizada. | ## Configurar sua Ação personalizada Quando um usuário aciona uma Ação personalizada, o Frame.io envia um conteúdo para uma URL fornecida por você. O aplicativo receptor pode responder com um código de status HTTP para confirmar o recebimento ou responder com um callback personalizado que renderiza IU adicional no [Frame.io](https://next.frame.io/). > **Warning** > > Permissões de administrador da conta são necessárias para criar Ações personalizadas para um espaço de trabalho. Peça ao administrador para modificar suas permissões se você não tiver acesso. ### Configuração multiativo O suporte a multiativo é orientado por configuração e deve ser ativado explicitamente no modal de configuração da Ação [na Web](https://next.frame.io/settings/actions). Isso pode ser feito durante a criação de uma nova Ação ou ao atualizar uma Ação existente. Quando o suporte a multiativo é ativado, o formato do conteúdo é alternado imediatamente. Os conteúdos legados e com suporte a multiativo são mutuamente exclusivos. ## Conteúdo do Frame.io Quando o usuário clica na sua Ação personalizada, um conteúdo é enviado para a URL definida no campo URL. Use esse conteúdo para identificar: #### Contexto da Ação * Qual Ação personalizada foi clicada * Quais recursos foram clicados * Qual usuário executou a ação * Qual tipo de evento foi acionado #### Contexto da organização * Qual conta está associada à Ação personalizada * Qual espaço de trabalho está associado à Ação personalizada * Qual Projeto contém os recursos #### Conteúdo - suporte a ativo único ou multiativo Originalmente, as ações personalizadas aceitavam apenas um ativo por solicitação usando um objeto `resource` que continha um ativo. Com o suporte a multiativo ativado, o conteúdo usa uma lista `resources` de um ou mais ativos, com um máximo de 100 ativos em uma solicitação. ```json 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" } } ``` #### Conteúdo legado - suporte somente a ativo único ```json 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" } } ``` ### Migração a partir do Conteúdo legado > **Conteúdo legado planejado para descontinuação** > > O Conteúdo legado está planejado para descontinuação, e os usuários são fortemente incentivados a migrar seus serviços para processar o novo conteúdo. > > Ao ativar o sinalizador de configuração e atualizar o processamento do conteúdo, uma Ação pode fazer uma transição fluida para oferecer suporte a conteúdo multiativo. > > 1. Substitua o uso do objeto singular `resource` pela lista `resources` 2. Atualize o código para iterar sobre a lista `resources` > > 2. Ative o sinalizador Multiativo na configuração de Ações | Nome do campo | Descrição | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `account_id` | O ID exclusivo da Conta da Ação. | | `action_id` | O ID exclusivo da Ação. | | `interaction_id` | Um identificador exclusivo gerado pelo Frame.io, usado para acompanhar sua transação em várias solicitações, como callbacks encadeados de Mensagem ou Formulário. Permanece o mesmo durante toda a sequência da Ação. | | `project_id` | O ID exclusivo do Projeto da Ação. | | `resource.id` | O ID do recurso a partir do qual a Ação foi acionada. | | `resource.type` | O tipo de recurso a partir do qual a Ação foi acionada. | | `type` | O nome fornecido no campo `event` ao configurar a Ação. | | `user.id` | O ID do usuário que acionou a Ação. | | `workspace.id` | O ID do espaço de trabalho que usa a Ação. | | `data` | Pares chave-valor contendo os nomes dos campos de formulário e os valores selecionados pelo usuário. Seu aplicativo recebe isso para saber quais escolhas foram feitas. | ## Interações, novas tentativas e tempos-limite O `interaction_id` é um identificador exclusivo para rastrear a interação conforme ela evolui ao longo do tempo. Se não precisar responder ao usuário, retorne um código de status 200 e pronto. Embora seja opcional, recomendamos incluir informações sobre o resultado da ação, como uma mensagem de sucesso ou alerta de erro. Ações personalizadas oferecem suporte a callbacks de mensagem. > **Note** > > O Frame.io espera uma resposta em menos de 10 segundos e tenta repetir até 5 vezes enquanto aguarda uma resposta bem-sucedida. O ideal é que a resposta seja imediata e que ações assíncronas ocorram após um acionador por meio de uma Ação personalizada. ## Criar um callback de mensagem Na resposta HTTP ao evento de webhook, você pode retornar um objeto JSON descrevendo uma mensagem que será retornada ao usuário iniciador na IU do Frame.io. ```json { "title": "Success!", "description": "The thing worked! Nice." } ``` As mensagens permitem fornecer feedback ao usuário diretamente na IU do Frame.io. Se precisar coletar informações adicionais do usuário, use **Callbacks de formulário**. ## Criar um callback de formulário Digamos que você precise de mais informações antes de iniciar seu processo. Por exemplo, talvez esteja fazendo upload de conteúdo para um sistema que exige detalhes adicionais. Você pode descrever um Formulário na resposta, que o usuário preenche e envia de volta para você. Veja um exemplo: ```json { "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" } ] } ] } ``` Quando o usuário envia o formulário, você receberá um evento na mesma URL do POST inicial: ```json 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" } } ``` Todos os campos personalizados adicionados a um formulário aparecem na seção `data` do conteúdo JSON enviado pelo Frame.io. Use o `interaction_id` para mapear a solicitação inicial e esses novos dados de formulário. Você pode responder com uma mensagem ou encadear outro formulário. Ao encadear Ações, Formulários e Mensagens, você pode programar fluxos de trabalho de várias etapas no Frame.io com lógica de negócios de um sistema externo. ## Detalhes do formulário Assim como mensagens, Formulários oferecem suporte aos atributos `title` e `description` que são renderizados na parte superior do formulário. Além disso, cada campo de formulário aceita os seguintes atributos de base: #### Propriedades do campo * **type** -- informa à IU do Frame.io qual tipo de dado esperar e qual componente renderizar. \* **label** -- aparece na IU como o cabeçalho acima do campo. #### Dados do campo * **name** -- chave pela qual o campo será identificado no conteúdo subsequente. \* **value** -- valor com o qual o campo será preenchido previamente. ## Tipos de campo compatíveis ### Campo de texto Um campo de texto simples sem parâmetros adicionais. ```json { "type": "text", "label": "Title", "name": "title", "value": "MyVideo.mp4" } ``` ### Área de texto Uma área de texto simples sem parâmetros adicionais. ```json { "type": "textarea", "label": "Description", "name": "description", "value": "This video is really, really popular." } ``` ### Lista de seleção Define uma lista de opções da qual o usuário pode escolher. Deve incluir uma lista `options`, e cada membro da qual deve incluir um `name` legível e um `value` analisável por máquina. ```json { "type": "select", "label": "Captions", "name": "captions", "value": "off", "options": [ { "name": "Off", "value": "off" }, { "name": "On", "value": "on" } ] } ``` ### Caixa de seleção Uma caixa de seleção simples sem parâmetros adicionais. ```json { "type": "boolean", "name": "enabled", "label": "Enabled", "value": "false" } ``` ### Link Um link simples sem parâmetros adicionais. ```json { "type": "link", "name": "videoLink", "label": "Video Link", "value": "https://www.youtube.com/watch?v=XtX1zv9CEVc" } ``` ## Modelo de permissões do Frame.io Ações personalizadas têm um modelo de permissões especial: elas pertencem a um espaço de trabalho, não a qualquer usuário específico existente em uma Conta. Isso significa: #### Criação e gerenciamento * Qualquer administrador pode criar uma Ação personalizada em um espaço de trabalho. * Qualquer administrador pode modificar ou excluir uma Ação personalizada existente em uma Equipe. #### Atualizações em tempo real * Depois de modificada, todos os usuários verão imediatamente o resultado da alteração. ## Segurança e verificação Por padrão, todas as Ações personalizadas têm uma chave de assinatura gerada durante sua criação. Isso não é configurável. Essa chave pode ser usada para verificar se a solicitação se origina do Frame.io. A solicitação `POST` inclui o seguinte: | Nome | Descrição | | ----------------------------- | -------------------------------------------------- | | `X-Frameio-Request-Timestamp` | A hora em que sua Ação personalizada foi acionada. | | `X-Frameio-Signature` | A assinatura calculada. | #### Verificação de carimbo de data e hora **O carimbo de data e hora** é o horário em que a solicitação foi assinada ao sair da rede do Frame.io. Isso pode ser usado para impedir ataques de repetição. Recomendamos verificar se esse horário está dentro de 5 minutos em relação à hora local. #### Verificação de assinatura **A assinatura** é um hash HMAC SHA-256 usando a chave de assinatura fornecida quando a Ação personalizada é criada pela primeira vez. ### Verificação da assinatura #### Extrair a assinatura Extraia a assinatura dos cabeçalhos HTTP. #### Criar mensagem para assinar Crie uma mensagem para assinar combinando a versão, a hora da entrega e o corpo da solicitação: `v0:timestamp:body`. #### Calcular HMAC SHA256 Calcule a assinatura HMAC SHA256 usando seu segredo de assinatura. #### Comparar assinaturas Compare a assinatura calculada com a fornecida. > **Note** > > A assinatura fornecida tem o prefixo `v0=`. Atualmente, o Frame.io possui apenas essa versão para assinar solicitações. Você precisará adicionar este prefixo à sua assinatura computada. **`Python`** ```python title="Python" 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 ``` ## Feedback Adoraríamos ouvir desenvolvedores e usuários finais sobre as formas como vocês gostariam de usar Ações no Frame.io V4. Entre em [contato conosco](https://forum.frame.io/) com suas dúvidas, ideias e casos de uso para ajudar a orientar nossa priorização.