Implementação: vídeos

Os exemplos a seguir mostram como usar a API YouTube Data (v3) para realizar funções relacionadas a vídeos.

Recuperar os vídeos enviados de um canal

Este exemplo recupera os vídeos enviados para um canal específico. Ele tem duas etapas:

Este exemplo mostra como recuperar uma lista dos vídeos mais populares do YouTube, que são selecionados usando um algoritmo que combina muitos indicadores diferentes para determinar a popularidade geral.

Para recuperar a lista de vídeos mais populares, chame o método videos.list e defina o valor do parâmetro chart como mostPopular. O gráfico mostPopular inclui músicas, filmes e vídeos sobre jogos em alta.

Em seguida, você pode definir os seguintes parâmetros:

  • regionCode: instrui a API a retornar uma lista de vídeos da região especificada. O valor de parâmetro é um código de país ISO 3166-1 alfa-2. Você pode usar o i18nRegions.list método para recuperar uma lista de códigos de região compatíveis com o YouTube.
  • videoCategoryId: identifica a categoria de vídeo para a qual os vídeos mais populares precisam ser recuperados. Você pode usar o videoCategories.list método para recuperar uma lista de IDs de categorias compatíveis com o YouTube.

Por exemplo, a solicitação a seguir recupera os vídeos de esportes mais populares na Espanha:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

Recuperar estatísticas de vídeos em lote

Este exemplo recupera estatísticas de uma lista de vídeos usando o método videos.batchGetStats.

Para usar esse método, defina o parâmetro id da solicitação como uma lista separada por vírgulas dos IDs de vídeos do YouTube para os quais você quer recuperar estatísticas. Defina o valor do parâmetro part como uma lista separada por vírgulas das partes do recurso videoStat que você quer que a resposta inclua. As partes compatíveis são snippet, statistics, contentDetails e id.

A autenticação é necessária para usar esse método em vídeos não públicos, mas não é necessária para vídeos públicos. Se a solicitação recuperar dados de vídeos não públicos, ela precisará ser autorizada corretamente.

A solicitação abaixo recupera estatísticas dos IDs de vídeo VIDEO_ID_1 e VIDEO_ID_2:

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

Fazer upload de um vídeo

Como o APIs Explorer não oferece suporte ao envio de arquivos, esta descrição não tem um exemplo executável. Os recursos a seguir vão ajudar você a modificar seu aplicativo para que ele possa enviar vídeos usando a API v3:

  • A documentação do método videos.insert da API contém vários exemplos de código que explicam como enviar um vídeo usando diferentes linguagens de programação.

  • O guia Uploads retomáveis explica a sequência de solicitações HTTP que um aplicativo usa para enviar vídeos usando um processo de upload retomável. O guia é destinado principalmente a desenvolvedores que não podem usar as bibliotecas de cliente de APIs do Google, algumas das quais oferecem suporte nativo a uploads retomáveis.

  • O exemplo em JavaScript para enviar um vídeo usa o CORS (compartilhamento de recursos entre origens) para demonstrar como enviar um arquivo de vídeo por uma página da Web. A biblioteca de upload do CORS que a API v3 usa oferece suporte nativo ao upload retomável. Além disso, o exemplo demonstra como verificar o status de um vídeo enviado recuperando a parte processingDetails do recurso video, bem como como lidar com mudanças de status do vídeo enviado.

Verificar o status de um vídeo enviado

Este exemplo mostra como verificar o status de um vídeo enviado. Um vídeo enviado fica imediatamente visível no feed de vídeos enviados do usuário autenticado. No entanto, o vídeo não fica visível no YouTube até ser processado.

  • Etapa 1: enviar o vídeo

    Chame o método videos.insert para fazer upload do vídeo. Se a solicitação for bem-sucedida, a resposta da API vai conter um recurso video que identifica o ID exclusivo do vídeo enviado.

  • Etapa 2: verificar o status do vídeo

    Chame o método videos.list para verificar o status do vídeo. Defina o valor do parâmetro id como o ID do vídeo obtido na etapa 1. Defina o valor do parâmetro part como processingDetails.

    Se a solicitação for processada com sucesso, a resposta da API vai conter um recurso video. Verifique o valor da propriedade processingDetails.processingStatus para determinar se o YouTube ainda está processando o vídeo. O valor da propriedade vai mudar para algo diferente de processing, como succeeded ou failed, quando o YouTube terminar de processar o vídeo.

    O corpo da solicitação é um recurso video em que a propriedade id especifica o ID do vídeo que você está excluindo. Neste exemplo, o recurso também contém um objeto recordingDetails.

    A solicitação abaixo verifica o status de um vídeo. Para concluir a solicitação no APIs Explorer, defina o valor da propriedade id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet,processingDetails
        &id=VIDEO_ID

Observação:seu aplicativo pode consultar a API para verificar periodicamente o status de um vídeo recém-enviado. Depois que o vídeo for processado, seu aplicativo poderá criar um boletim ou prosseguir com outra ação dependendo do status do vídeo.

Atualizar um vídeo

