Panoramica dell'API di dati di YouTube

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

  1. Devi disporre di un Account Google per accedere alla console API di Google, richiedere una chiave API e registrare la tua applicazione.

  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 di dati di YouTube sia uno dei servizi per cui è registrata la tua applicazione per l'utilizzo:

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

  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 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:

  1. L'esempio 1 restituisce una risorsa video che include quattro parti oltre alle proprietà kind e etag.
  2. L'esempio 2 restituisce una risorsa video che include due parti oltre alle 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 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 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 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 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)