Visão geral da API YouTube Data

Introdução

Este documento destina-se a desenvolvedores que desejam criar aplicativos que interajam com o YouTube. Ele explica os conceitos básicos do YouTube e da própria API. Também fornece uma visão geral das diferentes funções que a API suporta.

Antes de começar

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

  2. Crie um projeto no Google Developers Console e receba credenciais de autorização para que seu aplicativo possa enviar solicitações de API.

  3. Depois de criar o projeto, verifique se a API de dados do YouTube é um dos serviços que seu aplicativo está registrado para usar:

    1. Acesse o Console de APIs e selecione o projeto que você acabou de registrar.
    2. Acesse a página APIs ativadas. Na lista de APIs, verifique se o status da API YouTube Data v3 é ATIVADO.

  4. Se seu aplicativo usar um método de API que exige autorização do usuário, leia o guia de autenticação para saber como implementar a autorização OAuth 2.0.

  5. Selecione uma biblioteca de clientes para simplificar a implementação da API.

  6. 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.
channelSection Contém informações sobre um conjunto de vídeos que um canal escolheu destacar. Por exemplo, uma seção pode apresentar os envios mais recentes, os vídeos mais acessados ou vídeos de um canal usando uma ou mais playlists.
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.
i18nLanguage Identifica um idioma de aplicativo que tem suporte do site do YouTube. O idioma do aplicativo também pode ser chamado de idioma da IU.
i18nRegion Identifica uma área geográfica que um usuário do YouTube pode selecionar como região de conteúdo preferencial. A região de conteúdo também pode ser chamada de localidade de conteúdo.
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 correspondem aos 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 os próprios dados permanentes.
subscription Contém informações sobre a inscrição de um 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.
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.
watermark Identifica uma imagem que é exibida durante a reprodução dos vídeos de um canal especificado. O proprietário também pode especificar um canal de destino ao qual a imagem está vinculada, assim como detalhes de marcação de tempo que determinam quando a marca d'água aparece durante a reprodução do vídeo e por quanto tempo ela ficará visível.

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

Operações suportadas

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 classificação de usuário 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ções
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 aceitam solicitações autorizadas e não autorizadas, em que as solicitações não autorizadas apenas recuperam dados públicos, enquanto as solicitações autorizadas também podem recuperar informações sobre ou particulares ao usuário autenticado no momento.

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 cota

O YouTube Data API usa uma cota 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 outros. Todas as solicitações de API, incluindo as inválidas, geram pelo menos um custo de cota de um ponto. Veja a cota disponível para seu aplicativo em API Console.

Os projetos que ativam a API de dados do YouTube têm uma alocação de cota padrão de 10.000 unidades por dia, uma quantidade suficiente para a grande maioria de nossos usuários de API. A cota padrão, que está sujeita a alterações, nos ajuda a otimizar as alocações de cota e escalonar nossa infraestrutura de uma forma que seja mais significativa para os usuários da API. Veja o uso da sua cota na página Cotas no Console de APIs.

Observação:se você atingir o limite da cota, preencha o formulário de solicitação de extensão de cota para serviços de API do YouTube.

Calculando o uso da cota

O Google calcula o uso da cota atribuindo um custo a cada solicitação. Diferentes tipos de operações têm diferentes custos de cota. Exemplo:

  • Uma operação de leitura que recupera uma lista de recursos, como canais, vídeos e playlists, geralmente custa uma unidade.
  • Uma operação de gravação que cria, atualiza ou exclui um recurso geralmente tem custos 50.
  • Uma solicitação de pesquisa custa 100 unidades.
  • O envio de um vídeo custa 1600 unidades.

A tabela Custos de cota para solicitações de API mostra o custo de cota de cada método de API. Com essas regras em mente, é possível estimar o número de solicitações que o aplicativo poderia enviar por dia sem exceder a cota.

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 oferece suporte a dois parâmetros de solicitação, que são explicados nas seções a seguir, que permitem identificar as propriedades de recurso que devem ser incluídas nas respostas da API.

  • O parâmetro part identifica grupos de propriedades que precisam ser retornados para um recurso.
  • O parâmetro fields filtra a resposta da API para retornar apenas propriedades específicas nas partes do recurso solicitadas.

Como usar o parâmetro part

O parâmetro part é obrigatório para qualquer solicitação de API que recupera ou retorna um recurso. O parâmetro identifica uma ou mais propriedades do recurso de alto nível (não testadas) que devem ser incluídas em uma resposta da API. Por exemplo, um recurso video tem 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. Por isso, o parâmetro part exige que você selecione os componentes do recurso que seu aplicativo realmente usa. Esse requisito tem duas finalidades principais:

  • 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.

Como usar o parâmetro fields

O parâmetro fields filtra a resposta da API, que contém apenas as partes do recurso identificadas no valor do parâmetro part, para que a resposta inclua apenas um conjunto específico de campos. O parâmetro fields permite remover propriedades aninhadas de uma resposta da API e, com isso, reduzir ainda mais o uso da largura de banda. Não é possível usar o parâmetro part para filtrar propriedades aninhadas em 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 curinga para identificar todos os campos.
  • Use parênteses (fields=a(b,c)) para especificar um grupo de propriedades aninhadas que serão incluídas na resposta da API.
  • Use uma barra (fields=a/b) para identificar uma propriedade aninhada.

Na prática, essas regras geralmente permitem que diversos valores do parâmetro fields recuperem 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 com todos os valores de parâmetro de consulta, fields também precisa ter codificação de URL. Para facilitar a leitura, os exemplos neste documento estão sem a codificação.

Exemplos de solicitações parciais

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

  1. O exemplo 1 retorna um recurso de vídeo que inclui quatro partes, bem como as propriedades kind e etag.
  2. O exemplo 2 retorna um recurso de vídeo que inclui duas partes, bem como as propriedades kind e etag.
  3. O exemplo 3 retorna um recurso de vídeo que inclui duas partes, mas exclui as propriedades kind e etag.
  4. O exemplo 4 retorna um recurso de vídeo que inclui duas partes, mas exclui kind e etag, bem como algumas propriedades aninhadas 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

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "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

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "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)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "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

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "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 o desempenho

Como usar ETags

ETags, uma parte padrão do protocolo HTTP, permite que os aplicativos façam referência a uma versão específica de um recurso de API específico. 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 HTTP 304 (Not Modified), que indica 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 cliente JavaScript é compatível com ETags por meio de uma lista de permissões para cabeçalhos de solicitação permitidos que incluem 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.

O Google APIs Client Library for JavaScript oferece suporte a cabeçalhos de solicitação HTTP If-Match e If-None-Match, permitindo que as ETags funcionem dentro do contexto normal de armazenamento em cache 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:

  • Defina o cabeçalho da solicitação HTTP Accept-Encoding como gzip.
  • Modifique seu user agent 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)