> This page is for Da videocamera a cloud.
> 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.
# 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](./implementing-c2c-setting-up) prima di procedere.Avrai bisogno dell'`access_token` ottenuto durante il [processo di autenticazione e autorizzazione](./implementing-c2c-authentication-and-authorization).Per questa guida, utilizzeremo una risorsa test di esempio disponibile su [questo link a Frame.io](https://f.io/Rq1q5CzB). 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](https://f.io/Rq1q5CzB), che supponiamo sia stato creato 10 secondi fa. Per prima cosa, dobbiamo creare un riferimento alla risorsa in Frame.io:
```shell
{
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
```
La documentazione per `/v2/devices/assets` è [disponibile qui](/camera-to-cloud/api-reference/device-asset-create).Sebbene l'endpoint precedente `/v2/assets` funzioni ancora, consigliamo alle nuove integrazioni di utilizzare `/v2/devices/assets`.
A differenza degli endpoint di autenticazione utilizzati in precedenza, questo endpoint accetta la codifica `application/json` anziché `form/multipart`. Accetta anche `application/x-www-form-urlencoded`.
Questo esempio utilizza [heredoc](https://linuxize.com/post/bash-heredoc/) per fornire il payload JSON a `curl` in un formato multi-riga leggibile. Il parametro `--data-binary @-` indica a `curl` di leggere i dati raw da stdin. Scopri di più su questa estensione [qui](https://unix.stackexchange.com/questions/88490/how-do-you-use-output-redirection-in-combination-with-here-documents-and-cat).
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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) del file. La maggior parte dei linguaggi di programmazione fornisce utilità per il rilevamento del tipo MIME (esempi: [Go](https://golangcode.com/get-the-content-type-of-file/), [Python](https://docs.python.org/3/library/mimetypes.html)). `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](./how-to-advanced-uploads).
La risposta sarà simile a questa (alcuni campi sono omessi):
```json
{
"_type": "file",
...
"id": "9a280f99-8f4f-46b0-a4b4-ec4c2f95138e",
...
"upload_urls": [
"https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_01_path]",
"https://frameio-uploads-production.s3-accelerate.amazonaws.com/parts/[part_02_path]"
],
...
}
```
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](./how-to-advanced-uploads))
Per determinare la dimensione ottimale del chunk, usa questa formula:
**`Python`**
```python title="Python"
# We use math.ceil() to ensure we get the upper bound in the division
chunk_size = math.ceil(float(file.size) / float(len(response.upload_urls)))
```
Per il file di esempio, il calcolo è:
**`Python`**
```python title="Python"
math.ceil(21136250 / 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](./how-to-advanced-uploads).
Poiché le dimensioni dei file raramente si dividono in modo uniforme, il chunk finale può essere più piccolo del valore calcolato di `chunk_size`. L'implementazione deve tenere conto di questo aspetto durante la lettura dei chunk di file.
Per questa dimostrazione, useremo i comandi [head](https://man7.org/linux/man-pages/man1/head.1.html) e [tail](https://man7.org/linux/man-pages/man1/tail.1.html) per estrarre i chunk di file.
## Passaggio 3: caricamento dei chunk
Per caricare il primo chunk:
```shell
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 @-
```
Il parametro `--data-binary @-` indica a `curl` di utilizzare i dati raw da stdin, che provengono dal comando `head`.
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:
```text
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
...
```
Allo stesso modo, carica il secondo chunk:
```shell
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! 🎉
Durante il caricamento dei chunk, i dati vengono inviati direttamente ad AWS S3, non all'API di Frame.io. Le risposte di errore seguiranno i formati di AWS S3, anziché gli errori standard di Frame.io. Tratteremo la gestione degli errori di S3 nella [guida alla gestione degli errori](/camera-to-cloud/how-to-handle-errors).
Benché concettualmente sia più semplice caricare i chunk in sequenza, in realtà possono essere caricati in qualsiasi ordine. Il sistema li assemblerà correttamente a prescindere dalla sequenza di caricamento.
## Mettere tutto insieme
Ecco un esempio di pseudocodice semplificato simile a Python per il processo di caricamento completo:
**`Python`**
```python title="Python"
file = open("~/Downloads/C2C_TEST_CLIP.mp4")
mimetype = mimetypes.for_file("~/Downloads/C2C_TEST_CLIP.mp4")[0]
created_at = time.ctime(file.stat.ST_CTIME)
asset = c2c.asset_create(
name="C2C_TEST_CLIP.mp4",
filetype=mimetype,
filesize=file.size,
offset=datetime.now() - created_at,
channel=0,
)
chunk_size = math.ceil(float(file.size) / float(len(asset.upload_urls)))
for chunk_url in asset.upload_urls:
chunk = file.read(bytes=chunk_size)
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](/camera-to-cloud/how-to-handle-errors) e [caricamenti avanzati](./how-to-advanced-uploads).
## Passaggi successivi
Complimenti! Hai caricato la tua prima risorsa su Frame.io! La [guida ai caricamenti avanzati](./how-to-advanced-uploads) 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](./how-to-upload-realtime) per imparare come caricare le risorse mentre vengono create.