Questa pagina mostra le richieste di esempio all'API di dati di YouTube. Puoi utilizzare l'API YouTube Data per recuperare e manipolare risorse di YouTube come video, canali e playlist. Ogni campione si collega a Explorer API di Google e lo completa in modo che tu possa eseguire l'esempio e vedere la risposta.
Per saperne di più sul caricamento di contenuti mediante l'API di dati di YouTube, consulta la pagina Caricamenti ripristinabili.
Panoramica
Per maggiore chiarezza, gli esempi in questa pagina mostrano gli elementi distintivi di ogni richiesta e abbreviano l'URL di base per l'host che elabora le richieste dell'API di dati (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 per questa richiesta è:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Molte delle richieste recuperano i dati accessibili soltanto al proprietario del canale YouTube, ad esempio l'elenco degli iscritti. Queste richieste richiedono al proprietario del canale di concedere al programma di esplorazione delle API di Google il diritto di effettuare richieste per l'API di dati di YouTube per loro conto. Per informazioni dettagliate su come autorizzare l'accesso ai dati privati del canale, consulta Implementazione dell'autenticazione OAuth 2.0. Dopo aver eseguito il collegamento all'Explorer API, fai clic sul pulsante Autorizza le richieste utilizzando OAuth 2.0. Questo passaggio autorizza l'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 quali parti della risorsa sono incluse nella risposta. Il parametro identifica una o più proprietà di risorse di primo livello (non nidificate) che devono essere incluse nella risposta. Ad esempio, alcune parti di una risorsa video sono:
- snippet
- Dettagli contenuti
- player
- statistica
- stato
Tutte queste parti sono oggetti che contengono proprietà nidificate e puoi considerarli come gruppi di campi di metadati che il server API potrebbe (o non dovrebbe) recuperare. Pertanto, il parametro part richiede che tu selezioni i componenti della risorsa effettivamente utilizzati dalla tua applicazione.Per saperne di più, consulta la Guida introduttiva all'API YouTube Data.
Recuperare informazioni sul canale
Questa richiesta utilizza il metodo channels.list per recuperare i dettagli relativi ai canali che appartengono 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. I contentDetails includono 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 "Video caricati" restituita nella risposta di cui sopra per le informazioni del canale, utilizzando il metodo playlistItems.list per recuperare i video al suo interno.
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 i preferiti, i Mi piace, la cronologia delle visualizzazioni o gli elenchi Guarda più tardi dell'utente utilizzando la richiesta precedente sostituendo l'ID playlist corrispondente dalla risposta delle informazioni del 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 del canale (caricamenti, cronologia delle visualizzazioni e così via). Recupera solo le playlist create dagli utenti.
GET {base_URL}/playlists?part=snippet &mine=true
Quando disponi di un ID playlist, puoi recuperare gli elementi dalla playlist corrispondente tramite 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}
Recupera abbonamenti
Una risorsa subscription definisce una relazione tra un utente di YouTube (iscritto) e un canale. Il metodo subscriptions.list recupera gli iscritti a un determinato canale o le iscrizioni di un determinato utente, a seconda dei parametri che includi nella richiesta.
Iscritti al canale
Questa richiesta recupera un elenco di 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 usato per elencare i canali a cui un utente si iscrive. Questa richiesta utilizza il parametro mine per recuperare un elenco dei canali YouTube a cui l'utente autenticato ha effettuato l'iscrizione.
GET {base_URL}/subscriptions?part=snippet &mine=true
Recuperare l'attività utente
Una risorsa activity contiene informazioni su un'azione intrapresa su un determinato canale o utente da YouTube, come il caricamento di un video, l'iscrizione a un canale e così via. Il metodo activities.list recupera le azioni associate a un canale o un utente che corrispondono ai criteri della richiesta. Ad esempio, puoi recuperare le azioni associate a un determinato canale, le iscrizioni dell'utente o la home page di YouTube personalizzata.
Attività durante un periodo di tempo
Questa richiesta recupera tutte le azioni eseguite dall'utente autenticato nel 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à sulla home page
Questa richiesta recupera il feed di attività personalizzato che viene 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 relative alla popolarità e le informazioni demografiche relative ai video e ai canali di YouTube, puoi utilizzare l'API di YouTube Analytics. La pagina Richieste API di esempio mostra come recuperare i report più comuni da YouTube Analytics.
Cerca
Il metodo search.list ti consente di cercare video, canali o playlist di YouTube che corrispondono a criteri specifici. Puoi eseguire ricerche basate su proprietà video, parole chiave o argomenti (o una combinazione di questi) e ordinare i risultati in base a fattori quali data di creazione, numero di visualizzazioni o valutazione.
Come altre richieste all'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 permanente 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é richiede 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 per numero di visualizzazioni.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Video ad alta definizione incorporabili
Questa richiesta cerca video che hanno determinate proprietà, ovvero video ad alta definizione che possono essere incorporati in altri siti. I risultati vengono elencati 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 per video sull'API di dati di YouTube che includono sottotitoli.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Ricerca basata sugli argomenti
Un modo più sofisticato per cercare video su un determinato argomento è utilizzare gli argomenti Freebase anziché le parole chiave. Le risorse video e il canale YouTube contengono tutti un oggetto topicDetails che contiene un elenco di ID argomento Freebase associati alla risorsa. Una ricerca basata su argomento è più intelligente di una ricerca per parole chiave, perché un argomento Freebase rappresenta tutti gli aspetti di un concetto o di una cosa reale.
Per eseguire una ricerca utilizzando un argomento Freebase, devi prima recuperare l'ID argomento utilizzando l'API Freebase. Questa richiesta restituisce i video associati all'argomento Freebase per Python il cui ID argomento è /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Ricerca di 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 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 correlati al calcio (canali, playlist e video), puoi eseguire una ricerca universale. Se ometti il parametro type, la richiesta recupera i contenuti di tutti i tipi
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Creare e aggiornare risorse
Le richieste che abbiamo esaminato finora utilizzano tutte il metodo HTTP GET per recuperare i dati di YouTube. L'API di dati di YouTube offre anche metodi che utilizzano HTTP POST per creare o aggiornare le risorse di YouTube come video, playlist o canali. Di seguito sono riportati alcuni esempi di richieste.
I metodi POST includono un elemento Request body, che è la rappresentazione JSON della risorsa creata o aggiornata. Puoi creare rappresentazioni JSON in Explorer API di Google utilizzando uno strumento interattivo.
Crea una sottoscrizione
Questa richiesta consente di iscrivere 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' } } }
Crea 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', } }
Aggiunta di 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 } }