Puoi caricare i video in modo più affidabile utilizzando il protocollo di caricamento ripristinabile per le API di Google. Questo protocollo consente di riprendere un'operazione di caricamento dopo un'interruzione della rete o un altro errore di trasmissione, risparmiando tempo e larghezza di banda in caso di errori di rete.
L'utilizzo dei caricamenti ripristinabili è particolarmente utile in uno dei seguenti casi:
- Stai trasferendo file di grandi dimensioni.
- La probabilità di interruzione della rete è elevata.
- I caricamenti provengono da un dispositivo con connessione a Internet a bassa larghezza di banda o instabile, ad esempio un dispositivo mobile.
Questa guida spiega la sequenza delle richieste HTTP che un'applicazione esegue per caricare video utilizzando un processo di caricamento ripristinabile. Questa guida è rivolta principalmente agli sviluppatori che non possono utilizzare le librerie client dell'API di Google, alcune delle quali forniscono un supporto nativo per i caricamenti ripristinabili. In effetti, la guida relativa all'API YouTube Data - Caricamento di un video spiega come utilizzare la libreria client delle API di Google per Python per caricare un video utilizzando una procedura di caricamento ripristinabile.
Nota:puoi anche visualizzare la serie di richieste di caricamento ripristinabile o qualsiasi altra operazione dell'API utilizzando una delle librerie client dell'API di Google con il logging HTTPS attivato. Ad esempio, per abilitare la traccia HTTP per Python, utilizza la libreria httplib2
:
httplib2.debuglevel = 4
Passaggio 1 - Avvia una sessione ripristinabile
Per avviare un caricamento di video ripristinabile, invia una richiesta POST al seguente URL. Nell'URL, imposta il valore del parametro part
sul valore appropriato per la tua richiesta. Ricorda che il valore del parametro identifica le parti che contengono le proprietà che stai impostando e anche le parti che vuoi che la risposta dell'API includa. I valori dei parametri nell'URL della richiesta devono essere codificati nell'URL.
https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS
Imposta il corpo della richiesta su una risorsa video
. Imposta anche le seguenti intestazioni di richiesta HTTP:
Authorization
: il token di autorizzazione per la richiesta.Content-Length
: il numero di byte forniti nel corpo della richiesta. Tieni presente che non è necessario fornire questa intestazione se utilizzi la codifica trasferita.Content-Type
: imposta il valore suapplication/json; charset=UTF-8
.X-Upload-Content-Length
: il numero di byte che verranno caricati nelle richieste successive. Imposta questo valore sulle dimensioni del file che stai caricando.x-upload-content-type
: il tipo MIME del file che stai caricando. Puoi caricare file con qualsiasi tipo MIME video (video/*
) o MIME diapplication/octet-stream
.
L'esempio seguente mostra come avviare una sessione per il caricamento di un video. La richiesta imposta (e recupera) le proprietà nelle parti snippet
e status
della risorsa video
e recupera anche le proprietà nella parte contentdetails
della risorsa.
post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1 host: www.googleapis.com authorization: bearer auth_token content-length: content_length content-type: application/json; charset=utf-8 x-upload-content-length: x_upload_content_length X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE video resource
L'esempio seguente mostra una richiesta POST che contiene tutti questi valori ad eccezione del token di autenticazione. Il valore categoryId
nell'esempio corrisponde a una categoria di video. L'elenco delle categorie supportate può essere recuperato utilizzando il metodo videoCategories.list
dell'API.
POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1 Host: www.googleapis.com Authorization: Bearer AUTH_TOKEN Content-Length: 278 Content-Type: application/json; charset=UTF-8 X-Upload-Content-Length: 3000000 X-Upload-Content-Type: video/* { "snippet": { "title": "My video title", "description": "This is a description of my video", "tags": ["cool", "video", "more keywords"], "categoryId": 22 }, "status": { "privacyStatus": "public", "embeddable": True, "license": "youtube" } }
Passaggio 2: salva l'URI di sessione ripristinabile
Se la richiesta ha esito positivo, il server API risponderà con un codice di stato HTTP 200
(OK
) e la risposta includerà un'intestazione HTTP Location
che specifica l'URI della sessione ripristinabile. Questo è l'URI che utilizzerai per caricare il file video.
L'esempio seguente mostra una risposta API di esempio alla richiesta nel passaggio 1:
HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails Content-Length: 0
Passaggio 3: carica il file video
Dopo aver estratto l'URI della sessione dalla risposta dell'API, devi caricare i contenuti del file video effettivi in quella posizione. Il corpo della richiesta è il contenuto del file binario del video che stai caricando. L'esempio seguente mostra il formato della richiesta.
PUT UPLOAD_URL HTTP/1.1 Authorization: Bearer AUTH_TOKEN Content-Length: CONTENT_LENGTH Content-Type: CONTENT_TYPE BINARY_FILE_DATA
La richiesta imposta le seguenti intestazioni di richiesta HTTP:
Authorization
: il token di autorizzazione per la richiesta.Content-Length
: le dimensioni del file che stai caricando. Questo valore deve essere uguale al valore dell'intestazione della richiesta HTTPX-Upload-Content-Length
nel passaggio 1.Content-Type
: il tipo MIME del file che stai caricando. Questo valore deve essere uguale al valore dell'intestazione della richiesta HTTPX-Upload-Content-Type
nel passaggio 1.
Passaggio 4: completa la procedura di caricamento
La tua richiesta comporterà uno dei seguenti scenari:
-
Il caricamento è andato a buon fine.
Il server API risponde con un codice di risposta HTTP
201
(Created
). Il corpo della risposta è la risorsavideo
che hai creato. -
Il caricamento non è riuscito, ma puoi riprenderlo.
Dovresti riuscire a riprendere un caricamento in uno dei seguenti casi:
-
La richiesta è stata interrotta perché la connessione tra l'applicazione e il server API è interrotta. In questo caso, non riceverai una risposta dell'API.
-
La risposta dell'API specifica uno dei seguenti codici di risposta
5xx
. Il codice deve utilizzare una strategia di backoff esponenziale quando riprendi i caricamenti dopo aver ricevuto uno di questi codici di risposta.500
-Internal Server Error
502
-Bad Gateway
503
-Service Unavailable
504
-Gateway Timeout
Per riprendere un caricamento, segui le istruzioni per il controllo dello stato del caricamento e per riprendere un caricamento di seguito. Ricorda che ogni URI di sessione ripristinabile ha una durata limitata e alla fine scade. Per questo motivo ti consigliamo di avviare un caricamento ripristinabile non appena ottieni l'URI della sessione e di riprendere un caricamento interrotto subito dopo l'interruzione.
-
-
Il caricamento non è riuscito definitivamente.
Nel caso di un caricamento non riuscito, la risposta contiene una risposta di errore che spiega la causa dell'errore. Se il caricamento non va a buon fine, la risposta dell'API avrà un codice di risposta
4xx
o un codice di risposta5xx
diverso da quelli elencati sopra.Se invii una richiesta con un URI di sessione scaduto, il server restituisce un codice di risposta HTTP
404
(Not Found
). In questo caso, dovrai avviare un nuovo caricamento ripristinabile, ottenere un nuovo URI di sessione e avviare il caricamento dall'inizio utilizzando il nuovo URI.
Passaggio 4.1: controlla lo stato di un caricamento
Per controllare lo stato di un caricamento ripristinabile interrotto, invia una richiesta PUT vuota all'URL di caricamento recuperato nel passaggio 2 e utilizzato anche nel passaggio 3. Nella tua richiesta, imposta il valore dell'intestazione Content-Range
su bytes */CONTENT_LENGTH
, dove CONTENT_LENGTH corrisponde alle dimensioni del file che stai caricando.
PUT UPLOAD_URL HTTP/1.1 Authorization: Bearer AUTH_TOKEN Content-Length: 0 Content-Range: bytes */CONTENT_LENGTH
Passaggio 4.2: elabora la risposta dell'API
Se il caricamento è già stato completato, indipendentemente dal fatto che il caricamento sia riuscito o meno, l'API restituirà la stessa risposta inviata quando il caricamento è stato completato in origine.
Tuttavia, se il caricamento è stato interrotto o è ancora in corso, la risposta dell'API conterrà il codice di risposta HTTP 308
(Resume Incomplete
). Nella risposta, l'intestazione Range
specifica il numero di byte del file già caricati.
- Il valore dell'intestazione è indicizzato da
0
. Pertanto, un valore di intestazione0-999999
indica che sono stati caricati i primi1,000,000
byte del file. - Se non è stato ancora caricato nulla, la risposta dell'API non includerà l'intestazione
Range
.
La risposta di esempio di seguito mostra il formato di una risposta API per un caricamento ripristinabile:
308 Resume Incomplete Content-Length: 0 Range: bytes=0-999999
Se la risposta dell'API include anche l'intestazione Retry-After
, utilizza il valore di quell'intestazione per determinare quando tentare di riprendere il caricamento.
Passaggio 4.3: ripristina il caricamento
Per riprendere il caricamento, invia un'altra richiesta PUT
all'URL di caricamento acquisito nel passaggio 2. Imposta il corpo della richiesta sul codice binario della parte del file video che non è stata ancora caricata.
PUT UPLOAD_URL HTTP/1.1 Authorization: Bearer AUTH_TOKEN Content-Length: REMAINING_CONTENT_LENGTH Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH PARTIAL_BINARY_FILE_DATA
Devi impostare le seguenti intestazioni di richiesta HTTP:
-
Authorization
: il token di autorizzazione per la richiesta. -
Content-Length
: le dimensioni, in byte, dei contenuti non ancora caricati. Se carichi il resto di un file, puoi calcolare questo valore sottraendo il valoreFIRST_BYTE
dal valoreTOTAL_CONTENT_LENGTH
. Entrambi i valori sono utilizzati nell'intestazioneContent-Range
. -
Content-Range
: la parte del file che stai caricando. Il valore dell'intestazione è composto da tre valori:-
FIRST_BYTE
: l'indice numerico basato su zero del numero di byte da cui stai riprendendo il caricamento. Questo valore è un numero superiore al secondo numero nell'intestazioneRange
recuperato nel passaggio precedente. Nell'esempio precedente, il valore dell'intestazioneRange
era0-999999
, quindi il primo byte in un caricamento successivo ripristinato sarebbe1000000
. -
LAST_BYTE
: l'indice numerico basato su 0 dell'ultimo byte del file binario che stai caricando. In genere, si tratta dell'ultimo byte nel file. Ad esempio, se le dimensioni del file fossero di3000000
byte, l'ultimo byte nel file sarà2999999
. -
TOTAL_CONTENT_LENGTH
: le dimensioni totali del file video in byte. Questo valore è uguale all'intestazioneContent-Length
specificata nella richiesta di caricamento originale.
Nota: non è possibile caricare un blocco non continuo del file binario. Se provi a caricare un blocco non continuo, non verrà caricato alcun contenuto binario rimanente.
Pertanto, il primo byte caricato in un caricamento ripristinato deve essere il successivo dopo l'ultimo byte già caricato su YouTube. Consulta la discussione dell'intestazioneRange
nel passaggio 4.2.
Pertanto, se l'ultimo byte nell'intestazioneRange
è999999
, il primo byte nella richiesta per riprendere il caricamento deve essere 1000000. Entrambi i numeri utilizzano un indice basato su 0. Se tenti di riprendere il caricamento a partire da un byte 999.999 o inferiore (byte sovrapposti) o superiore o superiore a 100.001 byte (byte ignorati), nessuno dei contenuti binari verrà caricato. -
Carica un file in blocchi
Anziché tentare di caricare un intero file e di riprendere il caricamento in caso di interruzione della rete, l'applicazione può suddividere il file in blocchi e inviare una serie di richieste per caricare i blocchi in sequenza. Questo approccio è raramente necessario e in realtà è sconsigliato perché richiede richieste aggiuntive, che hanno implicazioni in termini di prestazioni. Tuttavia, potrebbe essere utile se stai cercando di visualizzare un indicatore di avanzamento su una rete molto instabile.
Le istruzioni per caricare un file in blocchi sono praticamente identiche alla procedura di quattro passaggi descritta in precedenza in questa guida. Tuttavia, le richieste per iniziare il caricamento di un file (passaggio 3 sopra) e per riprendere un caricamento (passaggio 4.3 precedente) impostano i valori dell'intestazione Content-Length
e Content-Range
in modo diverso quando viene caricato a blocchi.
-
Il valore dell'intestazione
Content-Length
specifica la dimensione del blocco che viene inviato dalla richiesta. Nota le seguenti limitazioni relative alle dimensioni dei blocchi:-
Le dimensioni del blocco devono essere un multiplo di 256 kB. Questa restrizione non si applica all'ultimo blocco perché le dimensioni dell'intero file non possono essere un multiplo di 256 kB. Ricorda che i blocchi più grandi sono più efficienti.
-
La dimensione del blocco deve essere la stessa per ogni richiesta nella sequenza di caricamento, ad eccezione dell'ultima richiesta, che specifica le dimensioni del blocco finale.
-
-
L'intestazione
Content-Range
specifica i byte nel file che è in corso il caricamento della richiesta. Le istruzioni per impostare l'intestazioneContent-Range
nel passaggio 4.3 sono valide durante l'impostazione di questo valore.Ad esempio, un valore
bytes 0-524287/2000000
indica che la richiesta sta inviando i primi 524.288 byte (256 x 2048) in un file da 2.000.000 di byte.
L'esempio seguente mostra il formato della prima di una serie di richieste che caricheranno un blocco di 2.000.000 byte in blocchi:
PUT UPLOAD_URL HTTP/1.1 Authorization: Bearer AUTH_TOKEN Content-Length: 524888 Content-Type: video/* Content-Range: bytes 0-524287/2000000 {bytes 0-524287}
Se una richiesta diversa da quella finale ha esito positivo, il server API risponde con una risposta 308
(Resume Incomplete
). Il formato della risposta sarà lo stesso descritto nel Passaggio 4.2: elabora la risposta dell'API sopra.
Usa il valore superiore restituito nell'intestazione Range
della risposta API per determinare da dove iniziare il blocco successivo. Continua a inviare richieste PUT
, come descritto nel Passaggio 4.3: ripristina il caricamento, per caricare i successivi blocchi di file fino al caricamento dell'intero file.
Una volta caricato l'intero file, il server risponde con un codice di risposta HTTP 201
(Created
) e restituisce le parti richieste della risorsa video appena creata.
Se una richiesta viene interrotta o l'applicazione riceve un codice di risposta 5xx
, segui la procedura illustrata nel passaggio 4 per completare il caricamento. Tuttavia, invece di tentare di caricare il resto del file, continua a caricare i blocchi dal punto in cui stai riprendendo il caricamento. Assicurati di controllare lo stato del caricamento per stabilire dove riprendere il caricamento. Non dare per scontato che il server abbia ricevuto tutti (o nessuno) i byte inviati nella richiesta precedente.
Nota: puoi anche richiedere lo stato di un caricamento attivo tra blocchi caricati. Non è necessario interrompere il caricamento prima di poterne recuperare lo stato.