Principais pontos
- Codifique uma única saída MP4 revisada antes da exportação para o YouTube, em vez de fazer o canal aceitar todas as variações de origem.
- Inicie as exportações como privadas para que a conclusão do processamento não seja confundida com aprovação editorial ou publicação pública.
- Mantenha o acesso OAuth em Credenciais de Template nomeadas e mantenha os segredos da conta da Transloadit fora do código do navegador.
Um upload direto para o YouTube é conveniente até que cada navegador, cliente mobile e ferramenta interna implemente por conta própria validação, suposições de codificação, regras de metadados e comportamento de novas tentativas. Um fluxo de trabalho em três etapas cria uma única passagem controlada: aceitar a origem, normalizar o entregável e, depois, publicá-lo em um canal sob uma política de visibilidade explícita.
O que mais importa
- Valide título, descrição e palavras-chave na aplicação antes de fornecê-los como campos do Template, e mantenha categoria e visibilidade como valores fixos do Template, em vez de entrada do cliente.
- Armazene o Assembly ID e o identificador retornado pela plataforma para que novas tentativas não possam criar vídeos duplicados silenciosamente.
- Teste as permissões e cotas do canal com a conta de destino real antes de ativar a publicação sem supervisão.
Defina a publicação como uma transição de estado
Fazer o upload dos bytes, concluir uma codificação e tornar um vídeo público são três eventos diferentes. Modele-os separadamente. A aplicação deve saber qual usuário forneceu a origem, quais metadados foram aprovados, qual versão do fluxo de trabalho foi executada e se uma pessoa ou política pode expor o registro resultante no canal. Um Step /youtube/store concluído prova que o YouTube aceitou a exportação; não prova que o conteúdo deva ser público.
Comece com a visibilidade definida como private. Reconcilie a identidade de destino retornada com o registro da aplicação, permita que editores inspecionem a reprodução e os metadados, e faça a publicação pública ou não listada por meio de uma ação explicitamente autorizada. Esse limite impede que um fluxo de trabalho técnico bem-sucedido contorne a moderação, o agendamento ou a revisão de direitos.
Transferência concluída
O arquivo de origem chegou à Assembly e está disponível para os Steps posteriores.
Processamento concluído
O MP4 controlado existe e passou nas verificações técnicas definidas pelo Template.
Publicação aprovada
A aplicação reconciliou o destino e autorizou o público dele.
Monte o Template bloqueado do YouTube
O grafo base tem um Step de upload, um Step de codificação e um Step de exportação para o YouTube. /upload/handle se chama :original e não define um valor para use. /video/encode lê :original e produz uma versão MP4 dentro de limites definidos. /youtube/store lê apenas essa versão, portanto um upload bruto de câmera não consegue contornar a política de codificação.
Mantenha allow_steps_override como false quando clientes de navegador ou de dispositivos móveis criarem Assemblies a partir do Template. Forneça apenas campos title, description e keywords revisados, vindos de um servidor confiável. O exemplo fixa category como education e visibility como private no Template salvo; quem faz a chamada não pode alterá-los por meio de fields. Valide os metadados de tempo de execução antes de assinar ou criar a Assembly, em vez de descobrir erros depois de uma codificação grande.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 2147483648
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"youtube_ready": {
"use": ":original",
"robot": "/video/encode",
"preset": "web/mp4/1080p",
"width": 1920,
"height": 1080,
"resize_strategy": "fit",
"zoom": false
},
"youtube_private": {
"use": "youtube_ready",
"robot": "/youtube/store",
"credentials": "youtube-channel",
"title": "${fields.title}",
"description": "${fields.description}",
"category": "education",
"keywords": "${fields.keywords}",
"visibility": "private",
"result": true
}
}
}Proteja as credenciais e os metadados do canal
Crie credenciais de Template do YouTube pelo fluxo OAuth e referencie apenas o nome delas no Template. O navegador nunca deve receber o token OAuth nem o Auth Secret da Transloadit. O servidor deve selecionar o Template fixo, autorizar o canal de destino e restringir quais usuários podem fornecer metadados de publicação.
Não interpole HTML arbitrário, segredos ou dados internos de registros na descrição pública. Aplique um limite de 80 caracteres para o título e limite o tamanho e a quantidade de palavras-chave na aplicação. Se o produto precisar de outra categoria ou visibilidade, transforme isso em uma alteração autorizada no Template salvo ou selecione um Template revisado separadamente; não aceite substituições arbitrárias vindas do cliente.
Reconcilie a conclusão sem publicação duplicada
A codificação de vídeo e um upload para uma plataforma remota podem durar mais que uma requisição interativa. Persista uma operação de publicação local antes de criar a Assembly, anexe o Assembly ID assim que ele existir e conclua o registro a partir de um webhook com assinatura verificada ou de uma consulta posterior ao Assembly Status. Guarde a identidade retornada pelo YouTube junto com a operação, em vez de depender apenas da URL do resultado como registro.
Um tempo limite esgotado não é prova de que a exportação falhou. Antes de tentar novamente, verifique a operação armazenada e o Assembly Status. Uma chave de idempotência estável, baseada na versão da origem, no canal, na versão do fluxo de trabalho e no evento de publicação pretendido, impede que uma resposta perdida crie um segundo vídeo privado que ninguém percebe.
Teste o contrato de destino
Use o canal de destino real com um arquivo de teste privado. Verifique as dimensões codificadas, o áudio, a duração, o comportamento de truncamento do título, a categoria, as palavras-chave e a privacidade. Teste uma concessão OAuth expirada, um usuário sem permissão no canal, um título acima do limite da aplicação, uma origem não suportada e uma notificação de conclusão repetida.
Monitore falhas por fase: recebimento, codificação ou exportação para o YouTube. Registre o tempo em fila, a duração do processamento, os bytes de saída, a duração da exportação, a identidade no destino e o estado final. Mantenha os erros brutos do provedor em diagnósticos protegidos e mostre aos editores uma ação estável, como reconectar as credenciais, corrigir os metadados ou tentar novamente a operação existente.
Mantenha a retenção da origem separada da entrega no canal
O YouTube é um destino de publicação, não necessariamente o acervo de origem da aplicação. Decida se o master enviado, o arquivo de entrega codificado ou ambos devem permanecer em um armazenamento controlado pela aplicação. Manter uma origem conhecida viabiliza recodificações posteriores, revisão de direitos, migração de provedor e recuperação após uma exclusão acidental no canal.
Aplique a exclusão somente depois que a identidade no destino estiver reconciliada e a política de retenção do produto permitir. Um vídeo privado no YouTube ainda pode ser removido, bloqueado ou desconectado da conta da aplicação, por isso não use apenas a presença na plataforma como evidência de que o fluxo de trabalho de origem foi bem-sucedido.
Detalhes técnicos que vale a pena conhecer
- /upload/handle deve se chamar :original, não deve definir use e só pode aparecer uma vez em um conjunto de Assembly Instructions.
- O schema de /youtube/store exige credentials, title, description, category, keywords e visibility. O valor de visibility não tem padrão e deve ser public, private ou unlisted, portanto omiti-lo faz a validação falhar. Defina-o como private para um fluxo de trabalho com revisão antes da publicação.
- O schema de /youtube/store limita títulos a 80 caracteres e restringe category a um enum fixo. O YouTube documenta um limite de 5.000 caracteres para a descrição, que a aplicação precisa impor, porque o schema do Robot aceita strings de qualquer tamanho.
- As palavras-chave do YouTube são fornecidas como uma única string separada por vírgulas, e não como um array.
- Um Step /youtube/store pode receber um vídeo e uma miniatura personalizada por meio de entradas use nomeadas, mas a configuração base de três etapas envia apenas o vídeo codificado.
- As credenciais de Template guardam a autorização OAuth do YouTube. Elas não decidem qual usuário da aplicação pode publicar no canal conectado.
Uma abordagem prática
- 1
Defina a origem aceita, a versão de saída, os limites de metadados e o estado de aprovação.
- 2
Crie Credenciais de Template do YouTube e salve um Template bloqueado de upload, codificação e exportação.
- 3
Envie um único arquivo de teste privado e reconcilie o resultado da Assembly com um registro da aplicação.
- 4
Teste envios duplicados, acesso OAuth expirado, metadados rejeitados e publicação manual.
Quando a Transloadit é útil
Use /upload/handle para o arquivo recebido, /video/encode para uma versão MP4 delimitada e /youtube/store para o upload no canal. Mantenha o Template salvo bloqueado, obtenha o acesso OAuth ao YouTube por meio de Credenciais de Template, valide os metadados de tempo de execução na aplicação e comece com a visibilidade privada.
Limite da arquitetura
A Transloadit pode receber, codificar e fazer o upload de um vídeo para o YouTube, mas a aplicação continua responsável pela autorização de quem faz o upload, pela aprovação editorial, pela política de metadados, pela governança do canal e pela relação durável entre o registro dela e o vídeo resultante no YouTube.
Perguntas frequentes
O fluxo de trabalho pode publicar diretamente como público?
Sim, o /youtube/store oferece suporte à visibilidade pública, mas a visibilidade privada é mais segura quando a publicação exige aprovação editorial, de direitos ou de moderação. Faça da publicação pública uma transição separada e autorizada.
O YouTube ainda transcodifica o MP4 após o upload?
A codificação da Transloadit controla o entregável delimitado cujo upload é feito para o YouTube, enquanto o YouTube controla separadamente como esse upload é preparado para reprodução na plataforma dele.
Onde o token OAuth do YouTube deve ficar armazenado?
Em Credenciais de Template nomeadas. O código do navegador não deve receber nem o token OAuth nem o Auth Secret da Transloadit.
Como evitamos vídeos duplicados após um tempo limite esgotado?
Persista a operação e o Assembly ID antes de aguardar. Verifique esse estado e o Assembly Status antes de criar outra Assembly para a mesma origem, o mesmo canal e o mesmo evento de publicação.
Este fluxo de trabalho pode adicionar uma miniatura personalizada?
Sim, o /youtube/store pode receber entradas nomeadas de vídeo e de imagem, mas isso adiciona outra ramificação de processamento. O guia básico cobre intencionalmente o fluxo de trabalho de três etapas apenas com vídeo.