introduzione
Questo documento è destinato agli sviluppatori che desiderano scrivere applicazioni che interagiscano con YouTube. Spiega i concetti di base di YouTube e dell'API stessa. Offre inoltre una panoramica delle diverse funzioni supportate dall'API.
Prima di iniziare
-
Devi disporre di un Account Google per accedere alla console API di Google, richiedere una chiave API e registrare la tua applicazione.
-
Crea un progetto in Google Developers Console e ottieni le credenziali di autorizzazione in modo che la tua applicazione possa inviare richieste API.
-
Dopo aver creato il progetto, assicurati che l'API di dati di YouTube sia uno dei servizi per cui è registrata la tua applicazione per l'utilizzo:
- Vai alla console API e seleziona il progetto appena registrato.
- Visita la pagina API abilitate. Nell'elenco delle API, verifica che lo stato della YouTube Data v3 sia ON.
-
Se la tua applicazione utilizzerà metodi dell'API che richiedono l'autorizzazione utente, leggi la guida per l'autenticazione per imparare a implementare l'autorizzazione OAuth 2.0.
-
Seleziona una libreria client per semplificare l'implementazione dell'API.
-
Acquisisci familiarità con i concetti fondamentali del formato dati JSON (JavaScript Object Notation). JSON è un formato dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture di dati arbitrarie. Per ulteriori informazioni, visita il sito json.org.
Risorse e tipi di risorse
Una risorsa è una singola entità di dati con un identificatore univoco. La tabella seguente descrive i diversi tipi di risorse con cui puoi interagire utilizzando l'API.
Risorse | |
---|---|
activity |
Contiene informazioni relative a un'azione intrapresa da un determinato utente sul sito di YouTube. Le azioni degli utenti riportate nei feed attività includono, ad esempio, la valutazione di un video, la condivisione di un video, l'aggiunta di un video ai preferiti e la pubblicazione di un bollettino del canale. |
channel |
Contiene informazioni su un singolo canale YouTube. |
channelBanner |
Identifica l'URL da utilizzare per impostare un'immagine appena caricata come immagine del banner per un canale. |
channelSection |
Contiene informazioni su un insieme di video che un canale ha scelto di mostrare. Ad esempio, una sezione potrebbe includere gli ultimi caricamenti di un canale, i caricamenti più popolari o i video di una o più playlist. |
guideCategory |
Identifica una categoria che YouTube associa ai canali in base ai loro contenuti o ad altri indicatori, come la popolarità. Le categorie delle guide cercano di organizzare i canali in modo che gli utenti di YouTube possano trovare più facilmente i contenuti che stanno cercando. Sebbene sia possibile associare i canali a una o più categorie della guida, non è garantito che si trovino in nessuna categoria della guida. |
i18nLanguage |
Identifica una lingua della richiesta supportata dal sito web di YouTube. Il linguaggio dell'applicazione è anche noto come lingua dell'interfaccia utente. |
i18nRegion |
Identifica un'area geografica che un utente di YouTube può selezionare come regione di contenuti preferita. L'area geografica di contenuti può essere detta anche impostazioni internazionali dei contenuti. |
playlist |
Rappresenta una singola playlist di YouTube. Una playlist è una raccolta di video che possono essere visualizzati in sequenza e condivisi con altri utenti. |
playlistItem |
Identifica una risorsa, ad esempio un video, che fa parte di una playlist. La risorsa playlistItem contiene anche dettagli che spiegano in che modo la risorsa inclusa viene utilizzata nella playlist. |
search result |
Contiene informazioni su un video, un canale o una playlist di YouTube che corrispondono ai parametri di ricerca specificati in una richiesta API. Anche se un risultato di ricerca rimanda a una risorsa identificabile in modo univoco, come un video, non ha dati propri permanenti. |
subscription |
Contiene informazioni sull'iscrizione di un utente di YouTube. Un'iscrizione notifica un utente quando vengono aggiunti nuovi video a un canale o quando un altro utente intraprende una delle varie azioni su YouTube, come caricare un video, votare o commentare un video. |
thumbnail |
Identifica le immagini in miniatura associate a una risorsa. |
video |
Rappresenta un singolo video di YouTube. |
videoCategory |
Identifica una categoria che è stata o potrebbe essere associata ai video caricati. |
watermark |
Identifica un'immagine che viene visualizzata durante le riproduzioni dei video di un determinato canale. Il proprietario del canale può anche specificare un canale di destinazione a cui rimanda l'immagine, nonché dettagli sui tempi, che determinano quando verrà visualizzata la filigrana durante le riproduzioni del video e per quanto tempo sarà visibile. |
Tieni presente che, in molti casi, una risorsa contiene riferimenti ad altre risorse. Ad esempio, la proprietà snippet.resourceId.videoId
di una risorsa playlistItem
identifica una risorsa video che, a sua volta, contiene informazioni complete sul video. Per fare un altro esempio, un risultato di ricerca contiene una proprietà videoId
, playlistId
o channelId
che identifica una determinata risorsa video, playlist o canale.
Operazioni supportate
La tabella seguente mostra i metodi più comuni supportati dall'API. Alcune risorse supportano anche altri metodi che eseguono funzioni più specifiche di queste risorse. Ad esempio, il metodo videos.rate
associa una valutazione degli utenti a un video, mentre il metodo thumbnails.set
carica un'immagine in miniatura del video su YouTube e la associa a un video.
Suite operativa | |
---|---|
list |
Recupera (GET ) un elenco di zero o più risorse. |
insert |
Crea una nuova risorsa (POST ). |
update |
Modifica (PUT ) una risorsa esistente per riflettere i dati nella richiesta. |
delete |
Rimuove (DELETE ) una risorsa specifica. |
L'API attualmente supporta metodi per elencare ciascuno dei tipi di risorse supportati e supporta anche le operazioni di scrittura per molte risorse.
La tabella seguente identifica le operazioni supportate per diversi tipi di risorse. Le operazioni che inseriscono, aggiornano o eliminano risorse richiedono sempre l'autorizzazione dell'utente. In alcuni casi, i metodi list
supportano sia le richieste autorizzate, sia quelle non autorizzate, in cui le richieste non autorizzate recuperano solo dati pubblici, mentre le richieste autorizzate possono anche recuperare informazioni relative o private per l'utente attualmente autenticato.
Operazioni supportate | ||||
---|---|---|---|---|
list | insert | update | delete | |
activity |
||||
caption |
||||
channel |
||||
channelBanner |
||||
channelSection |
||||
comment |
||||
commentThread |
||||
guideCategory |
||||
i18nLanguage |
||||
i18nRegion |
||||
playlist |
||||
playlistItem |
||||
search result |
||||
subscription |
||||
thumbnail |
||||
video |
||||
videoCategory |
||||
watermark |
Utilizzo della quota
YouTube Data API utilizza una quota per garantire che gli sviluppatori utilizzino il servizio come previsto e non creino applicazioni che riducono ingiustamente la qualità del servizio o limitano l'accesso per altri utenti. Tutte le richieste API, comprese quelle non valide, comportano un costo quota di almeno un punto. Puoi trovare la quota disponibile per la tua applicazione in API Console.
I progetti che attivano l'API di dati di YouTube hanno una quota predefinita di 10.000 unità al giorno, un importo sufficiente per la stragrande maggioranza dei nostri utenti dell'API. La quota predefinita, che è soggetta a modifiche, ci aiuta a ottimizzare le allocazioni delle quote e a scalare la nostra infrastruttura in modo più significativo per gli utenti dell'API. Puoi visualizzare l'utilizzo della quota nella pagina Quote della console API.
Nota: se raggiungi il limite di quota, puoi richiedere una quota aggiuntiva compilando il modulo di richiesta di estensione della quota per i servizi API di YouTube.
Calcolo dell'utilizzo della quota
Google calcola l'utilizzo della quota assegnando un costo a ogni richiesta. Tipi di operazioni diversi hanno costi di quota diversi. Ad esempio:
- Un'operazione di lettura che recupera un elenco di risorse (canali, video, playlist) in genere costa 1 unità.
- Un'operazione di scrittura che crea, aggiorna o elimina una risorsa di solito costa
50
unità. - Una richiesta di ricerca costa
100
unità. - Un caricamento video costa
1600
unità.
La tabella Costi di quota per le richieste API mostra il costo delle quote di ciascun metodo API. Tenendo presenti queste regole, puoi stimare il numero di richieste che l'applicazione potrebbe inviare al giorno senza superare la quota.
Risorse parziali
L'API consente, e di fatto, richiede il recupero di risorse parziali in modo che le applicazioni evitino il trasferimento, l'analisi e l'archiviazione di dati non necessari. Questo approccio garantisce inoltre che l'API utilizzi le risorse di rete, CPU e di memoria in modo più efficiente.
L'API supporta due parametri di richiesta, illustrati nelle sezioni seguenti, che consentono di identificare le proprietà della risorsa da includere nelle risposte dell'API.
- Il parametro
part
identifica i gruppi di proprietà che devono essere restituiti per una risorsa. - Il parametro
fields
filtra la risposta dell'API in modo che restituisca solo proprietà specifiche all'interno delle parti della risorsa richieste.
Come utilizzare il parametro part
Il parametro part
è un parametro obbligatorio per qualsiasi richiesta API che recupera o restituisce una risorsa. Il parametro identifica una o più proprietà delle risorse di primo livello (non nidificate) che devono essere incluse in una risposta dell'API. Ad esempio, una risorsa video
ha le seguenti parti:
snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails
Tutte queste parti sono oggetti che contengono proprietà nidificate e puoi considerarli come gruppi di campi di metadati che il server API potrebbe (o meno) recuperare. Pertanto, il parametro part
richiede di selezionare i componenti delle risorse effettivamente utilizzati dall'applicazione. Questo requisito serve a due scopi principali:
- Riduce la latenza impedendo al server API di dedicare tempo al recupero dei campi di metadati che l'applicazione non utilizza.
- Riduce l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che l'applicazione potrebbe recuperare.
Nel corso del tempo, man mano che le risorse si aggiungono, questi vantaggi aumenteranno solo perché la tua applicazione non richiederà proprietà introdotte di recente che non supporta.
Come utilizzare il parametro fields
Il parametro fields
filtra la risposta dell'API, che contiene solo le parti della risorsa identificate nel valore del parametro part
, in modo che la risposta includa solo un insieme specifico di campi. Il parametro fields
consente di rimuovere proprietà nidificate da una risposta dell'API e, di conseguenza, di ridurre ulteriormente l'utilizzo della larghezza di banda. Il parametro part
non può essere utilizzato per filtrare le proprietà nidificate da una risposta.
Le seguenti regole spiegano la sintassi supportata per il valore parametro fields
, che si basa in modo approssimativo sulla sintassi XPath:
- Utilizza un elenco separato da virgole (
fields=a,b
) per selezionare più campi. - Utilizza un asterisco (
fields=*
) come carattere jolly per identificare tutti i campi. - Utilizza le parentesi (
fields=a(b,c)
) per specificare un gruppo di proprietà nidificate che verranno incluse nella risposta dell'API. - Utilizza una barra (
fields=a/b
) per identificare una proprietà nidificata.
In pratica, queste regole spesso consentono a diversi valori dei parametri fields
di recuperare la stessa risposta dell'API. Ad esempio, se vuoi recuperare l'ID elemento, il titolo e la posizione della playlist per ogni elemento di una playlist, puoi utilizzare uno qualsiasi dei seguenti valori:
fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
fields=items(id,snippet/title,snippet/position)
fields=items(id,snippet(title,position))
Nota: come per tutti i valori dei parametri di query, il valore del parametro fields
deve essere codificato come URL. Per una migliore leggibilità, gli esempi in questo documento omettono la codifica.
Richieste parziali di esempio
Gli esempi riportati di seguito mostrano come utilizzare i parametri part
e fields
per garantire che le risposte dell'API includano solo i dati utilizzati nell'applicazione:
- L'esempio 1 restituisce una risorsa video che include quattro parti oltre alle proprietà
kind
eetag
. - L'esempio 2 restituisce una risorsa video che include due parti oltre alle proprietà
kind
eetag
. - L'esempio 3 restituisce una risorsa video che include due parti ma esclude le proprietà
kind
eetag
. - L'esempio 4 restituisce una risorsa video che include due parti, ma esclude
kind
eetag
, nonché alcune proprietà nidificate nell'oggettosnippet
della risorsa.
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
resource and identifies several resource parts that should be included in the API response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "contentDetails": { "duration": "PT15M51S", "aspectRatio": "RATIO_16_9" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" }, "status": { "uploadStatus": "STATUS_PROCESSED", "privacyStatus": "PRIVACY_PUBLIC" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics Description: This example modifies thepart
parameter value so that thecontentDetails
andstatus
properties are not included in the response. API response:{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics) Description: This example adds thefields
parameter to remove allkind
andetag
properties from the API response. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics Description: This example modifies thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
properties. API response:{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
Ottimizzazione del rendimento
Utilizzo di ETag
ETags, una parte standard del protocollo HTTP, consente alle applicazioni di fare riferimento a una versione specifica di una determinata risorsa API. La risorsa può essere un intero feed o un elemento al suo interno. Questa funzionalità supporta i seguenti casi d'uso:
-
Memorizzazione nella cache e recupero condizionale: l'applicazione può memorizzare nella cache le risorse API e i relativi ETag. Quindi, quando l'applicazione richiede di nuovo una risorsa archiviata, specifica l'ETag associato a quella risorsa. Se la risorsa è stata modificata, l'API restituisce la risorsa modificata e l'ETag associato a quella versione della risorsa. Se la risorsa non è cambiata, l'API restituisce una risposta HTTP 304 (
Not Modified
), che indica che la risorsa non è stata modificata. L'applicazione può ridurre la latenza e l'utilizzo della larghezza di banda fornendo risorse memorizzate nella cache in questo modo.Le librerie client per le API di Google supportano gli ETag diversi. Ad esempio, la libreria client JavaScript supporta gli ETag tramite una lista consentita per le intestazioni delle richieste consentite che includono
If-Match
eIf-None-Match
. La lista consentita consente la normale memorizzazione nella cache del browser in modo che, se l'ETag di una risorsa non è cambiato, la risorsa può essere fornita dalla cache del browser. Il client Obj-C, d'altra parte, non supporta gli ETag. -
Protezione da sovrascritture involontarie delle modifiche: gli ETag contribuiscono a garantire che più client API non sovrascrivano inavvertitamente le modifiche reciproche. Durante l'aggiornamento o l'eliminazione di una risorsa, l'applicazione può specificare l'ETag della risorsa. Se l'ETag non corrisponde alla versione più recente della risorsa, la richiesta API non va a buon fine.
L'utilizzo di ETag nell'applicazione offre diversi vantaggi:
- L'API risponde più rapidamente alle richieste di risorse memorizzate nella cache ma invariate, generando una latenza più bassa e un minore utilizzo della larghezza di banda.
- L'applicazione non sovrascriverà inavvertitamente le modifiche apportate a una risorsa da un altro client API.
Google APIs Client Library for JavaScript supporta le intestazioni delle richieste HTTP If-Match
e If-None-Match
, consentendo così il funzionamento degli ETag nel contesto della normale memorizzazione nella cache del browser.
Utilizzo di gzip
Puoi inoltre ridurre la larghezza di banda necessaria per ogni risposta dell'API abilitando la compressione gzip. Anche se la tua applicazione richiederà più tempo di CPU per decomprimere le risposte dell'API, il vantaggio di consumare meno risorse di rete di solito supera questi costi.
Per ricevere una risposta con codifica gzip devi fare due cose:
- Imposta l'intestazione della richiesta HTTP
Accept-Encoding
sugzip
. - Modifica lo user agent in modo che contenga la stringa
gzip
.
Le intestazioni HTTP di esempio riportate di seguito mostrano questi requisiti per l'attivazione della compressione gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)