Instruções: Como fazer upload (básico)

Introdução

Chegamos agora a um marco emocionante em nossa jornada de integração: o upload de recursos para o Frame.io.Este guia irá orientá-lo pelo processo básico de upload.

Pré-requisitos

Caso ainda não tenha feito isso, revise o guia Implementação do C2C: Configuração antes de prosseguir.Você precisará do access_token obtido durante o processo de autenticação e autorização.Para este guia, usaremos um recurso de teste de exemplo disponível neste link do Frame.io.Baixe este arquivo para acompanhar nossos exemplos, pois isso permitirá que você utilize os mesmos valores dos nossos comandos de exemplo.

Etapa 1: criar um recurso

Vamos fazer o upload do nosso arquivo de exemplo, que vamos supor que tenha sido criado há 10 segundos.Primeiro, precisamos criar uma referência de recurso no Frame.io:

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

Vamos examinar os parâmetros do conteúdo JSON:

name: o nome do ativo exibido no Frame.io.Não é necessário que ele corresponda ao nome do arquivo no disco.filetype: o tipo MIME do arquivo.A maioria das linguagens de programação oferece utilitários para detecção de tipo MIME (exemplos: Go, Python).filesize: o tamanho do arquivo em bytes.Nosso arquivo de exemplo tem aproximadamente 21,1 MB.offset: o número de segundos desde que o arquivo foi criado.O valor padrão é 0, caso seja omitido.Esse parâmetro deve ser fornecido, pois ajuda a determinar se os arquivos devem ser rejeitados devido à pausa do dispositivo.Abordaremos isso com mais detalhes no guia avançado de upload.

A resposta terá uma aparência semelhante a esta (com alguns campos omitidos):

1
{
2
    "_type": "file",
3
    ...
4
    "id": "9a280f99-8f4f-46b0-a4b4-ec4c2f95138e",
5
    ...
6
    "upload_urls": [
7
        "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path]",
8
        "https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path]"
9
    ],
10
    ...
11
}

Neste momento, apenas informamos ao Frame.io nossa intenção de fazer o upload de um arquivo. Nenhum dado real do arquivo foi transferido.Se você verificar a pasta do seu dispositivo no projeto, verá um recurso provisório no estado “em upload”.

O campo upload_urls contém as URLs para onde faremos o upload dos blocos do nosso arquivo.Para o nosso arquivo de teste, devemos receber duas URLs de upload.

Etapa 2: dividir o arquivo em blocos

A resposta continha várias URLs de upload.Ao fazer upload para o Frame.io, dividimos os arquivos em blocos e os enviamos separadamente, o que traz várias vantagens:

• Maior confiabilidade: se um bloco falhar, não precisamos reiniciar todo o upload
• Uploads mais rápidos: podemos enviar vários blocos em paralelo (conforme explicado no guia de uploads avançados)

Para determinar o tamanho ideal dos blocos, use esta fórmula:

1
# We use math.ceil() to ensure we get the upper bound in the division
2
chunk_size = math.ceil(float(file.size) / float(len(response.upload_urls)))

Para nosso arquivo de exemplo, o cálculo é:

1
math.ceil(21136250 / 2)
2
# 10568125

Isso significa que cada bloco deve ter 10.568.125 bytes.Os tamanhos dos blocos geralmente giram em torno de 25 MB, com cálculos exatos abordados no guia de uploads avançados.

Para esta demonstração, usaremos os comandos head e tail para extrair os blocos do arquivo.

Etapa 3: fazer upload dos blocos

Para fazer upload do primeiro bloco:

$
head -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \
>
curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path] \
>
        --include \
>
        --header 'content-type: video/mp4' \
>
        --header 'x-amz-acl: private' \
>
        --data-binary @-

A solicitação requer estes cabeçalhos:

content-type: o mesmo valor de tipo MIME usado ao criar o ativo x-amz-acl: Para permissões do AWS S3, defina sempre como private

Um upload bem-sucedido retorna:

HTTP/1.1 100 Continue
HTTP/1.1 200 OK
...

Da mesma forma, faça o upload do segundo bloco:

$
tail -c 10568125 ~/Downloads/C2C_TEST_CLIP.mp4 | \
>
curl -X PUT https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path] \
>
        --include \
>
        --header 'content-type: video/mp4' \
>
        --header 'x-amz-acl: private' \
>
        --data-binary @-

Após a conclusão de ambos os uploads, seu ativo deverá estar pronto para reprodução no Frame.io!🎉

Reunindo tudo

Aqui está um exemplo simplificado de pseudocódigo semelhante ao Python para o processo completo de upload:

1
file = open("~/Downloads/C2C_TEST_CLIP.mp4")
2
mimetype = mimetypes.for_file("~/Downloads/C2C_TEST_CLIP.mp4")[0]
3
created_at = time.ctime(file.stat.ST_CTIME)
4
5
asset = c2c.asset_create(
6
    name="C2C_TEST_CLIP.mp4", 
7
    filetype=mimetype, 
8
    filesize=file.size,
9
    offset=datetime.now() - created_at,
10
    channel=0,
11
)
12
13
chunk_size = math.ceil(float(file.size) / float(len(asset.upload_urls)))
14
15
for chunk_url in asset.upload_urls:
16
   chunk = file.read(bytes=chunk_size)
17
   c2c.upload_chunk(chunk, chunk_url, mimetype)

Este exemplo demonstra o fluxo básico sem tratamento de erros ou uploads paralelos, que serão abordados nos guias de tratamento de erros e uploads avançados.

Próximas etapas

Parabéns por ter realizado com sucesso o upload do seu primeiro recurso no Frame.io!O guia de uploads avançados abordará técnicas mais sofisticadas e requisitos para implementações prontas para produção.Recomendamos que você entre em contato com nossa equipe caso tenha alguma dúvida e consulte o guia de uploads em tempo real para saber mais sobre como fazer o upload de recursos à medida que eles são criados.