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 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 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 MIME di application/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 HTTP X-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 HTTP X-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 risorsa video 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 risposta 5xx 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 intestazione 0-999999 indica che sono stati caricati i primi 1,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 valore FIRST_BYTE dal valore TOTAL_CONTENT_LENGTH. Entrambi i valori sono 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 zero del numero di byte da cui stai riprendendo il caricamento. Questo valore è un numero superiore al secondo numero nell'intestazione Range recuperato nel passaggio precedente. Nell'esempio precedente, il valore dell'intestazione Range era 0-999999, quindi il primo byte in un caricamento successivo ripristinato sarebbe 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 nel file. Ad esempio, se le dimensioni del file fossero di 3000000 byte, l'ultimo byte nel file sarà 2999999.
- TOTAL_CONTENT_LENGTH: le dimensioni totali del file video in byte. Questo valore è uguale all'intestazione Content-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'intestazione Range nel passaggio 4.2.

Pertanto, se l'ultimo byte nell'intestazione Range è 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'intestazione Content-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.