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 consiga as credenciais de autorização para que seu aplicativo possa enviar solicitações de API.

3. Após criar seu projeto, certifique-se de que a API de dados do YouTube seja 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 de APIs ativadas. Na lista de APIs, certifique-se de que o status esteja ATIVADO para a API YouTube Data v3.

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.

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 de pesquisa contém uma propriedade videoId, playlistId ou channelId que identifica um recurso específico de vídeo, playlist ou canal.

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ário a um vídeo, e o método thumbnails.set envia uma imagem de miniatura do vídeo para o YouTube e a associa a um vídeo.

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 oferecem suporte a solicitações autorizadas e não autorizadas. As solicitações não autorizadas recuperam apenas dados públicos, enquanto as solicitações autorizadas também podem recuperar informações sobre ou particulares do usuário autenticado no momento.

Uso de cota

O YouTube Data API usa uma cota para garantir que os desenvolvedores usem o serviço conforme o esperado e não criem aplicativos que reduzem injustamente a qualidade do serviço ou limitam o acesso de outras pessoas. Todas as solicitações de API, incluindo solicitações inválidas, incorrem em um custo de cota de pelo menos um ponto. Consulte a cota disponível para seu aplicativo no 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 esmagadora maioria de nossos usuários da API. A cota padrão, que está sujeita a alterações, nos ajuda a otimizar as alocações de cota e dimensionar nossa infraestrutura de forma 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, poderá solicitar cota adicional preencher a extensão de cota formulário de solicitação para serviços de API do YouTube.

Como calcular o uso de cota

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

• Uma operação de leitura que recupera uma lista de recursos -- canais, vídeos, listas de reprodução -- normalmente custa 1 unidade.
• Uma operação de gravação que cria, atualiza ou exclui um recurso geralmente gera custos 50 unidades.
• Uma solicitação de pesquisa custa 100 unidades.
• Um upload de vídeo custa 1600 unidades.

A tabela Custos de cota para solicitações de API mostra 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 envia 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 suporta dois parâmetros de solicitaçã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 somente propriedades específicas nas partes de recursos solicitadas.

Como usar o parâmetro part

O 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. Dessa forma, o parâmetro part exige que você selecione os componentes de recursos que seu aplicativo realmente usa. Esse requisito tem dois propósitos fundamentais:

• 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 dos recursos identificadas no valor de parâmetro part, para que a resposta inclua apenas um conjunto específico de campos. Com o parâmetro fields, é possível remover propriedades aninhadas de uma resposta da API e, assim, reduzir ainda mais o uso da largura de banda. O parâmetro part não pode ser usado para filtrar propriedades aninhadas 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 curinga para identificar todos os campos.
• Use parênteses (fields=a(b,c)) para especificar um grupo de propriedades aninhadas que serão incluídos 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 de parâmetros 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 demonstram como usar os parâmetros part e fields para garantir que as respostas da API incluam apenas os dados usados pelo 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 devolve um recurso de vídeo que inclui duas partes, mas exclui as propriedades kind e etag.
4. O exemplo 4 devolve um recurso de vídeo que inclui duas partes, mas exclui kind e etag, assim como algumas propriedades aninhadas no objeto snippet do recurso.

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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

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