Guias práticos

Instruções: Organizar ativos

Introdução

Neste guia, aprenderemos como e até que ponto podemos controlar onde os ativos da sua integração são enviados.

O que vou precisar?

Caso ainda não tenha lido o guia Implementação do C2C: Configuração, dê uma olhada rápida nele antes de continuar! Você também precisará do access_token que recebeu durante o guia de autenticação e autorização do hardware C2C ou do aplicativo C2C.

Estrutura de pastas de ativos

Por padrão, os ativos são criados com a seguinte estrutura de pastas:

Cloud Devices > {YYYY}_{MM}_{DD} > {ASSET_TYPE} > {YOUR_DEVICE} > {ASSET_NAME} Onde {ASSET_TYPE} é VIDEO, AUDIO ou DATA (configurado para o modelo do seu dispositivo por canal), {YOUR_DEVICE} é o nome do dispositivo do projeto conectado ao projeto do usuário, e {ASSET_NAME} é o nome do recurso que você enviou e é o recurso que pode ser reproduzido no Frame.io.

Roteamento de extensão

Você pode configurar seu dispositivo para direcionar diferentes recursos para pastas {ASSET_TYPE} personalizadas com base na extensão do arquivo em {ASSET_NAME}. Por exemplo, digamos que sua integração gere vários tipos diferentes de arquivos, cada um pertencente a uma proveniência específica. Você pode nos pedir para mapear esses ativos da seguinte forma:

.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans

Agora, quando você criar o seguinte ativo:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_codes]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "IMAGE_0001.jpeg", 
>            "filetype": "image/jpeg", 
>            "filesize": 21136250,
>            "offset": 10
>        }
>__JSON__
>} | python -m json.tool
Especificação do ponto de acesso da API

A documentação para /v2/assets pode ser encontrada aqui

… será encaminhado para um local como: Cloud Devices > 2022_04_01 > STILLS > MY_DEVICE > IMAGE_0001.jpeg. Se, em vez disso, o arquivo se chamasse A001_C001.mov, seria encaminhado para: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > A001_C001.mov.

Caminhos de upload tokenizados

Algumas integrações podem precisar de maior controle sobre a estrutura de pastas criada pelo dispositivo. Por sua vez, nós, do Frame.io, precisamos garantir que haja um certo nível de consistência na forma como os arquivos são enviados para o Frame.io a partir de um dispositivo C2C e, especificamente, oferecer garantias aos clientes do Frame.io sobre com qual parte de seus projetos um dispositivo C2C pode interagir. Com esse objetivo, permitimos que os integradores personalizem os locais de upload de ativos dentro da pasta {YOUR_DEVICE}, mas não permitimos que ativos sejam enviados fora dessa pasta.

Para fazer o upload para uma estrutura de pastas personalizada, você precisará entrar em contato com seu Gerente de parceiros. Estruturas de pastas personalizadas são um conjunto de metadados tokenizados que devem ser fornecidos na criação do ativo. Vamos ver um exemplo simples:

Digamos que temos uma articulação de câmera 3D que tem valores de reel_name como &quot;A001&quot;, &quot;A002&quot;, &quot;A003&quot;, etc. e valores de clip_number como &quot;C001&quot;, &quot;C002&quot;, etc. Queremos criar pastas para cada clipe e preenchê-las com os arquivos do olho esquerdo e do olho direito, de modo que os arquivos fiquem assim em um projeto: Caminho de pasta tokenizado — Exemplo de articulação 3D

Para isso, precisaremos definir duas configurações:

  • Campos de metadados obrigatórios
  • Caminho de arquivo tokenizado

Campos de metadados obrigatórios são uma lista simples de chaves que devem ser definidas na criação do ativo para sua integração:

[reel_name, clip_number]

Você pode então usar qualquer uma dessas teclas para criar um caminho delimitado por /, utilizando {field_name} para indicar onde o valor de um campo deve ser inserido:

REEL_{reel_name}/{reel_name}_{clip_number}

Ambas as configurações terão que ser fornecidas à nossa equipe no Frame.io para adicionar como parte dos detalhes da sua integração. Depois de configurarmos isso, quando você criar um ativo, esses valores terão que ser fornecidos na raiz do conteúdo para que a criação do ativo seja bem-sucedida:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_LEFT.mp4", 
>            "filetype": "video/mp4", 
>            "filesize": 21136250,
>            "offset": 10,
>            "metadata": {
>              "reel_name": "A001",
>              "clip_number": "C001"
>            },
>        }
>__JSON__
>} | python -m json.tool

