Questa pagina è stata tradotta dall'API Cloud Translation.

Caricamenti ripristinabili

Puoi caricare i video in modo più affidabile utilizzando il protocollo di caricamento ripristinabile per le API Google. Questo protocollo ti 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 guasti della rete.

L'utilizzo dei caricamenti riavviabili è particolarmente utile nei seguenti casi:

Stai trasferendo file di grandi dimensioni.
La probabilità di un'interruzione della rete è elevata.
I caricamenti provengono da un dispositivo con una larghezza di banda ridotta o una connessione a internet instabile, ad esempio un dispositivo mobile.

Questa guida spiega la sequenza di richieste HTTP inviate da un'applicazione per caricare i video utilizzando un processo di caricamento ripristinabile. Questa guida è rivolta principalmente agli sviluppatori che non possono utilizzare le librerie client delle API di Google, alcune delle quali forniscono il supporto nativo per i caricamenti riavviabili. Infatti, la guida API YouTube Data - Caricamento di un video spiega come utilizzare la libreria client delle API di Google per Python per caricare un video utilizzando un processo di caricamento riassumibile.

Nota:puoi anche visualizzare la serie di richieste effettuate per il caricamento riavviabile o qualsiasi altra operazione dell'API utilizzando una delle librerie client dell'API di Google con la generazione di log HTTPS abilitata. Ad esempio, per attivare la traccia HTTP per Python, utilizza la libreria httplib2:

httplib2.debuglevel = 4

Passaggio 1: avvia una sessione riassumibile

Per avviare un caricamento del video con possibilità di ripresa, invia una richiesta POST al seguente URL. Nell'URL, imposta il valore del parametro part sul valore appropriato per la richiesta. Ricorda che il valore del parametro identifica le parti che contengono le proprietà che stai impostando e anche le parti che vuoi che vengano incluse nella risposta dell'API. 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 specificati nel corpo della richiesta. Tieni presente che non devi fornire questa intestazione se utilizzi la codifica di trasferimento suddivisa in blocchi.
Content-Type: imposta il valore su application/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 con un tipo MIME application/octet-stream.

L'esempio seguente mostra come avviare una sessione riassumibile per il caricamento di un video. La richiesta imposta (e recupererà) le proprietà nelle parti snippet e status della risorsa video e recupererà 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 in cui sono stati inseriti 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 della sessione riassumibile

Se la richiesta va a buon fine, il server API risponderà con un codice di stato HTTP 200 (OK) e la risposta includerà un'intestazione HTTP Location che specifica l'URI per la sessione riassumibile. Si tratta dell'URI che utilizzerai per caricare il file video.

L'esempio seguente mostra una risposta API di esempio alla richiesta del 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 sessione dalla risposta dell'API, devi caricare i contenuti effettivi del file video in quella posizione. Il corpo della richiesta è costituito dai contenuti 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 corrispondere al valore dell'intestazione della richiesta HTTP X-Upload-Content-Length nel passaggio 1.
Content-Type: il tipo MIME del file che stai caricando. Questo valore deve corrispondere al valore dell'intestazione della richiesta HTTP X-Upload-Content-Type nel passaggio 1.

Passaggio 4: completa la procedura di caricamento

La tua richiesta porterà a 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 risorsa video che hai creato.
Il caricamento non è andato a buon fine, ma può essere ripreso.

Dovresti essere in grado di riprendere un caricamento nei seguenti casi:
- La richiesta viene 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 per riprendere 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 controllare lo stato del caricamento e riprendere un caricamento riportate di seguito. Ricorda che ogni URI sessione riavviabile ha una durata limitata e alla fine scade. Per questo motivo, ti consigliamo di avviare un caricamento con possibilità di ripresa non appena ottieni l'URI della sessione e di riprendere un caricamento interrotto poco dopo l'interruzione.
Il caricamento non è andato a buon fine definitivamente.

Per un caricamento non riuscito, la risposta contiene una risposta di errore che aiuta a spiegare la causa dell'errore. Per un caricamento che non va a buon fine definitivamente, la risposta dell'API avrà un codice di risposta 4xx o 5xx diverso da quelli elencati sopra.

Se invii una richiesta con un URI sessione scaduto, il server restituisce un codice di risposta HTTP 404 (Not Found). In questo caso, dovrai avviare un nuovo caricamento interrompibile, ottenere un nuovo URI 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 richiesta, imposta il valore dell'intestazione Content-Range su bytes */CONTENT_LENGTH, dove CONTENT_LENGTH è la dimensione 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 sia riuscito o meno, l'API restituirà la stessa risposta inviata al termine del caricamento originale.

Tuttavia, se il caricamento è stato interrotto o è ancora in corso, la risposta dell'API avrà un codice di risposta HTTP 308 (Resume Incomplete). Nella risposta, l'intestazione Range specifica quanti byte del file sono già stati caricati correttamente.

Il valore dell'intestazione è indicizzato da 0. Di conseguenza, un valore di intestazione pari a 0-999999 indica che i primi 1,000,000 byte del file sono stati caricati.
Se non è stato ancora caricato nulla, la risposta dell'API non includerà l'intestazione Range.

