A API de dados do YouTube permite a incorporação de funções normalmente executadas no site do YouTube em seu próprio site ou aplicativo. A lista abaixo identifica os diferentes tipos de recursos que você pode recuperar usando a API. A API também suporta métodos para inserir, atualizar ou excluir muitos desses recursos.
Este guia de referência explica como usar a API para executar todas essas operações. O guia está organizado por tipo de recurso. Um recurso representa um tipo de item que compreende parte da experiência do YouTube, como um vídeo, uma playlist ou uma inscrição. Para cada tipo de recurso, o guia lista uma ou mais representações de dados, e os recursos são representados como objetos JSON. O guia também lista um ou mais métodos suportados (LIST
, POST
, DELETE
etc.) para cada tipo de recurso e explica como usar esses métodos em seu aplicativo.
Chamando a API
Os seguintes requisitos aplicam-se às solicitações de API de dados do YouTube:
-
Cada solicitação deve especificar uma chave de API (com o parâmetro
key
) ou fornecer um token do OAuth 2.0. Sua chave de API está disponível no painel Acesso à API do console da API para seu projeto. -
Você deve enviar um token de autorização para cada solicitação de inserção, atualização e exclusão. Você também deve enviar um token de autorização para qualquer solicitação que recupera os dados privados do usuário autenticado.
Além disso, alguns métodos de API para recuperação de recursos podem suportar parâmetros que necessitam de autorização ou podem conter metadados adicionais quando as solicitações são autorizadas. Por exemplo, uma solicitação para recuperar os vídeos enviados de um usuário também pode conter vídeos privados, se a solicitação for autorizada por esse usuário específico.
-
A API suporta o protocolo de autenticação OAuth 2.0. Você pode fornecer um token do OAuth 2.0 de uma das seguintes formas:
- Use o parâmetro de consulta
access_token
como este:?access_token=
oauth2-token
- Use o cabeçalho HTTP
Authorization
como este:Authorization: Bearer
oauth2-token
Instruções completas para a implementação da autenticação OAuth 2.0 em seu aplicativo podem ser encontradas no guia de autenticação.
- Use o parâmetro de consulta
Tipos de recursos
A API interage com os seguintes tipos de recursos:
- activities
- channelBanners
- channels
- guideCategories
- playlistItems
- playlists
- search
- subscriptions
- thumbnails
- videoCategories
- videos
activities
Um recurso activity
contém informações sobre uma ação que um determinado canal ou usuário realizou no YouTube. As ações relatadas nos feeds de atividades incluem classificar e compartilhar um vídeo, marcar um vídeo como favorito, comentar sobre um vídeo, fazer upload de um vídeo, e assim por diante. Cada recurso activity
identifica o tipo de ação, o canal associado à ação e o(s) recurso(s) associado(s) com a ação, como o vídeo que foi avaliado ou carregado.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
list |
GET /activities |
Retorna uma lista de eventos de atividade do canal que correspondem aos critérios da solicitação. Por exemplo, você pode recuperar eventos associados a um determinado canal, eventos associados a inscrições do usuário e amigos do Google+ ou o feed da página inicial do YouTube, que é personalizado para cada usuário. |
insert |
POST /activities |
Mensagens de um boletim para um canal específico. (O usuário que envia a solicitação deve estar autorizado a agir em nome do canal.) Nota: Embora um recurso de activity possa conter informações sobre ações, como classificar um vídeo de um usuário ou marcar um vídeo como favorito, você precisa usar outros métodos de API para gerar esses recursos activity . Por exemplo, você poderia usar o método videos.rate() da API para classificar um vídeo e o método playlistItems.insert() para marcar um vídeo como favorito. |
channelBanners
Um recurso channelBanner
contém a URL que você usaria para definir uma imagem recém-carregada como a imagem do banner de um canal.
Para mais informações sobre este recurso, consulte sua representação de recurso e a lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
insert |
POST /channelBanners/insert |
Carrega uma imagem de banner de canal no YouTube. Este método representa as duas primeiras etapas de um processo de três etapas para atualizar a imagem do banner para um canal:
|
channels
Um recurso de channel
contém informações sobre um canal do YouTube.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
list |
GET /channels |
Retorna um conjunto de zero ou maisl recursos de channel que correspondem aos critérios da solicitação. |
update |
PUT /channels |
Atualiza os metadados de um canal. Observe que este método atualmente suporta apenas atualizações dos objetos brandingSettings e invideoPromotion do recurso channel e suas propriedades filho. |
guideCategories
Um recurso de guideCategory
identifica uma categoria que o YouTube atribui algoritmicamente com base no conteúdo ou em outros indicadores de um canal, como a popularidade do canal. A lista é semelhante a categorias de vídeo , com a diferença de que o aplicativo de envio de um vídeo pode atribuir uma categoria de vídeo, mas somente o YouTube pode atribuir uma categoria de canal.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
list |
GET /guideCategories |
Retorna uma lista de categorias que podem ser associadas a canais do YouTube. |
playlistItems
O recurso playlistItem
identifica outro recurso incluído em uma playlist, como um vídeo por exemplo. Além disso, o recurso playlistItem
contém detalhes sobre o recurso incluído que dizem respeito especificamente à forma como esse recurso é usado nessa playlist.
O YouTube usa playlists para identificar conjuntos especiais de vídeos para um canal, tais como:
- vídeos enviados
- vídeos favoritos
- vídeos avaliados positivamente (gostei)
- histórico de exibição
- assistir mais tarde
Você pode recuperar o IDs da playlist para cada uma dessas listas a partir do
channel resource
para um determinado canal. Em seguida, você pode usar o método playlistItems.list
para recuperar qualquer uma dessas listas. Você também pode adicionar ou remover itens dessas listas chamando os métodos playlistItems.insert
e playlistItems.delete
. Por exemplo, se um usuário marca um vídeo como um vídeo favorito, você deve inserir esse vídeo na playlist de vídeos favoritos para o canal desse usuário.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /playlistItems |
Exclui um item da playlist. |
insert |
POST /playlistItems |
Adiciona um recurso a uma playlist. |
list |
GET /playlistItems |
Retorna um conjunto de itens da playlist que correspondem aos parâmetros da solicitação de API. Você pode recuperar todos os itens da playlist em uma playlist especificada ou recuperar um ou mais itens da playlist por seus IDs exclusivos. |
update |
PUT /playlistItems |
Modifica um item da playlist. Por exemplo, você poderia atualizar a posição do item na playlist. |
playlists
Um recurso de playlist
representa uma lista de reprodução do YouTube. Uma playlist é um conjunto de vídeos que podem ser visualizados em sequência e compartilhados com outros usuários. Uma playlist pode conter até 200 vídeos e o YouTube não limita o número de playlists que cada usuário cria. Por padrão, as playlists ficam visíveis publicamente a outros usuários, mas elas podem ser públicas ou privadas.
O YouTube também usa playlists para identificar conjuntos especiais de vídeos para um canal, tais como:
- vídeos enviados
- vídeos favoritos
- vídeos avaliados positivamente (gostei)
- histórico de exibição
- assistir mais tarde
channel resource
para um determinado canal.Em seguida, você pode usar o método
playlistItems.list
para recuperar qualquer uma dessas listas. Você também pode adicionar ou remover itens dessas listas chamando os métodos playlistItems.insert
e playlistItems.delete
.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /playlists |
Exclui uma playlist. |
list |
GET /playlists |
Retorna um conjunto de playlists que correspondem aos parâmetros da solicitação de API. Por exemplo, você pode recuperar todas as playlists que o usuário autenticado possui ou recuperar uma ou mais playlists por seus IDs únicos. |
insert |
POST /playlists |
Cria uma playlist. |
update |
PUT /playlists |
Modifica uma playlist. Por exemplo, você pode alterar o título, a descrição ou o status de privacidade de uma playlist. |
search
Um resultado de pesquisa contém informações sobre um vídeo, canal ou playlist do YouTube que correspondem a parâmetros de pesquisa especificados em uma solicitação de API. Embora um resultado de pesquisa aponte para um recurso exclusivamente identificável, como um vídeo, ele não tem seus próprios dados persistentes.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
list |
GET /search |
Retorna um conjunto de resultados de pesquisa que correspondem a parâmetros de consulta especificados na solicitação da API. Por padrão, um conjunto de resultados de pesquisa identifica recursos de video , channel e playlist correspondentes, mas você também pode configurar consultas para recuperar somente um tipo específico de recurso. |
subscriptions
Um recurso de subscription
contém informações sobre uma inscrição de usuário do YouTube. Uma inscrição notifica o usuário quando novos vídeos são adicionados a um canal ou quando outro usuário executa uma das várias ações no YouTube, como o upload ou a classificação de um vídeo ou comentários sobre um vídeo.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
delete |
DELETE /subscriptions |
Exclui uma inscrição. |
insert |
POST /subscriptions |
Adiciona uma inscrição para o canal do usuário autenticado. |
list |
GET /subscriptions |
Retorna recursos de inscrição que correspondem a critérios da solicitação da API. |
thumbnails
Um recurso thumbnail
identifica diferentes tamanhos de imagens em miniatura associadas a um recurso. Observe as seguintes características das imagens em miniatura:
- Uma propriedade
snippet.thumbnails
do recurso é um objeto que identifica as imagens em miniatura disponíveis para esse recurso. - Um recurso
thumbnail
contém uma série de objetos. O nome de cada objeto (default
,medium
,high
, etc.) refere-se ao tamanho da imagem em miniatura. - Diferentes tipos de recursos podem suportar diferentes tamanhos de imagens em miniatura.
- Diferentes tipos de recursos podem definir tamanhos diferentes para imagens em miniatura com o mesmo nome. Por exemplo, a imagem em miniatura
default
de um recurso devideo
normalmente é 120px por 90px, e a imagem em miniaturadefault
para um recurso dechannel
normalmente é 88px por 88px. - Recursos do mesmo tipo ainda podem ter diferentes tamanhos de imagem em miniatura para determinadas imagens, dependendo da resolução da imagem original ou do conteúdo carregado no YouTube. Por exemplo, um vídeo em HD pode apoiar miniaturas de resolução maior que vídeos não-HD.
- Cada objeto que contém informações sobre um tamanho de imagem em miniatura tem uma propriedade
width
e uma propriedadeheight
. No entanto, as propriedades de largura e altura podem não ser retornadas para essa imagem. - Se uma imagem em miniatura carregada não corresponder às dimensões necessárias, a imagem será redimensionada para corresponder ao tamanho correto, sem alteração de sua proporção. A imagem não é cortada, mas pode incluir barras pretas para que o tamanho fique correto.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
set |
POST /thumbnails/set |
Carrega uma miniatura de vídeo personalizada para o YouTube e a define para um vídeo. |
videoCategories
Um recurso videoCategory
identifica uma categoria que foi associada ou poderia ser associada a vídeos enviados.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
list |
GET /videoCategories |
Retorna uma lista de categorias que podem ser associadas a vídeos do YouTube. |
videos
Um recurso de video
representa um vídeo do YouTube.
Para mais informações sobre este recurso, consulte sua representação de recurso e lista de propriedades.
Método | Solicitação HTTP | Descrição |
---|---|---|
URIs relacionados a https://www.googleapis.com/youtube/v3 |
||
insert |
POST /videos |
Envia um vídeo para o YouTube e, opcionalmente, define os metadados do vídeo. |
list |
GET /videos |
Retorna uma lista de vídeos que correspondem aos parâmetros de solicitação da API. |
delete |
DELETE /videos |
Exclui um vídeo do YouTube. |
update |
PUT /videos |
Atualiza os metadados de um vídeocanal.. |
rate |
POST /videos/rate |
Adiciona uma classificação gostei ou não gostei a um vídeo ou remove uma classificação de um vídeo. |
getRating |
GET /videos/getRating |
Recupera as classificações que o usuário autorizado deu a uma lista de vídeos especificados. |