Questa pagina mostra esempi di richieste all'API YouTube Data. L'API YouTube Data consente di recuperare e manipolare risorse di YouTube come video, canali e playlist. Ogni esempio rimanda a Explorer API di Google e lo popola in modo che tu possa eseguirlo e visualizzare la risposta.
Per informazioni sul caricamento di contenuti utilizzando l'API YouTube Data, consulta Caricamenti ripristinabili.
Panoramica
Per chiarezza, gli esempi in questa pagina mostrano gli elementi distintivi di ogni richiesta e abbreviano l'URL di base dell'host che elabora le richieste dell'API Data (https://www.googleapis.com/youtube/v3). Per effettuare la richiesta al di fuori del contesto degli esempi, devi includere l'URL completo.
Ad esempio, ecco una richiesta di esempio così come appare in questa pagina:
GET {base-URL}/channels?part=contentDetails &mine=true
L'URL completo di questa richiesta è:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Diverse richieste recuperano dati accessibili solo al proprietario del canale YouTube, ad esempio l'elenco degli iscritti. Queste richieste richiedono che il proprietario del canale conceda a Explorer API di Google il diritto di eseguire richieste dell'API YouTube Data per suo conto. (Per informazioni dettagliate sull'autorizzazione dell'accesso ai dati privati del canale, consulta Implementare l'autenticazione OAuth 2.0.) Dopo aver eseguito il collegamento a APIs Explorer, fai clic sul pulsante Autorizza le richieste utilizzando OAuth 2.0. Questo passaggio autorizza Explorer API a effettuare richieste per conto del proprietario. Seleziona anche l'ambito dell'autorizzazione, che specifica i tipi di richieste che Explorer API può eseguire.
La risposta a ogni richiesta è la rappresentazione JSON di una risorsa di YouTube. Il parametro part nella richiesta specifica le parti della risorsa incluse nella risposta. Il parametro identifica una o più proprietà delle risorse di primo livello (non nidificate) da includere nella risposta. Ad esempio, alcune delle parti di una risorsa video sono:
- snippet
- contentDetails
- player
- statistics
- status
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.Per saperne di più, consulta Iniziare a utilizzare l'API YouTube Data.
Recuperare le informazioni sul canale
Questa richiesta utilizza il metodo channels.list per recuperare i dettagli dei canali appartenenti all'utente autenticato.
GET {base_URL}/channels?part=contentDetails &mine=true
La risposta a questa richiesta include l'ID canale e contentDetails per il canale dell'utente autenticato. contentDetails include le diverse playlist generate dal sistema associate al canale. Molte delle richieste successive richiedono l'ID canale o uno degli ID playlist, quindi è importante registrarli.
{
"id": {CHANNEL_ID},
"kind": "youtube#channel",
"etag": etag,
"contentDetails": {
"relatedPlaylists": {
"likes": {LIKES_PLAYLIST_ID},
"favorites": {FAVORITES_PLAYLIST_ID},
"uploads": {UPLOADS_PLAYLIST_ID},
"watchHistory": {WATCHHISTORY_PLAYLIST_ID},
"watchLater": {WATCHLATER_PLAYLIST_ID}
},
"googlePlusUserId": string
},
}Video caricati e playlist generate dal sistema
YouTube aggiunge tutti i video caricati a una playlist associata al canale. Per ottenere un elenco dei video caricati, esegui una query sulla playlist "uploads" restituita in the response shown above for channel information, utilizzando il playlistItems.list metodo per recuperare i video nella playlist.
Prima di eseguire la seguente richiesta di esempio in Explorer API di Google, sostituisci {UPLOADS_PLAYLIST_ID} con l'ID playlist della richiesta precedente.
GET {base_URL}/playlistItems?part=contentDetails &playlistId={UPLOADS_PLAYLIST_ID}
Tieni presente che il valore "id" di ogni elemento restituito è l'ID playlistItem. L'ID video dell'elemento della playlist è videoId nella parte contentDetails.
Puoi recuperare gli elenchi dei preferiti, dei Mi piace, della cronologia visualizzazioni o di Guarda più tardi di un utente utilizzando la richiesta sopra riportata, sostituendo l'ID playlist corrispondente dalla risposta delle informazioni sul canale.
Playlist create dagli utenti
Questa richiesta utilizza il metodo playlists.list per recuperare le playlist associate al canale autenticato. Tieni presente che questa richiesta non recupera le playlist generate dal sistema incluse nelle informazioni sul canale (caricamenti, cronologia visualizzazioni e così via). Recupera solo le playlist create dagli utenti.
GET {base_URL}/playlists?part=snippet &mine=true
Una volta che hai un ID playlist, puoi recuperare gli elementi dalla playlist utilizzando la richiesta mostrata nella sezione precedente.
Puoi richiedere informazioni sulle playlist pubbliche di un canale senza autenticazione. Quando invii una richiesta non autenticata, devi includere l'argomento key che specifica la chiave API univoca per l'applicazione che effettua la richiesta. Ad esempio, questa richiesta recupera le playlist associate al canale GoogleDevelopers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Recuperare gli abbonamenti
Una risorsa subscription definisce una relazione tra un utente di YouTube (l'iscritto) e un canale. Il metodo subscriptions.list recupera gli iscritti a un determinato canale o gli abbonamenti di un determinato utente, a seconda dei parametri inclusi nella richiesta.
Iscritti al canale
Questa richiesta recupera un elenco degli iscritti al canale autenticato.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Abbonamenti utente
Lo stesso metodo che elenca gli iscritti (subscriptions.list) può essere utilizzato per elencare i canali a cui un utente è iscritto. Questa richiesta utilizza il parametro mine per recuperare un elenco dei canali YouTube a cui l'utente autenticato è iscritto.
GET {base_URL}/subscriptions?part=snippet &mine=true
Recuperare l'attività utente
Una risorsa activity contiene informazioni su un'azione che un determinato canale o utente ha intrapreso su YouTube, ad esempio caricare un video, iscriversi a un canale e così via. Il metodo activities.list recupera le azioni associate a un canale o a un utente che corrispondono ai criteri della richiesta. Ad esempio, puoi recuperare le azioni associate a un canale specifico, agli abbonamenti dell'utente o alla home page personalizzata di YouTube dell'utente.
Attività durante un periodo di tempo
Questa richiesta recupera tutte le azioni intraprese dall'utente autenticato durante il mese di aprile 2013.
GET {base_URL}/activities?part=snippet,contentDetails &mine=true &publishedAfter=2013-04-01T00%3A00%3A00Z &publishedBefore=2013-05-01T00%3A00%3A00Z
Attività della home page
Questa richiesta recupera il feed di attività personalizzato visualizzato nella home page di YouTube dell'utente autenticato.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
Per recuperare le statistiche di visualizzazione, le metriche di popolarità e le informazioni demografiche per i video di YouTube e i canali, utilizza l'API YouTube Analytics. La pagina Richieste API di esempio mostra come recuperare i report comuni da YouTube Analytics.
Cerca
Il metodo search.list consente di cercare video di YouTube, canali o playlist che corrispondono a criteri specificati. Puoi eseguire la ricerca in base alle proprietà dei video, alle parole chiave o agli argomenti (o a una combinazione di questi) e ordinare i risultati in base a fattori come la data di creazione, il numero di visualizzazioni o la valutazione.
Come altre richieste dell'API YouTube Data, il metodo search.list restituisce la rappresentazione JSON di una risorsa di YouTube. A differenza di altre risorse di YouTube, tuttavia, un risultato di ricerca non è un oggetto persistente con un ID univoco.
Molte richieste cercano contenuti disponibili pubblicamente e pertanto non richiedono l'autenticazione. Tra gli esempi riportati di seguito, solo il primo richiede l'autenticazione, poiché chiede specificamente i "miei" video. Quando invii una richiesta non autenticata, devi includere l'argomento key che specifica la chiave API univoca per la tua applicazione.
I miei video più visti
Questa richiesta recupera tutti i video dell'utente autenticato e li elenca in ordine decrescente in base al numero di visualizzazioni.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Video in alta definizione incorporabili
Questa richiesta cerca video con proprietà specifiche, ovvero video in alta definizione che possono essere incorporati in altri siti. Elenca i risultati in ordine decrescente di valutazione.
GET {base_URL}/search?part=snippet &order=rating &type=video &videoDefinition=high &videoEmbeddable=true &key={YOUR_API_KEY}
Video su un argomento specifico
Questa richiesta esegue una ricerca per parole chiave di video sull'API YouTube Data che includono i sottotitoli codificati.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Ricerca basata su argomenti
Un modo più sofisticato per cercare video su un argomento specifico è utilizzare gli argomenti di Freebase anziché le parole chiave. Le risorse dei canali YouTube e dei video contengono tutte un topicDetails che contiene un elenco di ID argomento di Freebase associati alla risorsa. Una ricerca basata su argomenti è più intelligente di una ricerca per parole chiave, perché un argomento di Freebase rappresenta tutti gli aspetti di un concetto o di una cosa del mondo reale.
Per eseguire una ricerca utilizzando un argomento di Freebase, devi prima recuperare l'ID argomento utilizzando l'API Freebase. Questa richiesta restituisce i video associati all'argomento di Freebase per Python, il cui ID argomento è /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Cercare playlist o canali
La ricerca non è limitata ai video. Puoi anche cercare playlist o canali. Questa richiesta recupera le playlist che corrispondono alla parola chiave "calcio".
GET {base_URL}/search?part=snippet &q=soccer &type=playlist &key={YOUR_API_KEY}
Se preferisci trovare i canali di calcio, modifica il parametro type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Se vuoi tutti i contenuti relativi al calcio (canali, playlist e video), puoi eseguire una ricerca universale. Se ometti il parametro type, la richiesta recupera contenuti di tutti i tipi.
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Creare e aggiornare le risorse
Le richieste che abbiamo esaminato finora utilizzano tutte il metodo HTTP GET per recuperare i dati di YouTube. L'API YouTube Data offre anche metodi che utilizzano HTTP POST per creare o aggiornare risorse di YouTube come video, playlist o canali. Le seguenti richieste forniscono esempi.
I metodi POST includono un Request body, ovvero la rappresentazione JSON della risorsa in fase di creazione o aggiornamento. Puoi creare rappresentazioni JSON in Explorer API di Google utilizzando uno strumento interattivo.
Creare un abbonamento
Questa richiesta iscrive l'utente autenticato al canale GoogleDevelopers. In altre parole, crea una risorsa di abbonamento.
POST {base_URL}/subscriptions?part=snippet
Request body: { 'snippet': { 'resourceId': { 'kind': 'youtube#channel', 'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' } } }
Creare una playlist
Questa richiesta crea una nuova playlist pubblica.
POST {base_URL}/playlists?part=snippet
Request body: { 'snippet': { 'title': 'New playlist', 'description': 'Sample playlist for Data API', } }
Aggiungere un video a una playlist
Ora che abbiamo creato una playlist, aggiungiamo un video. Questa richiesta aggiunge un video all'inizio della playlist ('position': 0).
POST {base_URL}/playlistItems?part=snippet Request body: { 'snippet': { 'playlistId': '{PLAYLIST_ID}', 'resourceId': { 'kind': 'youtube#video', 'videoId': '{VIDEO_ID}' } 'position': 0 } }