A API de dados do YouTube permite que os aplicativos cliente recuperem e atualizem o conteúdo do YouTube na forma de feeds da API de dados do Google. Seu aplicativo cliente pode usar os feeds da API de dados do YouTube para buscar, pesquisar e atualizar vídeos, comentários, respostas, playlists, perfis de usuário e contatos de usuários, bem como consultar vídeos que correspondam a critérios específicos.
Além de fornecer um pouco de informações sobre os recursos da API de dados do YouTube, este documento fornece exemplos para interagir com a API usando a Biblioteca de cliente Python. Para usar a biblioteca de cliente Python, você precisará do Python 2.0+ e dos módulos Element Tree, httplib e urllib. Consulte Módulos de dependência para saber mais detalhes.
Se você precisar de ajuda para configurar a biblioteca de cliente Python, consulte o Guia para iniciantes. Se você quiser saber mais sobre o protocolo subjacente usado pela biblioteca de cliente do Python para interagir com o YouTube, consulte a página do protocolo do guia do desenvolvedor.
Sobre este documento
Público-alvo
Este documento é destinado a programadores que queiram criar aplicativos clientes que possam interagir com o YouTube usando a biblioteca de cliente Python. Ele fornece uma série de exemplos de interações básicas da API de dados.
Para informações sobre referência da API de dados do YouTube, consulte o guia de referência.
Ele pressupõe que você entende as ideias gerais por trás do protocolo das APIs de dados do Google e que saiba programar em Python.
Para informações de referência sobre as classes e os métodos do Python, consulte os pyDocs da classe de serviço e das classes de dados que estão incluídos no código-fonte.
Estrutura do documento
Este documento contém as seguintes seções:
-
A seção Autenticação descreve os dois métodos de autenticação disponíveis para associar operações de API a uma conta de usuário específica. Essa seção também descreve as diferenças entre a autenticação para a API de dados do YouTube e para outras APIs de dados do Google. Neste documento, as explicações das funções específicas da API indicarão claramente se ela exige autenticação do usuário. Em geral, todas as solicitações que modificam dados de vídeo ou feed precisam ser autenticadas. As solicitações somente leitura para vídeos públicos não exigem autenticação.
-
A seção Noções básicas sobre feeds e entradas de vídeos fornece um exemplo de resposta da API e explica como extrair informações sobre um único vídeo de uma lista ou de um conjunto de resultados da pesquisa. Esta seção também explica como acessar metadados sobre uma entrada de vídeo específica. Por fim, esta seção explica o mecanismo para atualizar uma entrada de vídeo individual.
-
A seção Recuperar e pesquisar vídeos explica como buscar listas específicas de vídeos, como um feed padrão dos vídeos mais assistidos do YouTube. Outras listas incluem vídeos enviados por um usuário específico e listas de vídeos relacionados a um determinado vídeo. Esta seção também explica como usar a API para permitir que os usuários pesquisem na biblioteca de vídeos do YouTube por termos ou categorias de pesquisa específicos.
-
A seção Envio de vídeos explica brevemente duas maneiras de permitir que os usuários enviem vídeos ao YouTube usando seu aplicativo. Além disso, essa seção também explica como enviar vídeos como respostas a outros vídeos.
-
A seção Atualizar e excluir vídeos descreve como usar a API para atualizar informações sobre um vídeo do YouTube. Também descreve como um vídeo pode ser removido usando a API.
-
A seção Como usar os recursos da comunidade descreve as funções da API que permitem aos usuários interagir com vídeos do YouTube. Essas funções explicam as solicitações para postar uma classificação, um comentário ou uma reclamação sobre um vídeo existente. Você também pode usar a API para recuperar listas de comentários de vídeos.
-
A seção Como salvar e coletar vídeos explica como usar a API para acessar, criar e atualizar vídeos favoritos, playlists de vídeos e inscrições em canais do YouTube. Ela também mostra como modificar playlists e vídeos favoritos adicionando e removendo vídeos.
-
A seção Ativar a interação do usuário explica como usar a API para recuperar e atualizar perfis de usuário. Essa seção também explica como recuperar, adicionar, atualizar e excluir contatos dos usuários.
Começar
Requisitos
Seu aplicativo cliente pode usar os feeds da API YouTube Data para pesquisar, recuperar e atualizar vídeos, comentários, respostas, playlists, inscrições, perfis de usuários e muito mais.Além de fornecer um pouco de informações sobre os recursos da API de dados do YouTube, este documento fornece exemplos para interagir com a API usando a Biblioteca de cliente Python. Para usar a biblioteca de cliente Python, você precisará do Python 2.2+ e dos módulos Element Tree, httplib e urllib. Consulte Módulos de dependência para saber mais detalhes.
Consulte o Guia para iniciantes para mais informações sobre como configurar seu ambiente. Se você quiser saber mais sobre o protocolo usado pela biblioteca de cliente do Python para interagir com o YouTube, consulte a página do protocolo do guia do desenvolvedor.
Os snippets do exemplo de código abaixo podem ser copiados/colados no seu código e modificados para atender às suas necessidades.
Antes de executar qualquer operação com a API de dados do YouTube, é necessário inicializar um objeto gdata.youtube.service.YouTubeService, conforme mostrado abaixo. As instruções import listadas abaixo executam automaticamente mais importações dos módulos gdata.media e gdata.geo. Todas as ações, exceto a recuperação de conteúdo público, exigem autenticação.
import gdata.youtube import gdata.youtube.service yt_service = gdata.youtube.service.YouTubeService() # Turn on HTTPS/SSL access. # Note: SSL is not available at this time for uploads. yt_service.ssl = True
A maioria dos exemplos de método neste guia funciona em uma instância de
gdata.youtube.service.YouTubeService. Pode ser vantajoso testar as solicitações não autenticadas do intérprete de Python interativo.
Observação: a biblioteca de cliente Python precisa ser adicionada corretamente no seu caminho. Execute o script setup.py fornecido para instalar. Consulte o Guia para iniciantes para mais informações.
Autenticação
A biblioteca de cliente Python pode ser usada para trabalhar com feeds públicos ou privados. Os feeds públicos são somente leitura e não exigem autenticação. Os feeds privados exigem que você faça a autenticação nos servidores do YouTube.
A autenticação pode ser realizada pela autenticação do ClientLogin (para aplicativos para computador) ou pela autenticação tmp (para aplicativos da Web).
Como definir a chave de desenvolvedor e o ID do cliente
Uma chave de desenvolvedor identifica o desenvolvedor do YouTube que está enviando uma solicitação à API. Um ID de cliente identifica o seu aplicativo para fins de login e depuração.
Quando você faz uma solicitação de API usando a biblioteca de cliente Python, o cabeçalho de solicitação X-GData-Key é usado para especificar sua chave de desenvolvedor, e o cabeçalho X-GData-Client é usado para especificar seu ID do cliente. A chave de desenvolvedor e o ID do cliente podem ser definidos no objeto YouTubeService, independentemente do esquema de autenticação usado:
yt_service.developer_key = 'ABCxyz123...' yt_service.client_id = 'My-Client_id'
Você precisa se inscrever para receber uma chave de desenvolvedor do YouTube.
Autenticação tmp para apps da Web
A autenticação por proxy tmp é usada por aplicativos da Web que precisam autenticar seus usuários em contas do YouTube/Google. O operador não precisa de acesso ao nome de usuário e da senha do usuário do YouTube, apenas tokens ISBN especiais são necessários.
Quando o usuário visita seu aplicativo pela primeira vez, ele ainda não foi autenticado nos serviços do Google. Nesse caso, você precisa fornecer um link que direcione o usuário para o Google para autorizar a solicitação dos seus aplicativos de acesso à conta do YouTube deles. A biblioteca de cliente Python fornece uma função para gerar esse URL. O código abaixo configura um link para a página tmpRequest.
def GetAuthSubUrl(): next = 'http://www.example.com/video_upload.pyc' scope = 'http://gdata.youtube.com' secure = False session = True yt_service = gdata.youtube.service.YouTubeService() return yt_service.GenerateAuthSubURL(next, scope, secure, session) authSubUrl = GetAuthSubUrl() print '<a href="%s">Login to your Google account</a>' % authSubUrl
Observe os parâmetros enviados ao método GenerateAuthSubURL dos objetos de serviço:
- Next: o URL da página à qual o YouTube deve redirecionar o usuário depois de autorizar seu aplicativo a acessar a conta dele.
- scope: indicando que o aplicativo acessará somente os feeds da API do YouTube.
- secure: indica que o token retornado não será seguro.
- session: indicando que esse token pode ser trocado por um token multiuso (sessão).
O URL retornado vai ser parecido com este:
https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fgdata.youtube.com&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fvideo_upload.pyc
O usuário poderá clicar no link para fazer login na conta do YouTube. Depois que o usuário autorizar o acesso, a conta será redirecionada para o URL next. O URL terá um valor de token de uso único anexado a ele como um parâmetro de consulta. O URL é semelhante a este:
http://www.example.com/video_upload.pyc?token=Abc123...
A próxima seção vai demonstrar como fazer upgrade desse token. O snippet abaixo demonstra uma das maneiras de recuperar esse token do URL:
import cgi parameters = cgi.FieldStorage() authsub_token = parameters[[]'token' ]
Como fazer upgrade para um token de sessão
Por motivo de segurança, esse token só pode ser usado uma vez. Agora, você precisa trocar esse token de uso único por um token de sessão. Esse processo é descrito na documentação do tmp. O snippet de código abaixo mostra como fazer upgrade do token.
yt_service = gdata.youtube.service.YouTubeService() yt_service.SetAuthSubToken(authsub_token) yt_service.UpgradeToSessionToken()
Esse valor de token representa um token AuthSub de um único uso. Como session = True foi especificado acima, esse token pode ser trocado por um token de sessão tmp usando o método UpgradeToSessionToken, que chama o serviço AuthSubSessionToken.
Seu objeto YouTubeService agora está totalmente autenticado e pode ser usado para realizar todas as outras solicitações com a API YouTube. Os tokens de sessão do XPN não expiram a menos que você emita especificamente uma solicitação para revogá-lo ou o usuário decida revogar o acesso visitando a página Sites autorizados na conta do YouTube.
Autenticação do ClientLogin para aplicativos instalados
A autenticação ClientLogin é usada em aplicativos instalados que podem armazenar ou consultar o usuário quanto a nome de usuário e senha. Para usar essa forma de autenticação, invoque o método ProgrammaticLogin de YouTubeService herdado da classe gdata.service.GDataService, especificando o ID e a senha do usuário em nome do qual o cliente está enviando a solicitação de autenticação.
yt_service = gdata.youtube.service.YouTubeService() yt_service.email = 'jo@gmail.com' yt_service.password = 'mypassword' yt_service.source = 'my-example-application' yt_service.ProgrammaticLogin()
Depois que as credenciais forem definidas, o objeto YouTubeService poderá ser usado para processar todas as outras solicitações. Para realizar uploads e qualquer tipo de solicitação de gravação (como adicionar comentários etc.) à API YouTube, transmita também sua chave de desenvolvedor e o ID do cliente ao objeto yt_service ao realizar a autenticação:
# A complete client login request yt_service.email = 'jo@gmail.com' yt_service.password = 'mypassword' yt_service.source = 'my-example-application' yt_service.developer_key = 'ABC123...' yt_service.client_id = 'my-example-application' yt_service.ProgrammaticLogin()
O objeto YouTubeService define automaticamente os cabeçalhos X-GData-Key e X-GData-Client corretos quando os atributos developer_key e client_id são definidos.
Observação: consulte a documentação de autenticação das APIs de dados do Google para ver informações mais detalhadas sobre os mecanismos tmp e ClientLogin.
Noções básicas dos feeds e entradas de vídeo
A API de dados do YouTube fornece vários feeds de vídeo que representam listas de vídeos, como feeds padrão, envios, inscrições e favoritos. O URL de cada feed está documentado no guia de referência.
Exibir um feed de vídeos
Muitos feeds na API do YouTube consistem em entradas de vídeo. Na maioria dos casos, esses feeds podem ser modelados como objetos gdata.youtube.YouTubeVideoFeed, cada um contendo vários objetos gdata.youtube.YouTubeVideoEntry. Cada entrada corresponde a exatamente um vídeo no YouTube e contém informações sobre ele.
A estrutura básica da recuperação de uma lista de vídeos é a criação de um URL para um feed de vídeo. O processamento das entradas separadamente é similar a este código:
def GetAndPrintVideoFeed(uri):
yt_service = gdata.youtube.service.YouTubeService()
feed = yt_service.GetYouTubeVideoFeed(uri)
for entry in feed.entry:
PrintEntryDetails(entry) # full documentation for this function
A seção Como recuperar e pesquisar vídeos detalha muitos URLs de feeds comuns e como recuperar vários feeds de vídeo.
Como recuperar uma entrada de vídeo específica
Você pode recuperar apenas as informações de uma entrada de vídeo específica se souber o ID do vídeo. O URL de entrada é baseado no ID do vídeo:
http://gdata.youtube.com/feeds/api/videos/videoID
O código a seguir recupera uma gdata.youtube.YouTubeVideoEntry correspondente a um vídeo no YouTube:
entry = yt_service.GetYouTubeVideoEntry(video_id='the0KZLEacs')
Conteúdo da entrada de vídeo
Há muitos metadados que podem ser recuperados em um objeto gdata.youtube.YouTubeVideoEntry, como miniaturas, URLs do player e duração do vídeo. O código a seguir mostra como conseguir algumas dessas informações. A biblioteca de cliente Python abstrai a maioria dessa funcionalidade mapeando elementos XML em classes. A maioria das informações importantes sobre uma entrada YouTubeVideoEntry está disponível nos filhos do atributo media (contendo um objeto gdata.media.Group) na entrada (que representa o elemento XML media:group). Veja abaixo um exemplo de como recuperar metadados de vídeo:
def PrintEntryDetails(entry):
print 'Video title: %s' % entry.media.title.text
print 'Video published on: %s ' % entry.published.text
print 'Video description: %s' % entry.media.description.text
print 'Video category: %s' % entry.media.category[[]0].text
print 'Video tags: %s' % entry.media.keywords.text
print 'Video watch page: %s' % entry.media.player.url
print 'Video flash player URL: %s' % entry.GetSwfUrl()
print 'Video duration: %s' % entry.media.duration.seconds
# non entry.media attributes
print 'Video geo location: %s' % entry.geo.location()
print 'Video view count: %s' % entry.statistics.view_count
print 'Video rating: %s' % entry.rating.average
# show alternate formats
for alternate_format in entry.media.content:
if 'isDefault' not in alternate_format.extension_attributes:
print 'Alternate format: %s | url: %s ' % (alternate_format.type,
alternate_format.url)
# show thumbnails
for thumbnail in entry.media.thumbnail:
print 'Thumbnail url: %s' % thumbnail.url
Observação: para mais informações sobre como gerar as informações necessárias para incorporar um vídeo a um player na página, consulte o guia do protocolo.
Como recuperar e pesquisar por vídeos
Como recuperar feeds padrão
A API de dados do YouTube fornece um feed padrão dos vídeos mais populares do YouTube. Anteriormente, a API era compatível com outros feeds padrão que foram descontinuados. Consulte o guia do desenvolvedor para mais informações.
O URL do feed dos vídeos mais assistidos do YouTube tem o seguinte formato:
http://gdata.youtube.com/feeds/api/standardfeeds/most_popular
Observação: também é possível recuperar feeds padrão específicos da localidade, especificando um localeID no formato: http://gdata.youtube.com/feeds/api/standardfeeds/localeID/feedID. Por exemplo, o conteúdo mais conhecido no Japão seria: http://gdata.youtube.com/feeds/api/standardfeeds/JP/most_popular. Para ver uma lista completa dos supostos localeIDs, consulte o guia de referência.
def PrintVideoFeed(feed):
for entry in feed.entry:
PrintEntryDetails(entry)
def GetAndPrintFeedByUrl:
yt_service = gdata.youtube.service.YouTubeService()
# You can retrieve a YouTubeVideoFeed by passing in the URI
uri = 'http://gdata.youtube.com/feeds/api/standardfeeds/JP/most_popular'
PrintVideoFeed(yt_service.GetYouTubeVideoFeed(uri))
Como recuperar vídeos enviados por um usuário específico
Cada usuário do YouTube tem um feed de vídeo associado aos vídeos que enviou em http://gdata.youtube.com/feeds/api/users/username/uploads.
O código a seguir demonstra como buscar e exibir um feed de uploads de usuários:
def GetAndPrintUserUploads(username): yt_service = gdata.youtube.service.YouTubeService() uri = 'http://gdata.youtube.com/feeds/api/users/%s/uploads' % username PrintVideoFeed(yt_service.GetYouTubeVideoFeed(uri))
Observação:também é possível usar a string "default" no lugar de username para recuperar vídeos do usuário autenticado no momento.
Como recuperar vídeos relacionados
Para recuperar vídeos relacionados, transmita o ID do vídeo do objeto gdata.youtube.YouTubeVideoEntry para o método GetYouTubeRelatedVideoFeed do objeto gdata.youtube.service.YouTubeService. Isso recupera um objeto YouTubeVideoFeed que contém entradas relacionadas.
related_feed = yt_service.GetYouTubeRelatedVideoFeed(video_id='abc123')
Pesquisar vídeos
A API YouTube Data permite solicitar um conjunto de entradas que correspondam a critérios especificados, como a solicitação de entradas de vídeo publicadas por um autor específico, por formato de vídeo ou que contenham uma palavra-chave específica. Para fazer isso, crie um objeto gdata.service.YouTubeVideoQuery com seus critérios de pesquisa específicos e transmita-o para o método
YouTubeQuery do
gdata.youtube.service.YouTubeService.
O exemplo abaixo mostra como realizar uma consulta de pesquisa, com resultados ordenados por contagem de visualizações, incluindo vídeos restritos (chamados de "Racy" pela API):
def SearchAndPrint(search_terms): yt_service = gdata.youtube.service.YouTubeService() query = gdata.youtube.service.YouTubeVideoQuery() query.vq = search_terms query.orderby = 'viewCount' query.racy = 'include' feed = yt_service.YouTubeQuery(query) PrintVideoFeed(feed)
A classe gdata.service.Query e as subclasses como YouTubeVideoQuery são responsáveis por construir URLs de feeds. O VideoQuery mostrado acima constrói um URL equivalente ao seguinte:
http://gdata.youtube.com/feeds/api/videos?vq=<searchTerms>&racy=include&orderby=viewCount
Veja algumas das propriedades mais comuns de YouTubeVideoQuery para definir parâmetros de pesquisa:
author- Define o autor da entrada. O autor é sinônimo de nome de usuário do YouTube.
format- Especifica um formato de vídeo. Aceita parâmetros numéricos para especificar um dos dois tipos de URLs de streaming RTSP na reprodução de vídeos no celular ou um URL HTTP no player de Flash incorporável.
racy- Indica se o conteúdo restrito precisa ser incluído nos resultados. Aceita apenas dois parâmetros: "include" ou "exclude".
max_results- Define o número máximo de entradas a serem retornadas por vez.
start_index- Define o índice com base em 1 do primeiro resultado a ser recuperado (para paginação).
orderby- Define a ordem em que as entradas serão listadas, por exemplo, por
relevance,viewCount,publishedourating. time- Define um período para limitar os resultados padrão do feed a
today,this_week,this_monthouall_time. vq- Define um termo de consulta de pesquisa. Pesquisa a string especificada em todos os metadados de vídeo, como títulos, tags e descrições.
Observação: para mais informações sobre parâmetros de consulta, consulte o Guia de referência da API YouTube Data e o Guia de referência da API Google Data.
Como pesquisar com categorias e palavras-chave
Você pode restringir os resultados da pesquisa para mostrar somente vídeos que correspondam a um determinado conjunto de categorias e palavras-chave. O guia de referência descreve como especificar categorias predefinidas do YouTube (como Música, Pessoas e blogs etc.) e palavras-chave definidas pelo usuário (tags).
O código a seguir demonstra como pesquisar usando palavras-chave (tags) alterando os termos de pesquisa para minúsculas. Observação: como algumas palavras (como "comédia") podem ser uma categoria do YouTube e uma palavra-chave, as consultas de categoria e de palavra-chave usam a convenção de que uma palavra em maiúscula ("comédia") indica uma categoria do YouTube, enquanto uma palavra minúscula ("comédia") indica uma palavra-chave.
def SearchAndPrintVideosByKeywords(list_of_search_terms):
yt_service = gdata.youtube.service.YouTubeService()
query = gdata.youtube.service.YouTubeVideoQuery()
query.orderby = 'viewCount'
query.racy = 'include'
for search_term in list_of_search_terms:
new_term = search_term.lower()
query.categories.append('/%s' % new_term)
feed = yt_service.YouTubeQuery(query)
PrintVideoFeed(feed)
Pesquisa por tags de desenvolvedor
As tags de desenvolvedor são palavras-chave adicionais e ocultas que o desenvolvedor pode usar para incluir conteúdo enviado pelo aplicativo pelos usuários finais. As tags do desenvolvedor são associadas à chave do desenvolvedor definida nos cabeçalhos durante o upload. Essas palavras-chave não ficarão visíveis ao público e poderão ser usadas para recuperar vídeos. Para pesquisar vídeos por uma tag de desenvolvedor específica, envie uma solicitação de pesquisa geral da API YouTube Data usando sua chave de desenvolvedor. Especifique o esquema de categoria e a tag de desenvolvedor a que os vídeos devem corresponder. É possível recuperar um feed de vídeos correspondentes à sua tag de desenvolvedor ("neste link" no nosso exemplo) no URL abaixo:
developer_tag_uri = 'http://gdata.youtube.com/feeds/videos/-/%7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007%2Fdevelopertags.cat%7Dyour_tag_here' yt_service = gdata.youtube.service.YouTubeService() PrintVideoFeed(yt_service.GetYouTubeVideoFeed(developer_tag_uri))
Como enviar vídeos
Consulte os diagramas no guia do protocolo para ter uma visão geral do processo de upload. O envio de vídeos pode ser feito de duas maneiras:
- enviando o vídeo diretamente dos seus servidores pelo método de envio direto
- enviar os metadados primeiro e depois pedir para o usuário enviar o vídeo diretamente ao YouTube pelo método de envio pelo navegador.
Upload direto
Para enviar um vídeo, primeiro você precisa criar um novo objeto gdata.youtube.YouTubeVideoEntry, transmitindo um objeto gdata.media.Group contendo os metadados necessários. O exemplo a seguir mostra como enviar o vídeo do Quicktime "mytestmovie.mov" para o YouTube com as seguintes propriedades:
| Propriedade | Valor |
|---|---|
| Title | Meu filme de teste |
| Categoria | Automáticos |
| Keywords | carros, engraçado |
| Descrição | Minha descrição |
| Nome do arquivo | filmemeuteste.mov |
| Tipo MIME do arquivo | video/quicktime |
| Vídeo privado? | falso |
| Local do vídeo | 37,-122 (lat,long) |
| Tags do desenvolvedor | mydevelopertag, anotherdevelopertag |
O código abaixo cria um YouTubeVideoEntry em branco para fazer upload. O método InsertVideoEntry na YouTubeService exige os seguintes parâmetros:
video_entry: o objetogdata.youtube.VideoEntryque contém metadados.filename_or_handle: um objeto semelhante a um arquivo ou o nome do arquivo em que o vídeo será lido.youtube_username: uma string opcional que especifica o nome de usuário em que a conta vai ser enviada. Sua conta precisará das permissões apropriadas. O padrão é a conta do usuário autenticado no momento.content_type: uma string opcional que especifica o tipo MIME do vídeo a ser enviado.
yt_service se refere a um objeto YouTubeService totalmente autenticado.
# prepare a media group object to hold our video's meta-data
my_media_group = gdata.media.Group(
title=gdata.media.Title(text='My Test Movie'),
description=gdata.media.Description(description_type='plain',
text='My description'),
keywords=gdata.media.Keywords(text='cars, funny'),
category=[[]gdata.media.Category(
text='Autos',
scheme='http://gdata.youtube.com/schemas/2007/categories.cat',
label='Autos')],
player=None
)
# prepare a geo.where object to hold the geographical location
# of where the video was recorded
where = gdata.geo.Where()
where.set_location((37.0,-122.0))
# create the gdata.youtube.YouTubeVideoEntry to be uploaded
video_entry = gdata.youtube.YouTubeVideoEntry(media=my_media_group,
geo=where)
# set the path for the video file binary
video_file_location = '/path/to/my/file.mov'
new_entry = yt_service.InsertVideoEntry(video_entry, video_file_location)
Se quiséssemos marcar nosso vídeo com tags de desenvolvedor opcionais (consulte Como pesquisar por tags de desenvolvedor para saber mais), poderíamos ter usado o método AddDeveloperTags antes de aplicar a chamada a InsertVideoEntry:
developer_tags = [[]'some_tag_01', 'another_tag'] video_entry.AddDeveloperTags(developer_tags)
Observação: para enviar vídeos como privados, é necessário transmitir um atributo privado ao gdata.media.Group.
my_media_group = gdata.media.Group(
title=gdata.media.Title(text='My Test Movie'),
description=gdata.media.Description(description_type='plain',
text='My description'),
keywords=gdata.media.Keywords(text='cars, funny'),
category=[[]gdata.media.Category(
text='Autos',
scheme='http://gdata.youtube.com/schemas/2007/categories.cat',
label='Autos')],
player=None,
private=gdata.media.Private()
)
video_entry = gdata.youtube.YouTubeVideoEntry(media=my_media_group)
# assuming that video_file_location points to a valid path
new_entry = yt_service.InsertVideoEntry(video_entry, video_file_location)
Envio com base no navegador
O envio pelo navegador é quase idêntico ao upload direto, exceto que você não envia o binário do arquivo na mesma solicitação que usa para enviar os metadados do vídeo. Em vez disso, basta criar um YouTubeVideoEntry contendo apenas metadados. Essa entrada de vídeo é postada em um link especial no servidor da API do YouTube. A resposta XML contém um token e um url, que podem ser usados para fazer upload do arquivo binário usando um formulário HTML padrão.
# create media group as usual
my_media_group = gdata.media.Group(
title=gdata.media.Title(text='My Test Movie'),
description=gdata.media.Description(description_type='plain',
text='My description'),
keywords=gdata.media.Keywords(text='cars, funny'),
category=[[]gdata.media.Category(
text='Autos',
scheme='http://gdata.youtube.com/schemas/2007/categories.cat',
label='Autos')],
player=None
)
# create video entry as usual
video_entry = gdata.youtube.YouTubeVideoEntry(media=my_media_group)
# upload meta data only
response = yt_service.GetFormUploadToken(video_entry)
# parse response tuple and use the variables to build a form (see next code snippet)
post_url = response[[]0]
youtube_token = response[[]1]
O código acima imprime um link e um token usado para construir um formulário HTML e exibi-lo no navegador do usuário. Um exemplo de formulário simples é mostrado abaixo com youtube_token representando o conteúdo do elemento de token retornado, conforme mostrado na recuperação de YouTubeVideoEntry acima. Para que o usuário seja redirecionado ao seu site após o envio do formulário, anexe um parâmetro next ao post_url, conforme mostrado abaixo. Ele funcionará da mesma forma que o parâmetro next de um link IFRAME. A única diferença é que, em vez de um token de uso único, uma variável status e uma id são retornadas como parâmetros de URL.
next = 'http://example.com/post_video_upload.pyc'
form = """<form action="%s?nexturl=%s" method="post" enctype="multipart/form-data">
<input name="file" type="file"/>
<input name="token" type="hidden" value="%s"/>
<input value="Upload Video File" type="submit" />
</form>""" % (post_url, next, youtube_token)
A resposta para um upload bem-sucedido seria esta:
http://example.com/post_video_upload.pyc?status=200&id=ABC123
O parâmetro status retorna o status da transação HTTP da transação de upload. O parâmetro id retorna o ID do vídeo do YouTube que foi atribuído ao vídeo enviado.
Como verificar o status do upload
Depois de enviar um vídeo, ele ficará imediatamente visível no feed de envios de um usuário autenticado. No entanto, o site só vai ficar público depois de ser processado. Os vídeos rejeitados ou com falha no envio também serão exibidos somente no feed de envios do usuário autenticado. O código a seguir verifica o status de um YouTubeVideoEntry para ver se ele ainda não está ativo ou se foi rejeitado.
upload_status = yt_service.CheckUploadStatus(new_entry) if upload_status is not None: video_upload_state = upload_status[[]0] detailed_message = upload_status[[]1]
Como atualizar e excluir vídeos
Atualizando informações do vídeo
Para atualizar os metadados de vídeo, basta atualizar o objeto YouTubeVideoEntry e usar o método UpdateVideoEntry dos objetos YouTubeService. Esse método usa como parâmetro um YouTubeVideoEntry que contém metadados atualizados.
# assuming we have a video entry that was just posted in our 'new_entry' variable new_entry.media.title.text = 'My Updated Video Title' new_entry.media.description.text = 'Just updated' updated_entry = yt_service.UpdateVideoEntry(new_entry)
Como excluir um vídeo
Excluir um vídeo é muito simples e envolve apenas uma chamada para o DeleteVideoEntry do objeto YouTubeService.
response = yt_service.DeleteVideoEntry(entry_to_be_deleted) if response: print 'Video successfully deleted!'
Como usar recursos de comunidade
Como adicionar uma avaliação
Para classificar um vídeo, use o método AddRating do objeto YouTubeService. Não é possível classificar seus próprios vídeos e as classificações precisam estar entre 1 e 5.
video_id_to_rate = 'Ncakifd_16k' video_entry = yt_service.GetYouTubeVideoEntry(video_id=video_id_to_rate) response = yt_service.AddRating(3, video_entry)
Comentários
Como recuperar comentários para um vídeo
Com um objeto YouTubeVideoEntry ou um ID de vídeo simples, é possível recuperar e imprimir um feed com os comentários do vídeo usando o método GetYouTubeVideoCommentFeed do objeto YouTubeService. O feed resultante é um gdata.youtube.YouTubeCommentFeed, que consiste em objetos gdata.youtube.YouTubeCommentEntry. O feed pode ser analisado como qualquer outro:
video_id = 'ABC123...' comment_feed = yt_service.GetYouTubeVideoCommentFeed(video_id=video_id) for comment_entry in comment_feed.entry: print comment_entry.ToString()
Adicionar um comentário
Para adicionar um novo comentário, use o método AddComment do objeto YouTubeService. O método exige um objeto YouTubeVideoEntry completo que será comentado, bem como uma string que representa o comentário:
my_comment = 'what a boring test video' video_id = '9g6buYJTt_g' video_entry = yt_service.GetYouTubeVideoEntry(video_id=video_id) yt_service.AddComment(comment_text=my_comment, video_entry=video_entry)
Respostas ao vídeo
Uma resposta ao vídeo do YouTube foi associada a um segundo vídeo, como uma resposta. O recurso de respostas em vídeo foi desativado, conforme explicado neste comunicado. Enquanto as respostas ao vídeo existentes ainda estiverem disponíveis, o YouTube não poderá mais recuperar uma lista de respostas para um vídeo, enviar novas respostas ou excluir respostas ao vídeo, mas você pode excluir o vídeo usado na resposta. Consequentemente, essas funções também não são mais suportadas na API.
As solicitações de API para operações de resposta de vídeo agora retornam o seguinte:
- Uma solicitação para recuperar respostas a um vídeo retorna uma lista vazia.
- Uma solicitação para adicionar uma resposta ao vídeo retorna um código de resposta HTTP 403.
- Uma solicitação para excluir uma resposta em vídeo retorna um código de resposta HTTP 403.
Como sinalizar um vídeo
Para adicionar uma reclamação sobre um vídeo, use o método AddComplaint no objeto YouTubeService. O termo de reclamação precisa ser uma categoria válida. Consulte a seção Como adicionar uma reclamação no guia de protocolos para mais informações.
video_id_to_flag = 'Ncakifd_16k'
complaint_term = 'VIOLENCE'
complaint_text = ('Please ignore this complaint. '
'I\'m testing a YouTube API and needed to issue '
'a complaint to test the add complaint function. ')
response = yt_service.AddComplaint(complaint_text, complaint_term, video_id_to_flag)
Como salvar e colecionar vídeos
Vídeos favoritos
Recuperar os vídeos favoritos de um usuário
Os usuários do YouTube podem escolher marcar os vídeos que assistem como favoritos. O local geral do feed favorito de um usuário é o URL a seguir.
http://gdata.youtube.com/feeds/api/users/username/favorites
Para recuperar os vídeos favoritos de um usuário, use o método GetUserFavoritesFeed do objeto YouTubeService. O método usa uma string opcional como um parâmetro que representa o nome de usuário do YouTube do usuário cujo feed favorito precisa ser recuperado.
favorite_feed = yt_service.GetUserFavoritesFeed(username='gdpython')
O feed retornado é um feed de vídeo normal, contendo objetos YouTubeVideoEntry.
Observação:como alternativa, você pode transmitir a string default para recuperar os favoritos do usuário autenticado no momento. Esse é o comportamento padrão do método GetUserFavoritesFeed se nenhum nome de usuário for fornecido.
Como adicionar um favorito
Para adicionar um vídeo favorito, use o método AddVideoEntryToFavorites do objeto YouTubeService. Os parâmetros são o YouTubeVideoEntry que será adicionado e, opcionalmente, o nome de usuário a que ele deve ser adicionado (o padrão é o usuário autenticado no momento).
video_id = 'Ncakifd_16k' video_entry = yt_service.GetYouTubeVideoEntry(video_id=video_id) response = yt_service.AddVideoEntryToFavorites(video_entry) # The response, if successfully posted is a YouTubeVideoEntry if isinstance(response, gdata.youtube.YouTubeVideoEntry): print 'Video successfully added to favorites'
Como excluir um favorito
Para excluir um favorito, basta usar o método DeleteVideoEntryFromFavorites do objeto YouTubeService.
video_id = 'Ncakifd_16k' response = yt_service.DeleteVideoEntryFromFavorites(video_id) if response is True: print 'Video deleted from favorites'
Playlists
Cada usuário do YouTube tem um feed de playlists que contém todas as playlists que o usuário criou. Cada playlist tem um feed para todos os vídeos contidos nela.
Recuperar playlists de usuários
Para buscar manualmente uma lista de todas as playlists de um usuário, use o seguinte URL:
http://gdata.youtube.com/feeds/api/users/username/playlists
Com a biblioteca de cliente Python, é possível usar o método GetYouTubePlaylistFeed do objeto YouTubeService:
playlist_feed = yt_service.GetYouTubePlaylistFeed(username='gdpython') # instead of passing in a username, you can also pass the URI to the playlist feed: playlist_feed = yt_service.GetYouTubePlaylistFeed(uri='http://gdata.youtube.com/feeds/api/users/default/playlists')
Observação:em vez de transmitir um nome de usuário específico (como "gdpython" no exemplo acima), você também pode transmitir a string 'default' para se referir ao usuário autenticado no momento.
Um gdata.youtube.YouTubePlaylistFeed representa um feed de objetos gdata.youtube.YouTubePlaylistEntry. Elas se referem a playlists individuais que um usuário pode ter. As entradas de vídeo em uma playlist específica são representadas como objetos gdata.youtube.YouTubePlaylistVideoEntry. Esses objetos são muito semelhantes aos objetos gdata.youtube.YouTubeVideoEntry normais, com algumas exceções. Títulos e descrições personalizados podem ser aplicados aos vídeos, e um campo de posição indica onde o vídeo aparece na playlist.
Recuperar informações da reprodução
Com uma YouTubePlaylistEntry (que representa uma playlist específica), é possível ter um YouTubePlaylistVideoFeed contendo objetos YouTubePlaylistVideoEntry. Como explicado acima, esses objetos representam vídeos individuais em uma playlist (com títulos e descrições personalizados opcionais). Você pode ver esse feed transmitindo o URI da playlist para o método GetYouTubePlaylistVideoFeed do objeto YouTubeService:
# a typical playlist URI playlist_uri = 'http://gdata.youtube.com/feeds/api/playlists/BCB3BB96DF51B505' playlist_video_feed = yt_service.GetYouTubePlaylistVideoFeed(uri=playlist_uri) # iterate through the feed as you would with any other for playlist_video_entry in playlist_video_feed.entry: print playlist_video_entry.title.text
Como adicionar uma lista de reprodução
Para adicionar uma nova playlist, basta usar o método AddPlaylist do objeto YouTubeService. Esse método usa os seguintes parâmetros: playlist_title, playlist_description (ambas) e um booleano opcional que pode ser definido como True se a playlist for marcada como privada.
new_public_playlistentry = yt_service.AddPlaylist('my new playlist', 'a new playlist')
if isinstance(new_public_playlistentry, gdata.youtube.YouTubePlaylistEntry):
print 'New playlist added'
# adding a private playlist
new_private_playlistentry = yt_service.AddPlaylist('new private playlist', 'a new private playlist', True)
if isinstance(new_private_playlistentry, gdata.youtube.YouTubePlaylistEntry):
print 'New private playlist added'
Como atualizar uma lista de reprodução
Para atualizar uma playlist, use o método UpdatePlaylist do objeto YouTubeService. O método usa os seguintes parâmetros: o ID da playlist a ser atualizada, um novo título, uma nova descrição, um booleano opcional para marcar a playlist como privada e uma string opcional que indica o nome de usuário proprietário da playlist. A string será padronizada para o usuário autenticado no momento.
# here we are updating a public playlist with a new title while also making it private
# we assume that playlist_to_be_updated here represents a YouTubePlaylistEntry object
playlist_entry_id = playlist_to_be_updated.id.text.split('/')[[]-1]
# we want to keep the original description for the playlist so we store it first
original_description = playlist_to_be_updated.description.text
updated_playlist = yt_service.UpdatePlaylist(playlist_entry_id,
'a new updated title',
original_playlist_description,
playlist_private=True)
Adicionar vídeo à lista de reprodução
Você pode adicionar um vídeo a uma playlist usando o método AddPlaylistVideoEntryToPlaylist do objeto YouTubeService. O código abaixo adiciona um vídeo a uma playlist, com um título e uma descrição personalizados.
custom_video_title = 'my test video on my test playlist'
custom_video_description = 'this is a test video on my test playlist'
video_id = 'Ncakifd_16k'
playlist_uri = 'http://gdata.youtube.com/feeds/api/playlists/BCB3BB96DF51B505'
playlist_video_entry = yt_service.AddPlaylistVideoEntryToPlaylist(
playlist_uri, video_id, custom_video_title, custom_video_description)
if isinstance(playlist_video_entry, gdata.youtube.YouTubePlaylistVideoEntry):
print 'Video added'
Observação: não é preciso definir um título e uma descrição personalizados. Se esses itens não forem especificados, serão usados o título e a descrição reais do vídeo.
Editar informações do vídeo na playlist
Use o método UpdatePlaylistVideoEntryMetaData do objeto YouTubeService para mudar os metadados de uma YouTubePlaylistVideoEntry. No exemplo abaixo, decidimos dar um novo título personalizado ao vídeo, e movê-lo para a primeira posição (posição 1) na playlist.
playlist_uri = 'http://gdata.youtube.com/feeds/api/playlists/BCB3BB96DF51B505'
playlist_entry_id = 'B0F29389E537F888'
new_video_title = 'a useful video'
new_video_description = 'updated video description'
updated_playlist_video_entry = yt_service.UpdatePlaylistVideoEntryMetaData(
playlist_uri, playlist_entry_id, new_video_title, new_video_description, 1)
Observação: se você quiser reverter a descrição e o título de um vídeo em uma playlist de volta para os metadados originais, basta transmitir NULL para o título e a descrição.
Remover vídeo da playlist
Para remover um vídeo de uma playlist, use o método DeletePlaylistVideoEntry do objeto YouTubeService. O método exige que o URI da playlist que contém a entrada seja excluída, assim como o ID da entrada:
playlist_uri = 'http://gdata.youtube.com/feeds/api/playlists/BCB3BB96DF51B505'
playlist_entry_id = 'B0F29389E537F888'
response = yt_service.DeletePlaylistVideoEntry(playlist_uri,
playlist_entry_id)
if response is True:
print 'Entry successfully deleted'
Excluir uma playlist
Para excluir uma playlist, basta usar o método DeletePlaylist do objeto YouTubeService, transmitindo o URI da playlist a ser excluída:
playlist_uri = 'http://gdata.youtube.com/feeds/api/playlists/BCB3BB96DF51B505' response = yt_service.DeletePlaylist(playlist_uri) if response is True: print 'Playlist successfully deleted'
Inscrições
Para buscar uma lista de canais, pesquisas e favoritos em que um determinado usuário está inscrito, use o seguinte URI:
http://gdata.youtube.com/feeds/api/users/username/subscriptions
Observação: como alternativa, você pode transmitir a string default para recuperar os favoritos do usuário autenticado no momento.
Recuperar assinaturas de usuários
O código a seguir demonstra como recuperar e imprimir a lista de assinaturas de um determinado usuário. As assinaturas são representadas como um gdata.youtube.YouTubeSubscriptionFeed, que consiste em objetos gdata.youtube.YouTubeSubscriptionEntry. Para recuperar assinaturas, use o método GetYouTubeSubscriptionFeed do objeto YouTubeService, transmitindo o URI de um feed de assinatura ou o nome de usuário que precisa ser recuperado. Por padrão, o parâmetro de nome de usuário é o usuário autenticado no momento.
subscription_feed = yt_service.GetYouTubeSubscriptionFeed(username='gdpython')
if isinstance(subscription_feed, gdata.youtube.YouTubeSubscriptionFeed)):
# given a YouTubeSubscriptionEntry we can determine it's type (channel, favorite, or query)
for entry in subscription_feed.entry:
print entry.GetSubscriptionType()
Como adicionar uma inscrição
Você pode criar uma nova assinatura inserindo um novo YouTubeSubsciptionEntry no feed de inscrições do usuário autenticado. Podemos criar três tipos de assinatura: uma assinatura para o canal de um usuário (usando AddSubscriptionToChannel), uma assinatura para os favoritos de um usuário (usando AddSubscriptionToFavorites ou uma assinatura para uma palavra-chave específica (usando AddSubscriptionToQuery). O código a seguir inscreve o usuário autenticado no canal "GoogleDevelopers".
new_subscription = yt_service.AddSubscriptionToChannel(
username_to_subscribe_to='GoogleDevelopers')
if isinstance(new_subscription, gdata.youtube.YouTubeSubscriptionEntry):
print 'New subscription added'
Você também pode se inscrever nos favoritos do usuário "GoogleDevelopers":
new_subscription = yt_service.AddSubscriptionToFavorites(
username='GoogleDevelopers')
if isinstance(new_subscription, gdata.youtube.YouTubeSubscriptionEntry):
print 'New subscription added'
Por fim, você também pode se inscrever em termos de pesquisa específicos. Aqui estamos assinando uma consulta para vídeos marcados com "python".
new_subscription = yt_service.AddSubscriptionToQuery(query='python') if isinstance(new_subscription, gdata.youtube.YouTubeSubscriptionEntry): print 'New subscription added'
Como excluir uma inscrição
Para excluir uma assinatura de usuário, use o método DeleteSubscription do objeto YouTubeService.
sample_subscription_uri = ('http://gdata.youtube.com/feeds/api/users/'
'gdpython/subscriptions/c0c77ca6102a7479')
response = yt_service.DeleteSubscription(sample_subscription_uri)
if response is True:
print 'Subscription successfully deleted'
Como ativar a interação do usuário
Perfis de usuário
Como recuperar o perfil de um usuário
Para buscar o perfil de um usuário manualmente no YouTube, você usaria o seguinte URI:
http://gdata.youtube.com/feeds/api/users/username
Você pode recuperar um gdata.youtube.YouTubeUserEntry com o método GetYouTubeUserEntry do objeto YouTubeService.
user_entry = yt_service.GetYouTubeUserEntry(username='gdpython')
# we can then write a helper function to print out the user details
def PrintUserEntry(entry):
# print required fields where we know there will be information
print 'URI: %s\n' % entry.id.text
print 'Age: %s\n' % entry.age.text
print 'Gender: %s\n' % entry.gender.text
print 'Location: %s\n' % entry.location.text
# check if there is information in the other fields and if so print it
if user.first_name:
print 'First Name: %s\n' % user.first_name.text
if user.last_name:
print 'Last Name: %s\n' % user.last_name.text
if user.relationship:
print 'Relationship: %s\n' % user.relationship.text
if user.description:
print 'About me: %s\n' % user.description.text
for link in user.link:
if link.rel == 'related':
print 'Website: %s\n' % link.href
if user.company:
print 'Company: %s\n' % user.company.text
if user.occupation:
print 'Occupation: %s\n' % user.occupation.text
if user.school:
print 'School: %s\n' % user.school.text
if user.hobbies:
print 'Hobbies: %s\n' % user.hobbies.text
if user.movies:
print 'Movies: %s\n' % user.movies.text
if user.music:
print 'Music: %s\n' % user.music.text
if user.books:
print 'Books: %s\n' % user.books.text
if user.hometown:
print 'Hometown: %s\n' % user.hometown.text
Contatos
A lista de contatos de um determinado usuário pode ser recuperada com este URL:
http://gdata.youtube.com/feeds/api/users/username/contacts
Como recuperar contatos do usuário
O método GetYouTubeContactFeed do objeto YouTubeService pode ser usado para recuperar um gdata.youtube.YouTubeContactFeed, que consiste em objetos gdata.youtube.YouTubeContactEntry.
contact_feed = yt_service.GetYouTubeContactFeed(username='GoogleDevelopers')
for entry in contact_feed.entry:
print entry.title.text
# find the apprpriate category element to find out the contact type
for category in entry.category:
if category.scheme == 'http://gdata.youtube.com/schemas/2007/contact.cat':
print category.term
Como adicionar um contato
Para adicionar um novo contato ao feed de contatos de um usuário, use o método AddContact do objeto YouTubeService.
new_contact = yt_service.AddContact(contact_username='GoogleDevelopers') if isinstance(new_contact, gdata.youtube.YouTubeContactEntry) print 'New contact added'
Aceitar/rejeitar um contato
Para atualizar um contato, use o método UpdateContact do objeto YouTubeService. Esse método pode ser usado para aceitar/rejeitar solicitações de contatos e também categorizar os contatos como "Amigo" ou "Família". No exemplo abaixo, aceitamos um contato e definimos a categoria como "Família":
# in this case user 'gdpython' has requested to be our contact
#so the original contact status is 'pending'
updated_contact = yt_service.UpdateContact('gdpython', 'accepted', 'Family')
if isinstance(updated_contact, gdata.youtube.YouTubeContactEntry)
print 'New contact added'
Como excluir um contato
Para excluir um contato, use o método DeleteContact do objeto YouTubeService e transmita o nome de usuário do contato que você quer excluir.
response = yt_service.DeleteContact(contact_username='gdpython') if response is True: print 'Contact deleted'