Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Panoramica dell'API di dati di YouTube

Introduzione

Questo documento è rivolto agli sviluppatori che vogliono scrivere applicazioni che interagiscono con YouTube. Spiega i concetti di base di YouTube e dell'API stessa. Fornisce inoltre una panoramica delle diverse funzioni supportate dall'API.

Prima di iniziare

Per accedere alla console Google Cloud, richiedere una chiave API e registrare la tua applicazione, devi avere un Account Google.
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 YouTube Data sia uno dei servizi per cui la tua applicazione è registrata:
1. Vai alla console Cloud e seleziona il progetto che hai appena registrato.
2. Visita la pagina API abilitate. Assicurati che l'API YouTube Data sia presente nell'elenco delle API abilitate. In caso contrario, apri la libreria API e abilita l'API.
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 dei dati JSON (JavaScript Object Notation). JSON è un formato di dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture arbitrarie di dati. Per ulteriori informazioni, visita il sito json.org.

Risorse e tipi di risorse

Una risorsa è un'entità di dati individuale con un identificatore univoco. La tabella seguente descrive i diversi tipi di risorse con cui puoi interagire utilizzando l'API.

Risorse
`activity`	Contiene informazioni su un'azione eseguita da un determinato utente sul sito di YouTube. Le azioni degli utenti segnalate nei feed Attività includono, tra le altre, 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 di un canale.
`channelSection`	Contiene informazioni su un insieme di video che un canale ha scelto di mettere in evidenza. Ad esempio, una sezione potrebbe mostrare i caricamenti più recenti, i caricamenti più popolari o i video di una o più playlist di un canale.
`guideCategory`	Identifica una categoria che YouTube associa ai canali in base ai loro contenuti o ad altri indicatori, come la popolarità. Le categorie della guida hanno lo scopo di organizzare i canali in modo da facilitare la ricerca dei contenuti da parte degli utenti di YouTube. Anche se i canali possono essere associati a una o più categorie della guida, non è garantito che siano presenti in nessuna categoria della guida.
`i18nLanguage`	Identifica una lingua dell'applicazione supportata dal sito web YouTube. La lingua dell'applicazione può anche essere definita lingua della UI.
`i18nRegion`	Identifica un'area geografica che un utente di YouTube può selezionare come regione preferita per i contenuti. La regione dei contenuti può anche essere definita come località 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 come viene utilizzata la risorsa inclusa nella playlist.
`search result`	Contiene informazioni su un video di YouTube, un canale o una playlist che corrispondono ai parametri di ricerca specificati in una richiesta API. Sebbene un risultato di ricerca rimandi a una risorsa identificabile in modo univoco, come un video, non dispone di dati persistenti propri.
`subscription`	Contiene informazioni su un abbonamento di un utente di YouTube. Un'iscrizione avvisa un utente quando vengono aggiunti nuovi video a un canale o quando un altro utente esegue una delle diverse azioni su YouTube, ad esempio caricare un video, valutare un video 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 la riproduzione dei video di un canale specifico. Il proprietario del canale può anche specificare un canale di destinazione a cui è collegata l'immagine, nonché i dettagli di temporizzazione che determinano quando viene visualizzato il watermark durante la riproduzione dei video e per quanto tempo è 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. 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 per queste risorse. Ad esempio, il metodo videos.rate associa una valutazione dell'utente a un video, mentre il metodo thumbnails.set carica un'immagine in miniatura del video su YouTube e la associa a un video.

