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

  1. Per accedere alla console API di Google, richiedere una chiave API e registrare la tua applicazione, devi avere un Account Google.

  2. Crea un progetto in Google Developers Console e ottieni le credenziali di autorizzazione in modo che la tua applicazione possa inviare richieste API.

  3. Dopo aver creato il progetto, assicurati che l'API YouTube Data sia uno dei servizi per cui è registrata la tua applicazione:

    1. Vai alla console API e seleziona il progetto che hai appena registrato.
    2. Visita la pagina API abilitate. Nell'elenco delle API, assicurati che lo stato sia ON per l'API YouTube Data v3.

  4. 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.

  5. Seleziona una libreria client per semplificare l'implementazione dell'API.

  6. Acquisisci familiarità con i concetti di base 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 è 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 su un'azione eseguita da un determinato utente sul sito YouTube. Le azioni utente segnalate nei feed attività includono 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, tra le altre.
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 includere 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 agli utenti di YouTube la ricerca dei contenuti che stanno cercando. Sebbene i canali possano essere associati a una o più categorie della guida, non è garantito che siano presenti in una categoria della guida.
i18nLanguage Identifica una lingua dell'applicazione supportata dal sito web YouTube. La lingua dell'applicazione può anche essere definita lingua dell'interfaccia utente.
i18nRegion Identifica un'area geografica che un utente di YouTube può selezionare come regione di contenuti preferita. La regione dei contenuti può essere definita anche locale 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, un canale o una playlist di YouTube 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 disponga 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, valutarlo o commentarlo.
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 temporali 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 che contiene una proprietà videoId, playlistId o channelId che identifica una risorsa video, playlist o canale specifica.

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 della miniatura di un 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 in modo che rifletta 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 dell'utente. In alcuni casi, i metodi list supportano sia le richieste autorizzate che quelle non autorizzate, dove le richieste non autorizzate recuperano solo i dati pubblici, mentre le richieste autorizzate possono recuperare anche 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 della 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 attivano l'API YouTube Data hanno un'allocazione di quota predefinita di 10.000 unità al giorno, una quantità sufficiente per la stragrande maggioranza dei nostri utenti API. La quota predefinita, soggetta a modifiche, ci aiuta a ottimizzare le allocazioni delle quote e a scalare la nostra infrastruttura in modo più significativo per gli utenti delle 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 delle quote

Google calcola l'utilizzo della quota assegnando un costo a ogni richiesta. Diversi tipi di operazioni 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 richiesta di ricerca costa 100 unità.
  • Il caricamento di un video costa 100 unità.

La tabella Costi della quota per le richieste API mostra il costo della quota di ciascun 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 in modo più efficiente le risorse di rete, CPU e di memoria.

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à da restituire per una risorsa.
  • Il parametro fields filtra la risposta dell'API in modo da restituire solo proprietà specifiche all'interno delle parti della risorsa richiesta.

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) da includere in una risposta API. Ad esempio, una risorsa video è composta dalle 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:

  • Riduce la latenza impedendo al server API di dedicare tempo al recupero dei campi di metadati che la tua 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 tempo, man mano che le risorse aggiungono più parti, questi vantaggi aumenteranno solo perché la tua 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 del 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 API e quindi 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 del 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 del parametro fields di recuperare la stessa risposta API. Ad esempio, se vuoi recuperare l'ID, 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 del 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 assicurarti che le risposte dell'API includano solo i dati utilizzati dalla tua applicazione:

  1. L'esempio 1 restituisce una risorsa video che include quattro parti, nonché le proprietà kind e etag.
  2. L'esempio 2 restituisce una risorsa video che include due parti, nonché le proprietà kind e etag.
  3. L'esempio 3 restituisce una risorsa video che include due parti, ma esclude le proprietà kind e etag.
  4. 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 del rendimento

Utilizzo degli ETag

ETags, una parte standard del protocollo HTTP, consentono 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. Poi, quando l'applicazione richiede di nuovo una risorsa archiviata, specifica l'ETag associato a quella risorsa. Se la risorsa è cambiata, l'API restituisce la risorsa modificata e l'ETag associato a quella versione della risorsa. Se la risorsa non è stata modificata, l'API restituisce una risposta HTTP 304 (Not Modified), che indica che la risorsa non è stata modificata. 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 di intestazioni di richiesta che include If-Match e If-None-Match. La whitelist consente la normale memorizzazione nella cache del browser, in modo che se l'ETag di una risorsa non è cambiata, la risorsa possa essere pubblicata dalla cache del browser. Il client Obj-C, invece, non supporta gli ETag.

  • Protezione dalla sovrascrittura involontaria 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:

  • L'API risponde più rapidamente 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 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)