Getting Started with the YouTube Data API

Introdução

Este documento é destinado a desenvolvedores que desejam criar aplicativos que interagem com o YouTube. Ele explica os conceitos básicos do YouTube e da própria API. Também oferece uma visão geral das diferentes funções compatíveis com a API.

Antes de começar

  1. Você precisa de uma Conta do Google para acessar o Console de APIs do Google, solicitar uma chave da API e cadastrar seu aplicativo.

  2. Cadastre seu aplicativo no Google para que ele possa enviar solicitações de API.

  3. Após cadastrar seu aplicativo, selecione a API de dados do YouTube como um dos serviços usados por seu aplicativo:

    1. Acesse o Console de APIs e selecione o projeto que você acabou de cadastrar.
    2. Clique no painel Serviços.
    3. Na lista de APIs, mude o status da API de dados do YouTube para ON.

  4. Familiarize-se com os conceitos fundamentais do formato de dados JSON (JavaScript Object Notation, Notação de objeto do JavaScript). JSON é um formato de dados comum e independente de linguagem que fornece uma representação de texto simples de estruturas de dados arbitrárias. Acesse json.org para mais informações.

Recursos e tipos de recursos

Um recurso é uma entidade individual de dados com um identificador exclusivo. A tabela abaixo descreve os diferentes tipos de recursos com os quais você pode interagir usando a API.

Recursos
activity Contém informações sobre uma ação que determinado usuário executou no site do YouTube. Ações do usuário que são informadas em feeds de atividades incluem a classificação de um vídeo, o compartilhamento de um vídeo, a marcação de um vídeo como favorito, a publicação de um boletim do canal etc.
channel Contém informações sobre um canal simples do YouTube.
channelBanner Identifica o URL que será usado para definir uma imagem recém-enviada como imagem do banner de um canal.
guideCategory Identifica uma categoria que o YouTube associa aos canais com base em seu conteúdo ou outros indicadores, como a popularidade. As categorias de guia servem para organizar canais de modo que os usuários do YouTube possam encontrar com mais facilidade o conteúdo que procuram. Embora os canais possam ser associados a uma ou mais categorias de guia, não é certeza que eles estejam em uma delas.
playlist Representa uma playlist simples do YouTube. Uma playlist é um conjunto de vídeos que podem ser visualizados em sequência e compartilhados com outros usuários.
playlistItem Identifica um recurso, como um vídeo, que faz parte de uma playlist. O recurso playlistItem também contém detalhes que explicam como o recurso incluso é usado na playlist.
search result Contém informações sobre um vídeo, um canal ou uma playlist do YouTube que corresponde aos parâmetros de pesquisa especificados em uma solicitação da API. Embora indique um recurso exclusivamente identificável (como um vídeo), um resultado de pesquisa não tem seus próprios dados persistentes.
subscription Contém informações sobre a inscrição de um usuário do YouTube. Uma assinatura 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.
thumbnail Identifica imagens em miniatura associadas a um recurso.
video Representa um vídeo simples do YouTube.
videoCategory Identifica uma categoria que foi ou pode ser associada a vídeos enviados.

Observação: em muitos casos, um recurso contém referências a outros recursos. Por exemplo, a propriedade de um playlistItem recurso snippet.resourceId.videoId identifica um recurso de vídeo que, por sua vez, contém informações completas sobre o vídeo. Outro exemplo: o resultado de uma pesquisa contém uma propriedade videoId , playlistId ou channelId propriedade que identifica determinado recurso de canal, playlist ou vídeo.

Operações compatíveis

A tabela a seguir mostra os métodos mais comuns compatíveis com a API. Alguns recursos também são compatíveis com outros métodos que executam funções mais específicas a esses recursos. Por exemplo, o método videos.rate associa uma avaliação de usuários a um vídeo, e o método thumbnails.set envia uma imagem em miniatura do vídeo para o YouTube, associando-a a um vídeo.

Operaçãoes
list Recupera (GET) uma lista vazia ou com recursos.
insert Cria (POST) um novo recurso.
update Modifica (PUT) um recurso existente para propagar os dados em sua solicitação.
delete Remove (DELETE) um recurso específico.

