Guida pratica: Caricamento (base)

Introduzione

Eccoci in un passaggio fondamentale e monto interessante nel percorso di integrazione: caricare le risorse su Frame.io. Questa guida illustra il processo di caricamento di base.

Prerequisiti

Se non l’hai già fatto, consulta la guida Implementazione C2C: configurazione prima di procedere.Avrai bisogno dell’access_token ottenuto durante il processo di autenticazione e autorizzazione.Per questa guida, utilizzeremo una risorsa test di esempio disponibile su questo link a Frame.io. Scarica questo file per seguire i nostri esempi, poiché ti permetterà di far corrispondere i valori nei nostri comandi di esempio.

Passaggio 1: crea una risorsa

Carichiamo il file di esempio, che supponiamo sia stato creato 10 secondi fa. Per prima cosa, dobbiamo creare un riferimento alla risorsa in 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

Esaminiamo i parametri del payload JSON:

name: il nome della risorsa visualizzato in Frame.io. Non deve corrispondere al nome file su disco. filetype: il tipo MIME del file. La maggior parte dei linguaggi di programmazione fornisce utilità per il rilevamento del tipo MIME (esempi: Go, Python). filesize: la dimensione del file in byte. Il file di esempio ha una dimensione di circa 21,1 MB. offset: il numero di secondi trascorsi dalla creazione del file. Per impostazione predefinita è 0, se omesso. Questo parametro deve essere fornito in quanto aiuta a determinare se i file devono essere rifiutati a causa della pausa del dispositivo. Approfondiremo questo argomento nella guida per il caricamento avanzato.

La risposta sarà simile a questa (alcuni campi sono omessi):

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
}

A questo punto, abbiamo solo informato Frame.io dell’intenzione di caricare un file; nessun dato del file è stato trasferito. Se controlli la cartella del tuo dispositivo nel progetto, vedrai una risorsa segnaposto in stato “uploading”.

Il campo upload_urls contiene gli URL dove caricheremo i chunk del file. Per il file di test, dovremmo ricevere due URL di caricamento.

Passaggio 2: divisione del file in chunk

La risposta conteneva più URL di caricamento. Quando carichi su Frame.io, i file vengono suddivisi in chunk che vengono caricati separatamente, il che offre diversi vantaggi:

• Maggiore affidabilità: se un chunk non riesce, non è necessario riavviare l’intero caricamento
• Caricamenti più veloci: possiamo caricare più chunk in parallelo (questa operazione è trattata nella guida al caricamento avanzato)

Per determinare la dimensione ottimale del chunk, usa questa formula:

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)))

Per il file di esempio, il calcolo è:

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

Questo significa che ogni chunk dovrebbe essere di 10.568.125 byte. Le dimensioni dei chunk in genere sono di circa 25 MB. I calcoli esatti sono trattati nella guida ai caricamenti avanzati.

Per questa dimostrazione, useremo i comandi head e tail per estrarre i chunk di file.

Passaggio 3: caricamento dei chunk

Per caricare il primo chunk:

$
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 @-

La richiesta richiede queste intestazioni:

content-type: lo stesso valore del tipo MIME utilizzato durante la creazione della risorsa x-amz-acl: per le autorizzazioni di AWS S3, va impostato sempre su private

Se un caricamento riesce, viene restituito quanto segue:

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

Allo stesso modo, carica il secondo chunk:

$
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 @-

Al termine di entrambi i caricamenti, la risorsa dovrebbe essere riproducibile in Frame.io! 🎉

Mettere tutto insieme

Ecco un esempio di pseudocodice semplificato simile a Python per il processo di caricamento completo:

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)

Questo esempio dimostra il flusso di base senza gestione degli errori o caricamenti paralleli, che saranno trattati nelle guide su gestione degli errori e caricamenti avanzati.

Passaggi successivi

Complimenti! Hai caricato la tua prima risorsa su Frame.io! La guida ai caricamenti avanzati coprirà delle tecniche più sofisticate e requisiti per implementazioni pronte per la produzione. Ti invitiamo a contattare il nostro team per qualsiasi domanda e a procedere con la guida ai caricamenti in tempo reale per imparare come caricare le risorse mentre vengono create.