Esta página mostra exemplos de solicitações da API YouTube Data. Você usa a API YouTube Data para recuperar e manipular recursos do YouTube, como vídeos, canais e playlists. Cada exemplo tem um link e preenche o APIs Explorer do Google para que você possa executar o exemplo e conferir a resposta.
Para informações sobre como fazer upload de conteúdo usando a API YouTube Data, consulte Uploads retomáveis.
Visão geral
Para fins de esclarecimento, os exemplos nesta página mostram os elementos distintos de cada solicitação de API e abreviaram o URL de base do host que processa as solicitações da API Data (https://www.googleapis.com/youtube/v3). Para fazer a solicitação fora do contexto dos exemplos, inclua o URL completo.
Por exemplo, confira uma solicitação de amostra conforme ela aparece nesta página:
GET {base-URL}/channels?part=contentDetails &mine=true
O URL completo dessa solicitação é:
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Várias solicitações recuperam dados que só podem ser acessados pelo proprietário do canal do YouTube, como a lista de inscritos. Essas solicitações exigem que o proprietário do canal conceda ao APIs Explorer do Google o direito de fazer solicitações de API YouTube Data em nome dele. (Consulte Implementar a autenticação OAuth 2.0 para mais detalhes sobre como autorizar o acesso a dados de canais privados.) Depois de fazer a vinculação ao APIs Explorer, clique no botão Autorizar solicitações usando o OAuth 2.0. Essa etapa autoriza o APIs Explorer a fazer solicitações em nome do proprietário. Você também seleciona o escopo da autorização, que especifica os tipos de solicitações que o APIs Explorer pode realizar.
A resposta a cada solicitação é a representação JSON de um recurso do YouTube. O parâmetro part na solicitação especifica quais partes do recurso são incluídas na resposta. O parâmetro identifica uma ou mais propriedades de recurso de nível superior (não aninhadas) que precisam ser incluídas na resposta. Por exemplo, algumas das partes de um vídeo recurso são:
- snippet
- contentDetails
- jogador
- estatísticas
- status
Todas essas partes são objetos que contêm propriedades aninhadas, e você pode pensar nesses objetos como grupos de campos de metadados que o servidor de API pode (ou não pode) recuperar. Assim, o parâmetro part exige que você selecione os componentes de recursos que seu aplicativo realmente usa.Consulte Introdução à API YouTube Data para mais informações.
Recuperar informações do canal
Essa solicitação usa o método channels.list para recuperar detalhes sobre os canais pertencentes ao usuário autenticado.
GET {base_URL}/channels?part=contentDetails &mine=true
A resposta a essa solicitação inclui o ID do canal e contentDetails do canal do usuário autenticado. Os contentDetails incluem as várias playlists geradas pelo sistema associadas ao canal. Muitas das solicitações subsequentes exigem o ID do canal ou um dos códigos da playlist. Por isso, é importante registrá-los.
{
"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
},
}Vídeos enviados e playlists geradas pelo sistema
O YouTube adiciona todos os vídeos enviados a uma playlist associada ao canal. Para receber uma lista dos vídeos enviados, consulte a playlist "uploads" retornada em a resposta mostrada acima para informações do canal, usando o playlistItems.list método para recuperar os vídeos nessa playlist.
Antes de executar a solicitação de exemplo a seguir no APIs Explorer do Google, substitua {UPLOADS_PLAYLIST_ID} pelo código da playlist da solicitação anterior.
GET {base_URL}/playlistItems?part=contentDetails &playlistId={UPLOADS_PLAYLIST_ID}
Observe que o valor "id" de cada item retornado é o ID do playlistItem. O ID do vídeo do item da playlist é o videoId na parte contentDetails.
Você pode recuperar as listas de favoritos, gostos, histórico de exibição ou assistir mais tarde de um usuário usando a solicitação acima, substituindo o código da playlist correspondente da resposta de informações do canal.
Playlists criadas pelo usuário
Essa solicitação usa o método playlists.list para recuperar as playlists associadas ao canal autenticado. Essa solicitação não recupera as playlists geradas pelo sistema incluídas nas informações do canal (uploads, histórico de exibição etc.). Ela recupera apenas playlists criadas pelo usuário.
GET {base_URL}/playlists?part=snippet &mine=true
Depois de ter um código da playlist, você pode recuperar os itens dela usando a solicitação mostrada na seção anterior.
É possível solicitar informações sobre as playlists públicas de um canal sem autenticação. Ao enviar uma solicitação não autenticada, inclua o argumento key que especifica a chave de API exclusiva do aplicativo que está fazendo a solicitação. Por exemplo, essa solicitação recupera as playlists associadas ao canal GoogleDevelopers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Recuperar assinaturas
Um recurso subscription define uma relação entre um usuário do YouTube (o inscrito) e um canal. O método subscriptions.list recupera os inscritos em um canal específico ou as assinaturas de um usuário específico, dependendo dos parâmetros incluídos na solicitação.
Inscritos no canal
Essa solicitação recupera uma lista dos inscritos no canal autenticado.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Assinaturas do usuário
O mesmo método que lista os inscritos (subscriptions.list) pode ser usado para listar os canais que um usuário assina. Essa solicitação usa o parâmetro mine para recuperar uma lista dos canais do YouTube que o usuário autenticado assina.
GET {base_URL}/subscriptions?part=snippet &mine=true
Recuperar a atividade do usuário
Um recurso activity contém informações sobre uma ação que um canal ou usuário específico realizou no YouTube, como enviar um vídeo, se inscrever em um canal e assim por diante. O método activities.list recupera as ações associadas a um canal ou usuário que correspondem aos critérios da solicitação. Por exemplo, é possível recuperar ações associadas a um canal específico, às assinaturas do usuário ou à página inicial personalizada do YouTube do usuário.
Atividade durante um período
Essa solicitação recupera todas as ações que o usuário autenticado realizou durante abril de 2013.
GET {base_URL}/activities?part=snippet,contentDetails &mine=true &publishedAfter=2013-04-01T00%3A00%3A00Z &publishedBefore=2013-05-01T00%3A00%3A00Z
Atividade da página inicial
Essa solicitação recupera o feed de atividades personalizado que aparece na página inicial do YouTube do usuário autenticado.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
Para recuperar estatísticas de visualização, métricas de popularidade e informações demográficas de vídeos do YouTube e canais, use a API YouTube Analytics. A página Solicitações de API de exemplo mostra como recuperar relatórios comuns do YouTube Analytics.
Pesquisar
O método search.list permite pesquisar vídeos do YouTube, canais ou playlists que correspondam a critérios especificados. É possível pesquisar com base em propriedades de vídeo, palavras-chave ou temas (ou uma combinação deles) e classificar os resultados com base em fatores como data de criação, contagem de visualizações ou classificação.
Como outras solicitações da API YouTube Data, o método search.list retorna a representação JSON de um recurso do YouTube. No entanto, ao contrário de outros recursos do YouTube, um resultado da pesquisa não é um objeto persistente com um ID exclusivo.
Muitas solicitações pesquisam conteúdo disponível publicamente e, portanto, não exigem autenticação. Entre os exemplos abaixo, apenas o primeiro exige autenticação, já que pede especificamente "meus" vídeos. Ao enviar uma solicitação não autenticada, inclua o argumento key que especifica a chave de API exclusiva do seu aplicativo.
Meus vídeos mais assistidos
Essa solicitação recupera todos os vídeos do usuário autenticado e os lista em ordem decrescente por contagem de visualizações.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Vídeos incorporáveis em alta definição
Essa solicitação pesquisa vídeos que têm propriedades específicas, ou seja, vídeos em alta definição que podem ser incorporados em outros sites. Ela lista os resultados em ordem decrescente de classificação.
GET {base_URL}/search?part=snippet &order=rating &type=video &videoDefinition=high &videoEmbeddable=true &key={YOUR_API_KEY}
Vídeos sobre um assunto específico
Essa solicitação realiza uma pesquisa de palavras-chave para vídeos sobre a API YouTube Data que incluem legendas.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Pesquisa baseada em temas
Uma maneira mais sofisticada de pesquisar vídeos sobre um tema específico é usar temas do Freebase em vez de palavras-chave. Os recursos de canal do YouTube e de vídeo contêm um topicDetails objeto que contém uma lista de IDs de temas do Freebase associados ao recurso. Uma pesquisa baseada em temas é mais inteligente do que uma pesquisa de palavras-chave, porque um tema do Freebase representa todos os aspectos de um conceito ou coisa do mundo real.
Para pesquisar usando um tema do Freebase, primeiro recupere o ID do tema usando a API Freebase. Essa solicitação retorna vídeos associados ao tema do Freebase para Python, cujo ID é /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Pesquisar playlists ou canais
A pesquisa não se limita a vídeos. Também é possível pesquisar playlists ou canais. Essa solicitação recupera playlists que correspondem à palavra-chave "futebol".
GET {base_URL}/search?part=snippet &q=soccer &type=playlist &key={YOUR_API_KEY}
Se você preferir encontrar canais de futebol, basta mudar o parâmetro type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Se você quiser todo o conteúdo relacionado ao futebol (canais, playlists e vídeos), faça uma pesquisa universal. Se você omitir o parâmetro type, a solicitação vai recuperar conteúdo de todos os tipos.
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Criar e atualizar recursos
As solicitações que analisamos até agora usam o método HTTP GET para recuperar dados do YouTube. A API YouTube Data também oferece métodos que usam HTTP POST para criar ou atualizar recursos do YouTube, como vídeos, playlists ou canais. As solicitações a seguir fornecem exemplos.
Os métodos POST incluem um Request body, que é a representação JSON do recurso que está sendo criado ou atualizado. É possível criar representações JSON no APIs Explorer do Google usando uma ferramenta interativa.
Crie uma assinatura
Essa solicitação inscreve o usuário autenticado no canal GoogleDevelopers. Em outras palavras, ela cria um recurso de assinatura.
POST {base_URL}/subscriptions?part=snippet
Request body: { 'snippet': { 'resourceId': { 'kind': 'youtube#channel', 'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' } } }
Criar uma playlist
Essa solicitação cria uma nova playlist pública.
POST {base_URL}/playlists?part=snippet
Request body: { 'snippet': { 'title': 'New playlist', 'description': 'Sample playlist for Data API', } }
Como adicionar um vídeo a uma lista de reprodução
Agora que criamos uma playlist, vamos adicionar um vídeo a ela. Essa solicitação adiciona um vídeo ao início da playlist ('position': 0).
POST {base_URL}/playlistItems?part=snippet Request body: { 'snippet': { 'playlistId': '{PLAYLIST_ID}', 'resourceId': { 'kind': 'youtube#video', 'videoId': '{VIDEO_ID}' } 'position': 0 } }