A API é compatível com métodos para listar todos os tipos de recursos compatíveis, além de aceitar operações de gravação em diversos recursos.

A tabela abaixo identifica as operações que são compatíveis com diferentes tipos de recursos. Operações que inserem, atualizam ou excluem recursos sempre precisam de autorização do usuário. Em alguns casos, os métodos list são compatíveis com solicitações autorizadas e não autorizadas. As solicitações não autorizadas recuperam apenas dados públicos, e as solicitações autorizadas também podem recuperar informações sobre ou particulares ao usuário atualmente autenticado.

Operações suportadas
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

Uso de quotas

O YouTube Data API usa uma quota para garantir que os desenvolvedores usem o serviço conforme pretendido e não criem aplicativos que reduzem injustamente a qualidade do serviço ou limitam o acesso para os outros. É possível encontrar a quota disponível para seu aplicativo no painel Quotas do API console's.

O Google calcula o uso da quota atribuindo um custo a cada solicitação, mas o custo não é o mesmo para cada solicitação. Dois fatores principais influenciam o custo da quota de uma solicitação:

  1. Diferentes tipos de operações têm diferentes custos de quotas.

    • A operação de leitura simples que recupera apenas o ID de cada recurso devolvido tem um custo de aproximadamente 1 unidade.
    • A operação de gravação tem um custo de aproximadamente 50 unidades.
    • O envio de um vídeo tem um custo de aproximadamente 1600 unidades.

  2. Dependendo de quantas partes do recurso são recuperadas por cada solicitação de recursos, as operações de leitura e gravação usar várias quantidades de quotas diferentes. As operações insert e update gravam dados e também devolvem um recurso. Por exemplo, a inclusão de uma playlist tem um custo de quota de 50 unidades para a operação de gravação, além do custo do recurso devolvido da playlist.

    Conforme discutido na seção a seguir, cada recurso de API é dividido em partes. Por exemplo, um recurso de playlist tem duas partes (snippet e status), enquanto um recurso de channel tem seis partes, e um recurso de video tem 10. Cada parte contém um grupo de propriedades relacionadas, e os grupos são criados de modo que seu aplicativo só precise recuperar os tipos de dados que realmente usa.

    Uma solicitação da API que devolve dados de recursos deve especificar as partes dos recursos recuperadas pela solicitação. Sendo assim, cada parte adiciona cerca de 2 unidades ao custo de quota da solicitação. Portanto, uma solicitação videos.list que só recupera a parte snippet de cada vídeo pode ter um custo de 3 unidades. No entanto, uma solicitação videos.list que recupera todas as partes de cada recurso pode ter um custo de aproximadamente 21 unidades de quota.

Considerando essas regras, você pode estimar o número de solicitações de leitura, gravação ou envio que seu aplicativo pode enviar por dia sem exceder sua quota. Por exemplo, se você tiver uma quota diária de 5.000.000 unidades, o aplicativo poderá ter qualquer um dos seguintes limites aproximados:

  • 1.000.000 operações de leitura, sendo que cada uma recupera duas partes de recursos.
  • 50.000 operações de gravação e 450.000 operações de leitura adicionais, sendo que cada uma recupera duas partes de recursos.
  • 2.000 envios de vídeo, 7.000 operações de gravação e 200.000 operações de leitura, sendo que cada uma recupera três partes de recursos.

Importante: apenas a recuperação de partes de recursos necessárias para seus aplicativos é o suficiente para conservar sua quota diária e tornar todo o sistema mais eficiente.

Recursos parciais

A API permite e, na prática, requer a recuperação de recursos parciais para que os aplicativos evitem a transferência, a análise e o armazenamento de dados desnecessários. Essa abordagem também garante que a API use os recursos de rede, CPU e memória de forma mais eficiente.

A API é compatível com dois parâmetros de solicitação (explicados nas seções a seguir), que permitem identificar as propriedades de recursos que devem ser incluídas nas respostas da API.

  • O parâmetro part identifica grupos de propriedades que devem ser devolvidos a um recurso.
  • O parâmetro fields filtra a resposta da API para devolver apenas propriedades específicas nas partes de recursos solicitadas.

Compreender o parâmetro part

O parâmetro part é obrigatório em qualquer solicitação da API que recupere ou devolva um recurso. O parâmetro identifica uma ou mais propriedades de recursos de alto nível (não agrupadas) que devem ser incluídas em uma resposta da API. Por exemplo, um recurso video contém as seguintes partes:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

Todas essas partes são objetos que contêm propriedades agrupadas, e esses objetos são considerados grupos de campos de metadados que podem (ou não) ser recuperados pelo servidor da API. Dessa forma, o parâmetro part exige que você selecione os componentes de recursos realmente usados por seu aplicativo. Essa exigência é feita por diversos motivos:

  • Permite que você gerencie o uso da quota da API. Se você aumentar o número de partes recuperadas nas respostas da API, o uso da API aumentará consequentemente e sua quota disponível diminuirá.
  • Reduz a latência evitando que o servidor da API perca tempo recuperando campos de metadados que não são usados por seu aplicativo.
  • Reduz o uso de largura de banda diminuindo (ou eliminando) a quantidade de dados desnecessários que seu aplicativo pode recuperar.

Com o passar do tempo, conforme os recursos adicionam mais partes, esses benefícios só aumentarão se seu aplicativo não solicitar propriedades recém-introduzidas incompatíveis.

Compreender o parâmetro fields

O parâmetro fields filtra a resposta da API, que contém apenas frações de recursos identificadas no valor do parâmetro part para que a resposta tenha apenas um conjunto específico de campos. O parâmetro fields permite remover propriedades agrupadas de uma resposta da API e, com isso, reduzir ainda mais o uso de largura de banda (o parâmetro part não pode ser usado para filtrar as propriedades agrupadas de uma resposta).

As regras a seguir explicam a sintaxe compatível com o valor do parâmetro fields, que é vagamente baseado na sintaxe XPath:

  • Use uma lista separada por vírgulas (fields=a,b) para selecionar vários campos.
  • Use um asterisco (fields=*) como caractere universal para identificar todos os campos.
  • Use parênteses (fields=a(b,c)) para especificar um conjunto de propriedades agrupadas que será incluído na resposta da API.
  • Use uma barra (fields=a/b) para identificar uma propriedade agrupada.

Na prática, essas regras geralmente permitem que diversos valores do parâmetro fields recebam a mesma resposta da API. Por exemplo, para recuperar a posição, o título e ID do item da playlist de cada item em uma playlist, você pode usar um dos seguintes valores:

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

Observação: assim como ocorre em todos os valores de parâmetros de consulta, o valor do parâmetro fields deve ser um URL codificado. Para facilitar a leitura, os exemplos deste documento omitem a codificação.

Exemplos de solicitações parciais

Os exemplos abaixo demonstram como usar os parâmetros part e fields para garantir que as respostas da API incluam apenas os dados usados por seu aplicativo:

  1. O exemplo 1 devolve um recurso de vídeo que inclui quatro partes, assim como as propriedades kind e etag.
  2. O exemplo 2 devolve um recurso de vídeo que inclui duas partes, assim como as propriedades kind e etag.
  3. O exemplo 3 devolve um recurso de vídeo que inclui duas partes, porém exclui as propriedades kind e etag.
  4. O exemplo 4 devolve um recurso de vídeo que inclui duas partes, porém exclui kind e etag, assim como algumas propriedades agrupadas no objeto snippet do recurso.