Operazioni
`list`	Recupera (`GET`) un elenco di zero o più risorse.
`insert`	Crea (`POST`) una nuova risorsa.
`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 i diversi tipi di risorse. Le operazioni che inseriscono, aggiornano o eliminano risorse richiedono sempre l'autorizzazione utente. In alcuni casi, i metodi list supportano sia le richieste autorizzate sia quelle non autorizzate, dove le richieste non autorizzate recuperano solo i dati pubblici, mentre le richieste autorizzate possono anche recuperare informazioni sull'utente attualmente autenticato o private.

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 quota

YouTube Data API utilizza una quota per garantire che gli sviluppatori utilizzino il servizio come previsto e non creino applicazioni che riducano ingiustamente la qualità del servizio o limitino l'accesso per altri. Tutte le richieste API, incluse quelle non valide, comportano un costo di quota di almeno un punto. Puoi trovare la quota disponibile per la tua applicazione in API Console.

I progetti che abilitano l'API YouTube Data hanno un'allocazione di quota predefinita di 100 chiamate search.list, 100 chiamate videos.insert e 10.000 unità al giorno combinate per tutti gli altri endpoint. La quota predefinita, che è soggetta a modifiche, ci aiuta a ottimizzare le allocazioni delle quote e a scalare la nostra infrastruttura in un modo più significativo per gli utenti delle nostre 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) di solito costa 1 unità.
Un'operazione di scrittura che crea, aggiorna o elimina una risorsa di solito costa 50 unità.
Una query di ricerca costa 1 unità.
Il caricamento di un video costa 1 unità.

La tabella Costi delle quote per le richieste API mostra il costo della quota di ogni metodo API. Tenendo presente queste regole, puoi stimare il numero di richieste che la tua applicazione potrebbe inviare al giorno senza superare la quota.

Risorse parziali

L'API consente e richiede il recupero di risorse parziali in modo che le applicazioni evitino di trasferire, analizzare e archiviare dati non necessari. Questo approccio garantisce inoltre che l'API utilizzi le risorse di rete, CPU e memoria in modo più efficiente.

L'API supporta due parametri di richiesta, spiegati nelle sezioni seguenti, che consentono di identificare le proprietà delle risorse 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 da restituire solo proprietà specifiche all'interno delle parti della risorsa richieste.

Come utilizzare il parametro `part`

Il parametro part è 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 ha due scopi principali:

In questo modo, la latenza viene ridotta perché il server API non deve recuperare i campi dei metadati che non vengono utilizzati dall'applicazione.
Riduce l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che l'applicazione potrebbe recuperare.

Nel tempo, man mano che le risorse aggiungono altre parti, questi vantaggi aumenteranno, poiché l'applicazione non richiederà proprietà appena introdotte 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 parametro part, in modo che la risposta includa solo un insieme specifico di campi. Il parametro fields ti consente di rimuovere le 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 liberamente 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 parametro fields di recuperare la stessa risposta dell'API. Ad esempio, se vuoi recuperare l'ID articolo, il titolo e la posizione di ogni elemento di una playlist, puoi utilizzare uno 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 parametro fields deve essere codificato nell'URL. Per una maggiore leggibilità, gli esempi in questo documento omettono la codifica.

Esempi di richieste parziali

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 dall'applicazione:

L'esempio 1 restituisce una risorsa video che include quattro parti, nonché le proprietà kind e etag.
L'esempio 2 restituisce una risorsa video che include due parti, nonché le proprietà kind e etag.
L'esempio 3 restituisce una risorsa video che include due parti, ma esclude le proprietà kind e etag.
L'esempio 4 restituisce una risorsa video che include due parti, ma esclude kind e etag, nonché alcune proprietà nidificate nell'oggetto snippet della risorsa.

Esempio 1

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video 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"
   }
  }
 ]
}

Esempio 2

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status 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"
   }
  }
 ]
}

Esempio 3

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 the fields parameter to remove all
             kind and etag 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"
   }
  }
 ]
}

Esempio 4

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 the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId 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 delle prestazioni

Utilizzo degli 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 potrebbe essere un intero feed o un elemento di quel feed. Questa funzionalità supporta i seguenti casi d'uso:

Memorizzazione nella cache e recupero condizionale: la tua applicazione può memorizzare nella cache le risorse API e i relativi ETag. In seguito, quando l'applicazione richiede nuovamente una risorsa archiviata, specifica l'ETag associato alla risorsa. Se la risorsa è cambiata, 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 è cambiata. La tua applicazione può ridurre la latenza e l'utilizzo della larghezza di banda pubblicando risorse memorizzate nella cache in questo modo.

Le librerie client per le API di Google differiscono nel supporto degli ETag. Ad esempio, la libreria client JavaScript supporta gli ETag tramite una lista consentita per le intestazioni della richiesta che include If-Match e If-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 possa essere pubblicata dalla cache del browser. Il client Obj-C, invece, non supporta gli ETag.
Protezione da sovrascritture involontarie delle modifiche: gli ETag contribuiscono a garantire che più client API non sovrascrivano inavvertitamente le modifiche degli altri. Quando aggiorni o elimini una risorsa, la tua 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 degli ETag nella tua applicazione offre diversi vantaggi:

La risposta dell'API è più rapida alle richieste di risorse memorizzate nella cache ma invariate, con conseguente latenza e utilizzo della larghezza di banda inferiori.
La tua applicazione non sovrascriverà inavvertitamente le modifiche a una risorsa apportate 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ì alle ETag di funzionare nel contesto della normale memorizzazione nella cache del browser.

Utilizzo di gzip

Puoi anche ridurre la larghezza di banda necessaria per ogni risposta dell'API attivando la compressione gzip. Sebbene l'applicazione richieda tempo di CPU aggiuntivo per decomprimere le risposte dell'API, il vantaggio di consumare meno risorse di rete di solito supera questo costo.

Per ricevere una risposta con codifica gzip, devi eseguire due operazioni:

Imposta l'intestazione della richiesta HTTP Accept-Encoding su gzip.
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)

Panoramica dell'API di dati di YouTube Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.