O exemplo acima criará um arquivo com um caminho completo como: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4

Erros de metadados

Se o dispositivo não foi explicitamente configurado para permitir esses campos, você receberá um erro se tentar fazer a mesma chamada. Da mesma forma, se você configurar campos de metadados obrigatórios, DEVE fornecê-los no conteúdo de criação de ativo ou um erro será retornado.

O conteúdo aceitará qualquer valor JSON válido. Valores que não são string são renderizados da seguinte forma:

  • integers: renderizados na base 10: 10 -> &quot;10&quot;
  • floats: usa a representação mais curta de acordo com o algoritmo descrito em “Como imprimir números de ponto flutuante com rapidez e precisão” em Anais da Conferência SIGPLAN ‘96 sobre Projeto e Implementação de Linguagens de Programação.
  • booleans: true e false são renderizados como &quot;true&quot; e &quot;false&quot;
  • null: renderizado como uma string em branco. Se reel_name fosse definido como null, então a primeira pasta personalizada seria renderizada como REEL_

Em geral, sugerimos que você limite seus valores a strings e formate os demais valores como achar melhor (por exemplo, números inteiros sempre serão exibidos sem zeros à esquerda, algo que talvez você queira alterar).

Em geral, apenas campos que tenham um valor válido para todos os clipes devem ser usados. Se um campo nem sempre tiver um valor válido, você deve ter um plano para representar valores não definidos ou nulos.

Empilhamento de versões

O Frame.io oferece suporte a pilhas de versões: uma maneira de agrupar várias iterações do mesmo conteúdo na interface do usuário. A API C2C permite que os dispositivos enviem novas iterações de um ativo, que serão incluídas em uma pilha de versões junto com suas versões anteriores. Para criar uma pilha de versões, você deve fornecer um autoversion_id para identificar a qual pilha de versões os ativos pertencem. Esse valor pode ser qualquer coisa: um UUID, um nome de arquivo, etc. Tome cuidado para usar apenas valores que nunca sejam repetidos acidentalmente em uma pasta de ativos. Por exemplo, se for possível que sua integração crie o mesmo nome de arquivo mais de uma vez, então o nome do arquivo não é uma boa opção para usar como autoversion_id.

Fornecemos um autoversion_id assim:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v01.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 10,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

Agora, sempre que você fizer upload de um novo ativo, se usar o mesmo autoversion_id, o ativo será adicionado como a versão mais recente em uma pilha com o ativo original:

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v02_with_color.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 10,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

Os ativos só serão empilhados se forem enviados para a mesma pasta, então você precisa ter algumas coisas em mente se quiser implementar a pilha de versões:

  • Os metadados tokenizados devem resolver para a mesma pasta principal para que a pilha de versões seja criada.
  • Como a data de criação faz parte do caminho do arquivo, novas versões criadas após a meia-noite (UTC) podem não ser empilhadas corretamente, a menos que você forneça um deslocamento para a hora de criação do upload original.

Este segundo ponto é importante. Suponhamos que, 48 horas após o upload inicial, seja criada uma nova versão do ativo. Para que ela seja empilhada com o ativo original, devemos fornecer um deslocamento de 48 horas no passado: 172.800 segundos.

${
>curl -X POST https://api.frame.io/v2/assets \
>    --header 'Authorization: Bearer [access_token]' \
>    --header 'Content-Type: application/json' \
>    --header 'x-client-version: 2.0.0' \
>    --data-binary @- <<'__JSON__' 
>        {
>            "name": "A001_C001_v03_with_color.mov", 
>            "filetype": "video/webm", 
>            "filesize": 21136250,
>            "offset": 172800,
>            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
>        }
>__JSON__
>} | python -m json.tool

Se o ativo atual tivesse sido enviado para 2022_04_03, agora será enviado para 2022_04_01 e empilhado com o ativo correto.

Próximas etapas

Este é o último guia para criar uma excelente integração C2C! Reserve um momento para se parabenizar! Talvez seja uma boa ideia fazer um lanchinho. A única coisa que resta fazer é revisar a lista de verificação do integrador, onde você encontrará um resumo de tudo o que é necessário para criar uma integração à prova de falhas.

Se ainda não o fez, recomendamos que entre em contato com nossa equipe e, em seguida, siga para o próximo guia. Estamos ansiosos para ter notícias suas!