Este exemplo mostra como atualizar um vídeo para adicionar informações sobre a hora e o local em que ele foi gravado. O exemplo tem as seguintes etapas:

  • Etapa 1: recuperar o ID do vídeo

    Siga as etapas acima para recuperar os vídeos enviados do canal do usuário autenticado. A lista pode ser usada para mostrar uma lista de vídeos, usando o ID de cada vídeo como uma chave.

    Observação:há várias outras maneiras de conseguir IDs de vídeos, como recuperar resultados da pesquisa ou listar itens em uma playlist. No entanto, como um vídeo só pode ser atualizado pelo proprietário, recuperar uma lista de vídeos de propriedade do usuário que autoriza a solicitação de API é uma primeira etapa provável nesse processo.

  • Etapa 2: atualizar um vídeo

    Chame o método videos.update para atualizar um vídeo específico. Defina o valor do parâmetro part como recordingDetails. O valor do parâmetro depende dos campos de metadados do vídeo que estão sendo atualizados.

    O corpo da solicitação é um recurso video em que a propriedade id especifica o ID do vídeo que você está atualizando. Neste exemplo, o recurso também contém um objeto recordingDetails.

    O exemplo de recurso abaixo indica que o vídeo foi gravado em 30 de outubro de 2013, em Boston:

    {
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}

    Para concluir a solicitação no APIs Explorer, defina o valor da propriedade id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet

O acesso de marcas parceiras iniciado pelo criador de conteúdo (CI BPA, na sigla em inglês) permite que o proprietário de um vídeo compartilhe o acesso ao vídeo com um canal de marca parceira. Isso exige a parte brandPartner.

Estabelecer acesso (inserir)

Para estabelecer o acesso ao enviar um vídeo, inclua brandPartner no parâmetro part e forneça um objeto brandPartner no corpo da solicitação. Você precisa especificar channelId (ID do canal externo que começa com "UC") ou channelHandle (que começa com "@") para identificar o canal da marca.

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

Somente o channelId resolvido será retornado na resposta.

Atualizar ou remover o acesso (atualizar)

Para atualizar o acesso a um canal de marca diferente ou remover o acesso, chame o método videos.update com brandPartner no parâmetro part.

Para substituir o acesso, forneça o novo channelId ou channelHandle no corpo da solicitação:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

Para remover o acesso, envie uma solicitação com brandPartner no parâmetro part, mas com um objeto brandPartner vazio no corpo da solicitação:

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

Enviar uma imagem de miniatura personalizada e defini-la para um vídeo

Você pode usar o método thumbnails.set da API v3 para enviar uma imagem de miniatura personalizada e defini-la para um vídeo. Na solicitação, o valor do parâmetro videoId identifica o vídeo para o qual a miniatura será usada.

Essa consulta não pode ser testada usando o APIs Explorer porque ele não oferece suporte ao envio de arquivos de mídia, que é um requisito para esse método.

Exemplos de código relacionados: PHP, Python

Excluir um vídeo

Este exemplo mostra como excluir um vídeo. O exemplo tem as seguintes etapas:

  • Etapa 1: recuperar o ID do vídeo

    Siga as etapas acima para recuperar os vídeos enviados do canal do usuário autenticado. A lista pode ser usada para mostrar uma lista de vídeos, usando o ID de cada vídeo como uma chave.

    Observação:há várias outras maneiras de conseguir IDs de vídeos, como recuperar resultados da pesquisa ou listar itens em uma playlist. No entanto, como um vídeo só pode ser excluído pelo proprietário, recuperar uma lista de vídeos de propriedade do usuário que autoriza a solicitação de API é uma primeira etapa provável nesse processo.

  • Etapa 2: excluir um vídeo

    Chame o método videos.delete para excluir um vídeo específico. Na solicitação, o parâmetro id especifica o ID do vídeo que você está excluindo. A solicitação precisa ser autorizada usando o OAuth 2.0. Se você estiver testando essa consulta no APIs Explorer, substitua um ID de vídeo válido pelo valor do parâmetro id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
        id=VIDEO_ID

Denunciar um vídeo abusivo

Este exemplo mostra como denunciar um vídeo que contém conteúdo abusivo. O exemplo tem as seguintes etapas:

  • Etapa 1: recuperar os IDs que explicam por que o vídeo está sendo denunciado

    Envie uma solicitação autorizada ao método videoAbuseReportReasons.list para recuperar uma lista de motivos válidos para sinalizar um vídeo. O exemplo de recurso videoAbuseReportReason abaixo contém informações para sinalizar um vídeo que contém spam ou conteúdo enganoso.

    {
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

    Como mostrado no recurso, esse motivo está associado a uma lista de motivos secundários. Ao sinalizar um vídeo por conter spam, você precisa fornecer o ID do motivo e é altamente recomendável fornecer também um motivo secundário.

  • Etapa 2: sinalizar o vídeo por conteúdo abusivo

    Envie uma solicitação autorizada ao método videos.reportAbuse para denunciar o vídeo. O corpo da solicitação é um objeto JSON que identifica o vídeo sinalizado e o motivo da sinalização. Como observado na etapa 1, para alguns tipos de motivos, um motivo secundário é aceito e altamente recomendado.

    A propriedade videoId do objeto JSON identifica o vídeo que está sendo sinalizado.

    O exemplo de objeto JSON abaixo sinaliza um vídeo por conter spam ou conteúdo enganoso e, mais especificamente, por usar uma imagem de miniatura enganosa. Como mostrado no exemplo de objeto JSON acima, o ID do conteúdo spam ou enganoso é S. O ID de uma miniatura enganosa é 28.

    {
  "videoId": "VIDEO_ID",
  "reasonId": "S",
  "secondaryReasonId": "28",
  "comments": "Testing the video flagging feature.",
  "language": "en"
}

    A solicitação videos.reportAbuse precisa ser autorizada usando o OAuth 2.0. O link abaixo carrega o objeto JSON acima no APIs Explorer. Para testar a consulta, substitua um ID de vídeo válido pelo valor da propriedade videoId. Lembre-se de que o envio dessa solicitação vai sinalizar o vídeo.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse