Carica contenuti multimediali

La funzionalità di caricamento di contenuti multimediali consente all'API di Campaign Manager 360 di archiviare i dati nel cloud e di renderli disponibili al server. I dati che possono essere caricati includono foto, video, file PDF, file ZIP o qualsiasi altro tipo di dati.

Gli esempi riportati in questo documento mostrano l'utilizzo del caricamento di contenuti multimediali per un'API fittizia di Farm. Tuttavia, gli stessi concetti valgono per l'API Campaign Manager 360.

Opzioni relative al caricamento

L'API Campaign Manager 360 consente di caricare determinati tipi di dati binari o i contenuti multimediali. Le caratteristiche specifiche dei dati che puoi caricare sono specificate nella pagina di riferimento per qualsiasi metodo che supporta i caricamenti multimediali:

  • Dimensioni massime del file di caricamento: la quantità massima di dati che puoi archiviare con questo metodo.
  • Tipi MIME dei contenuti multimediali accettati: i tipi di dati binari che puoi archiviare utilizzando questo metodo.

Puoi effettuare richieste di caricamento in uno dei seguenti modi. Specifica il metodo utilizzato con il parametro di richiesta uploadType.

  • Caricamento semplice: uploadType=media. Per il trasferimento rapido di file più piccoli, ad esempio non più di 5 MB
  • Caricamento a più parti: uploadType=multipart. Per un trasferimento rapido di file e metadati più piccoli; trasferisci il file insieme ai metadati che lo descrivono, il tutto in un'unica richiesta.
  • Caricamento possibile: uploadType=resumable. Per un trasferimento affidabile, soprattutto in caso di file più grandi. Con questo metodo, utilizzi una richiesta di avvio di sessione, che facoltativamente può includere metadati. Si tratta di una buona strategia da utilizzare per la maggior parte delle applicazioni, poiché funziona anche per file più piccoli al costo di una richiesta HTTP aggiuntiva per caricamento.

Quando carichi contenuti multimediali, devi utilizzare un URI speciale. In effetti, i metodi che supportano i caricamenti multimediali hanno due endpoint URI:

  • L'URI /upload per i contenuti multimediali. Il formato dell'endpoint di caricamento è l'URI della risorsa standard con un prefisso "/upload". Utilizza questo URI quando trasferisci i dati multimediali stessi.

    Esempio: POST /upload/farm/v1/animals

  • L'URI standard della risorsa per i metadati Se la risorsa contiene campi di dati, questi vengono utilizzati per archiviare i metadati che descrivono il file caricato. Puoi utilizzare questo URI quando crei o aggiorni i valori dei metadati.

    Esempio: POST /farm/v1/animals

Caricamento semplice

Il metodo più semplice per caricare un file è effettuare una semplice richiesta di caricamento. Questa opzione è una buona scelta quando:

  • Il file è abbastanza piccolo da poter essere caricato di nuovo se la connessione non riesce.
  • Non sono presenti metadati da inviare. Questa situazione può verificarsi se prevedi di inviare metadati per questa risorsa in una richiesta separata o se non sono supportati o disponibili metadati.

Per utilizzare il caricamento semplice, effettua una richiesta POST o PUT all'URI /upload del metodo e aggiungi il parametro di ricerca uploadType=media. Ad esempio:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

Le intestazioni HTTP da utilizzare per effettuare una semplice richiesta di caricamento includono:

  • Content-Type. Imposta uno dei tipi di dati multimediali per il caricamento accettati dal metodo, specificato nel riferimento dell'API.
  • Content-Length. Imposta il numero di byte caricati. Non è necessario se utilizzi la codifica di trasferimento in blocchi.

Esempio: caricamento semplice

L'esempio seguente mostra l'utilizzo di una semplice richiesta di caricamento per l'API fittizia Farm.

POST /upload/farm/v1/animals?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

JPEG data

Se la richiesta ha esito positivo, il server restituisce il codice di stato HTTP 200 OK insieme a tutti i metadati:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

Caricamento a più parti

Se hai metadati che vuoi inviare insieme ai dati da caricare, puoi effettuare una singola richiesta multipart/related. Si tratta di una scelta vantaggiosa se i dati che invii sono sufficientemente piccoli per essere caricati di nuovo completamente, se la connessione non riesce.

Per utilizzare il caricamento a più parti, effettua una richiesta POST o PUT all'URI /upload del metodo e aggiungi il parametro di ricerca uploadType=multipart, ad esempio:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

Le intestazioni HTTP di primo livello da utilizzare quando si effettua una richiesta di caricamento con più parti includono:

  • Content-Type. Imposta la funzione su più parti/correlate e includi la stringa di confine che utilizzi per identificare le parti della richiesta.
  • Content-Length. Imposta il numero totale di byte nel corpo della richiesta. La parte multimediale della richiesta deve essere inferiore alla dimensione massima del file specificata per questo metodo.

Il corpo della richiesta è formattato come un tipo di contenuti multipart/related [RFC2387] e contiene esattamente due parti. Le parti sono identificate da una stringa di confine e la stringa di confine finale è seguita da due trattini.

Ogni parte della richiesta con più parti richiede un'intestazione Content-Type aggiuntiva:

  1. Parte dei metadati: deve apparire per primo e Content-Type deve corrispondere a uno dei formati dei metadati accettati.
  2. Parte multimediale: deve essere secondo e Content-Type deve corrispondere a uno dei tipi MIME multimediali del metodo.

Consulta il riferimento dell'API per l'elenco dei tipi MIME multimediali e i limiti di dimensione per i file caricati.

Nota: per creare o aggiornare solo la parte dei metadati, senza caricare i dati associati, invia una richiesta POST o PUT all'endpoint standard della risorsa: https://www.googleapis.com/farm/v1/animals

Esempio: caricamento a più parti

L'esempio seguente mostra una richiesta di caricamento a più parti per l'API fittizia di Farm.

POST /upload/farm/v1/animals?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "name": "Llama"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

Se la richiesta ha esito positivo, il server restituisce il codice di stato HTTP 200 OK insieme a eventuali metadati:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

Caricamento ripristinabile

Per caricare i file di dati in modo più affidabile, puoi utilizzare il protocollo di caricamento ripristinabile. Questo protocollo consente di riprendere un'operazione di caricamento dopo che un errore di comunicazione ha interrotto il flusso di dati. Questo metodo è particolarmente utile in caso di trasferimento di file di grandi dimensioni e la probabilità di un'interruzione della rete o qualche altro errore di trasmissione, ad esempio durante il caricamento da un'app client per dispositivi mobili, può anche ridurre l'utilizzo della larghezza di banda in caso di errori della rete, poiché non è necessario riavviare i caricamenti di file di grandi dimensioni dall'inizio.

Ecco i passaggi per utilizzare il caricamento ripristinabile:

  1. Avvia una sessione ripristinabile. Invia una richiesta iniziale all'URI di caricamento che include i metadati, se presenti.
  2. Salva l'URI della sessione ripristinabile. Salva l'URI della sessione restituito nella risposta alla richiesta iniziale; lo utilizzerai per le richieste rimanenti in questa sessione.
  3. Carica il file. Invia il file multimediale all'URI della sessione ripristinabile.

Inoltre, le app che usano il caricamento ripristinabile devono avere del codice per riprendere un caricamento interrotto. Se un caricamento viene interrotto, scopri quanti dati sono stati ricevuti correttamente e poi riprendi il caricamento a partire da quel momento.

Nota : l'URI di caricamento scade dopo una settimana.

Passaggio 1: avvia una sessione ripristinabile

Per avviare un caricamento ripristinabile, effettua una richiesta POST o PUT all'URI /upload del metodo e aggiungi il parametro di ricerca uploadType=resumable, ad esempio:

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable

In questa richiesta di avvio, il corpo è vuoto o contiene solo i metadati; trasferirai i contenuti effettivi del file che vuoi caricare nelle richieste successive.

Utilizza le seguenti intestazioni HTTP con la richiesta iniziale:

  • X-Upload-Content-Type. Imposta il tipo MIME multimediale dei dati di caricamento da trasferire nelle richieste successive.
  • X-Upload-Content-Length. Imposta il numero di byte dei dati di caricamento da trasferire nelle richieste successive. Se la lunghezza non è nota al momento della richiesta, puoi omettere questa intestazione.
  • Se fornisci metadati: Content-Type. Impostato in base al tipo di dati dei metadati.
  • Content-Length. Impostalo sul numero di byte forniti nel corpo di questa richiesta iniziale. Non è necessario se utilizzi la codifica di trasferimento in blocchi.

Consulta il riferimento dell'API per l'elenco dei tipi MIME multimediali e i limiti di dimensione per i file caricati.

Esempio: richiesta di avvio di sessione ripristinabile

L'esempio seguente mostra come avviare una sessione ripristinabile per l'API fittizia di Farm.

POST /upload/farm/v1/animals?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/jpeg
X-Upload-Content-Length: 2000000

{
  "name": "Llama"
}

Nota: per una richiesta di aggiornamento iniziale ripristinabile senza metadati, lascia il corpo della richiesta vuoto e imposta l'intestazione Content-Length su 0.

Nella sezione successiva viene descritto come gestire la risposta.

Passaggio 2: salva l'URI della sessione ripristinabile

Se la richiesta di avvio della sessione ha esito positivo, il server API risponde con un codice di stato HTTP 200 OK. Inoltre, fornisce un'intestazione Location che specifica l'URI della sessione ripristinabile. L'intestazione Location, mostrata nell'esempio di seguito, include una porzione del parametro di ricerca upload_id che fornisce l'ID caricamento univoco da utilizzare per questa sessione.

Esempio: risposta di avviamento della sessione ripristinabile

Ecco la risposta alla richiesta riportata nel passaggio 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

Il valore dell'intestazione Location, come mostrato nella risposta di esempio riportata sopra, è l'URI della sessione che utilizzerai come endpoint HTTP per eseguire il caricamento effettivo del file o eseguire una query sullo stato di caricamento.

Copia e salva l'URI della sessione per poterlo utilizzare per le richieste successive.

Passaggio 3. Carica il file

Per caricare il file, invia una richiesta PUT all'URI di caricamento ottenuto nel passaggio precedente. Il formato della richiesta di caricamento è:

PUT session_uri

Le intestazioni HTTP da utilizzare per effettuare le richieste di caricamento di file ripristinabili includono Content-Length. Impostalo sul numero di byte caricati in questa richiesta, che in genere corrisponde alle dimensioni del file di caricamento.

Esempio: richiesta di caricamento di file ripristinabile

Ecco una richiesta di ripristino per il caricamento dell'intero file JPEG da 2.000.000 byte per l'esempio corrente.

PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

bytes 0-1999999

Se la richiesta ha esito positivo, il server risponde con un HTTP 201 Created, insieme a tutti i metadati associati a questa risorsa. Se la richiesta iniziale della sessione ripristinabile era una PUT, per aggiornare una risorsa esistente, la risposta corretta sarebbe 200 OK, insieme a eventuali metadati associati a questa risorsa.

Se la richiesta di caricamento viene interrotta o se ricevi dal server una risposta HTTP 503 Service Unavailable o qualsiasi altra risposta 5xx, segui la procedura descritta nella sezione Riprendere un caricamento interrotto.  

Caricamento del file in blocchi

Con i caricamenti ripristinabili, puoi suddividere un file in blocchi e inviare una serie di richieste per caricare ogni blocco in sequenza. Questo non è l'approccio preferito poiché esistono costi di rendimento associati alle richieste aggiuntive e in genere non è necessario. Tuttavia, potrebbe essere necessario utilizzare il blocco per ridurre la quantità di dati trasferiti in ogni singola richiesta. Questo è utile quando esiste un limite di tempo fisso per le singole richieste, come per alcuni tipi di richieste di Google App Engine. Ti consente inoltre di fornire indicazioni relative all'avanzamento del caricamento per i browser precedenti che non hanno il supporto dell'avanzamento del caricamento per impostazione predefinita.

Riprendi un caricamento interrotto

Se una richiesta di caricamento viene terminata prima di ricevere una risposta o se ricevi una risposta HTTP 503 Service Unavailable dal server, devi riprendere il caricamento interrotto. Per farlo:

  1. Stato richiesta. Per eseguire query sullo stato attuale del caricamento, invia una richiesta PUT vuota all'URI di caricamento. Per questa richiesta, le intestazioni HTTP devono includere un'intestazione Content-Range che indichi che la posizione corrente nel file è sconosciuta. Ad esempio, imposta Content-Range su */2000000 se la lunghezza totale del file è 2.000.000. Se non conosci le dimensioni complete del file, imposta Content-Range su */*.

    Nota: puoi richiedere lo stato tra blocchi, non solo se il caricamento viene interrotto. Questa opzione è utile, ad esempio, se vuoi visualizzare indicazioni di avanzamento del caricamento per i browser precedenti.

  2. Numero di byte caricati. Elabora la risposta dalla query di stato. Il server utilizza l'intestazione Range nella risposta per specificare i byte ricevuti finora. Ad esempio, un'intestazione Range di 0-299999 indica che sono stati ricevuti i primi 300.000 byte del file.
  3. Carica i dati rimanenti. Infine, ora che sai dove riprendere la richiesta, invia i dati rimanenti o il blocco corrente. Tieni presente che, in entrambi i casi, devi gestire i dati rimanenti come un blocco a parte, quindi dovrai inviare l'intestazione Content-Range quando riprendi il caricamento.
Esempio: riprendere un caricamento interrotto

1) Richiedi lo stato di caricamento.

La richiesta seguente utilizza l'intestazione Content-Range per indicare che la posizione corrente nel file da 2.000.000 di byte è sconosciuta.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Estrai il numero di byte caricati finora dalla risposta.

La risposta del server utilizza l'intestazione Range per indicare che finora ha ricevuto i primi 43 byte del file. Usa il valore superiore dell'intestazione Range per determinare da dove iniziare il caricamento.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

Nota : è possibile che la risposta dello stato sia 201 Created o 200 OK se il caricamento è completo. Questo può accadere se la connessione si è interrotta dopo che sono stati caricati tutti i byte, ma prima che il client ricevesse una risposta dal server.

3) Riprendi il caricamento dal punto in cui era stato interrotto.

La richiesta seguente riprende il caricamento inviando i byte rimanenti del file, a partire dal byte 43.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

Best practice

Quando carichi contenuti multimediali, è utile conoscere alcune best practice relative alla gestione degli errori.

  • Riprendi o riprova a caricare i video non riusciti a causa di interruzioni della connessione o errori di 5xx, tra cui:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Utilizza una strategia di backoff esponenziale se viene restituito un errore del server 5xx durante il ripristino o il tentativo di caricamento di nuove richieste. Questi errori possono verificarsi se un server si sovraccarica. Il backoff esponenziale può aiutare ad alleviare questo tipo di problemi durante i periodi di traffico elevato delle richieste o di traffico di rete intenso.
  • Altri tipi di richieste non dovrebbero essere gestiti da backoff esponenziale, ma puoi comunque riprovare più volte. Quando riprovi queste richieste, limita il numero di nuove tentativi. Ad esempio, il codice potrebbe limitare a dieci nuovi tentativi prima di segnalare un errore.
  • Gestisci gli errori 404 Not Found e 410 Gone quando esegui caricamenti ripristinabili, avviando l'intero caricamento dall'inizio.

Backoff esponenziale

Il backoff esponenziale è una strategia di gestione degli errori standard per le applicazioni di rete in cui il client tenta periodicamente di completare una richiesta non riuscita per un periodo di tempo crescente. Se un volume elevato di richieste o un traffico di rete elevato fa sì che il server restituisca errori, il backoff esponenziale potrebbe essere una buona strategia per gestirli. Al contrario, non è una strategia pertinente per gestire errori non correlati al volume di rete o ai tempi di risposta, come credenziali di autorizzazione non valide o errori di tipo file non trovato.

Se utilizzato correttamente, il backoff esponenziale aumenta l'efficienza dell'utilizzo della larghezza di banda, riduce il numero di richieste richieste per ottenere una risposta corretta e massimizza la velocità effettiva delle richieste in ambienti simultanei.

Il flusso per l'implementazione di un backoff esponenziale semplice è il seguente:

  1. Inviare una richiesta all'API.
  2. Ricevi una risposta HTTP 503 che indica che devi riprovare la richiesta.
  3. Attendi un secondo + numero_casuale_di_millisecondi e riprova la richiesta.
  4. Ricevi una risposta HTTP 503 che indica che devi riprovare la richiesta.
  5. Attendi 2 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
  6. Ricevi una risposta HTTP 503 che indica che devi riprovare la richiesta.
  7. Attendi 4 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
  8. Ricevi una risposta HTTP 503 che indica che devi riprovare la richiesta.
  9. Attendi 8 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
  10. Ricevi una risposta HTTP 503 che indica che devi riprovare la richiesta.
  11. Attendi 16 secondi + numero_casuale_di_millisecondi e riprova la richiesta.
  12. Interrompi. Segnala o registra un errore.

Nel flusso riportato sopra, numero_casuale_di_millisecondi è un numero casuale di millisecondi inferiore o uguale a 1000. Questo è necessario, dal momento che l'introduzione di un piccolo ritardo casuale aiuta a distribuire il carico in modo più uniforme ed evitare la possibilità di timbrare il server. Il valore di random_number_milliseconds deve essere ridefinito dopo ogni attesa.

Nota: l'attesa è sempre (2 ^ n) + numero_casuale_millisecondi, dove n è un numero intero che aumenta in modo monotonico inizialmente definito come 0. Il numero intero n viene incrementato di 1 per ogni iterazione (ogni richiesta).

L'algoritmo è impostato in modo da terminare quando n è 5. Questo limite impedisce ai client di riprovare infinitamente e genera un ritardo totale di circa 32 secondi prima che una richiesta venga considerata "un errore irreversibile". Un numero massimo di nuovi tentativi è accettabile, soprattutto se è in corso un caricamento lungo. Assicurati solo di limitare il ritardo del nuovo tentativo in modo ragionevole, ad esempio meno di un minuto.

Guide alla libreria client delle API