Exemplo 1

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status
Descrição: este exemplo recupera um recurso video e identifica várias partes de recursos que devem ser incluídas na resposta da API. Resposta da API:
{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "contentDetails": { "duration": "PT15M51S", "aspectRatio": "RATIO_16_9" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" }, "status": { "uploadStatus": "STATUS_PROCESSED", "privacyStatus": "PRIVACY_PUBLIC" } } ] }
Exemplo 2

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics
Descrição: este exemplo modifica o parâmetro part de modo que as propriedades contentDetails e status não sejam incluídas na resposta. Resposta da API:
{ "kind": "youtube#videoListResponse", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"", "videos": [ { "id": "7lCDEYXw3mM", "kind": "youtube#video", "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
Exemplo 3

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,statistics&fields=items(id,snippet,statistics)
Descrição: este exemplo adiciona o parâmetro fields para remover todas as propriedades kind e etag da resposta da API. Resposta da API:
{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "publishedAt": "2012-06-20T22:45:24.000Z", "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.", "thumbnails": { "default": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg" }, "medium": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg" }, "high": { "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg" } }, "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }
Exemplo 4

URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics
Descrição: este exemplo modifica o parâmetro fields do exemplo 3 para que cada objeto snippet do recurso de vídeo inclua apenas as propriedades channelId , title e categoryId na resposta da API. Resposta da API:
{ "videos": [ { "id": "7lCDEYXw3mM", "snippet": { "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw", "title": "Google I/O 101: Q&A On Using Google APIs", "categoryId": "28" }, "statistics": { "viewCount": "3057", "likeCount": "25", "dislikeCount": "0", "favoriteCount": "17", "commentCount": "12" } } ] }

Otimizar a performance

Usar ETags

ETags, uma parte padrão do protocolo HTTP, permitem que os aplicativos consultem determinada versão de um recurso da API. O recurso pode ser um feed inteiro ou um item desse feed. Essa funcionalidade é compatível com os seguintes usos:

  • Caches e recuperação condicional - o aplicativo pode armazenar em cache os recursos da API e as ETags deles. Dessa forma, quando seu aplicativo solicitar novamente um recurso armazenado, especificará a ETag associada a esse recurso. Se o recurso tiver sido alterado, a API devolverá o recurso modificado e a ETag associada a essa versão do recurso. Se o recurso não tiver sido alterado, a API retornará uma resposta de HTTP 304 (Not Modified), indicando que o recurso não foi alterado. Seu aplicativo pode reduzir a latência e o uso de largura de banda oferecendo recursos armazenados em cache dessa maneira.

    As bibliotecas de clientes das APIs do Google diferem em sua compatibilidade de ETags. Por exemplo, a biblioteca de clientes de JavaScript é compatível com ETags por meio de uma lista de permissões para cabeçalhos de solicitação permitidos que inclui If-Match e If-None-Match. A lista de permissões possibilita o uso de caches comuns do navegador caso uma ETag do recurso não tenha sido alterada para que o recurso possa ser oferecido por meio do cache do navegador. Por outro lado, o cliente Obj-C não é compatível com ETags.

  • Proteção contra substituições acidentais de alterações - As ETags ajudam a evitar que os vários clientes da API substituam acidentalmente as alterações uns dos outros. Ao atualizar ou excluir um recurso, seu aplicativo pode especificar a ETag do recurso. Se a ETag não corresponder à versão mais recente desse recurso, a solicitação da API falhará.

O uso de ETags em seu aplicativo oferece diversas vantagens:

  • A API responde mais rapidamente às solicitações de recursos armazenados em cache que não foram alterados, resultando em menos latência e uso de largura de banda.
  • Seu aplicativo não substituirá acidentalmente as alterações de um recurso que foram feitas por outro cliente da API.

A Google APIs Client Library for JavaScript é compatível com cabeçalhos de solicitação HTTP If-Match e If-None-Match, portanto, as ETags podem funcionar dentro do contexto de caches comuns do navegador.

Usar Gzip

Você também pode reduzir a largura de banda necessária de cada resposta da API, permitindo a compactação com Gzip. Embora seu aplicativo precise de mais tempo de CPU para descompactar as respostas da API, a vantagem de consumir menos recursos da rede geralmente supera esse custo.

Para receber uma resposta codificada por Gzip, é preciso fazer duas coisas:

  • Definir o cabeçalho de solicitação HTTP Accept-Encoding como gzip .
  • Modificar seu agente de usuário para conter a string gzip.

Os exemplos de cabeçalhos HTTP abaixo demonstram esses requisitos para habilitar a compactação com Gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)