La risposta di esempio riportata di seguito mostra il formato di una risposta dell'API per un caricamento riavviabile:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

Se la risposta dell'API include anche l'intestazione Retry-After, utilizza il valore dell'intestazione per determinare quando tentare di riprendere il caricamento.

Passaggio 4.3: riprendi 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 non 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 che non sono ancora stati caricati. Se carichi il resto di un file, puoi calcolare questo valore sottraendo il valore FIRST_BYTE dal valore TOTAL_CONTENT_LENGTH. Entrambi i valori vengono utilizzati nell'intestazione Content-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 0 del numero di byte da cui vuoi riprendere il caricamento. Questo valore è un numero superiore al secondo numero nell'intestazione Range recuperata nel passaggio precedente. Nell'esempio precedente, il valore dell'intestazione Range era 0-999999, pertanto il primo byte in un successivo caricamento ripreso sarà 1000000.
- LAST_BYTE: l'indice numerico basato su 0 dell'ultimo byte del file binario che stai caricando. In genere, si tratta dell'ultimo byte del file. Ad esempio, se le dimensioni del file sono 3000000 byte, l'ultimo byte del file sarà il numero 2999999.
- TOTAL_CONTENT_LENGTH: le dimensioni totali del file video in byte. Questo valore corrisponde all'intestazione Content-Length specificata nella richiesta di caricamento originale.
Nota:non puoi caricare un blocco non continuo del file binario. Se provi a caricare un blocco non continuo, nessuno dei contenuti binari rimanenti verrà caricato.

Di conseguenza, il primo byte caricato in un caricamento ripreso deve essere il byte successivo all'ultimo byte già caricato correttamente su YouTube. Consulta la discussione sull'intestazione Range nel passaggio 4.2.

Pertanto, se l'ultimo byte dell'intestazione Range è 999999, il primo byte della richiesta per riprendere il caricamento deve essere il byte 1000000. Entrambi i numeri utilizzano un indice basato su 0. Se provi a riprendere il caricamento dal byte 999999 o precedente (byte sovrapposti) o dal byte 1000001 o successivo (byte saltati), nessuno dei contenuti binari verrà caricato.

Caricare un file a blocchi

Anziché provare a caricare un intero file e 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 ed è sconsigliato perché richiede richieste aggiuntive, che hanno implicazioni sul rendimento. Tuttavia, potrebbe essere utile se stai tentando di visualizzare un indicatore di avanzamento su una rete molto instabile.

Le istruzioni per il caricamento di un file in blocchi sono praticamente identiche alla procedura in quattro passaggi descritta in precedenza in questa guida. Tuttavia, le richieste per avviare il caricamento di un file (passaggio 3 sopra) e per riprendere un caricamento (passaggio 4.3 sopra) impostano entrambi i valori dell'intestazione Content-Length e Content-Range in modo diverso quando un file viene caricato a blocchi.

Il valore dell'intestazione Content-Length specifica la dimensione del chunk inviato dalla richiesta. Tieni presenti le seguenti limitazioni relative alle dimensioni dei chunk:
- La dimensione del chunk deve essere un multiplo di 256 KB. Questa limitazione non si applica all'ultimo chunk, poiché le dimensioni dell'intero file potrebbero non essere un multiplo di 256 KB. Ricorda che i chunk più grandi sono più efficienti.
- La dimensione del chunk deve essere la stessa per ogni richiesta nella sequenza di caricamento, ad eccezione dell'ultima richiesta, che specifica la dimensione del chunk finale.
L'intestazione Content-Range specifica i byte del file che la richiesta sta caricando. Le istruzioni per l'impostazione dell'intestazione Content-Range nel passaggio 4.3 sono applicabili quando si imposta questo valore.

Ad esempio, un valore bytes 0-524287/2000000 indica che la richiesta sta inviando i primi 524.288 byte (256 x 2048) di un file di 2.000.000 byte.

L'esempio seguente mostra il formato della prima di una serie di richieste che caricherà un file 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 va a buon fine, il server API risponde con 308 (Resume Incomplete). Il formato della risposta sarà lo stesso descritto nel passaggio 4.2: Elabora la risposta dell'API qui sopra.

Utilizza il valore superiore restituito nell'intestazione Range della risposta dell'API per determinare dove iniziare il blocco successivo. Continua a inviare richieste PUT, come descritto nel passaggio 4.3: Riprendi il caricamento, per caricare i blocchi di file successivi finché l'intero file non è stato caricato.

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 la tua applicazione riceve un codice di risposta 5xx, segui la procedura descritta nel passaggio 4 per completare il caricamento. Tuttavia, anziché tentare di caricare il resto del file, continua a caricare i chunk dal punto in cui hai ripreso il caricamento. Assicurati di controllare lo stato del caricamento per determinare da dove riprendere il caricamento del file. 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 i chunk caricati. Il caricamento non deve essere stato interrotto prima di poterne recuperare lo stato.