Transferências de canal do YouTube

Com o conector do serviço de transferência de dados do BigQuery para YouTube, é possível programar e gerenciar automaticamente jobs de carregamento recorrentes para relatórios de canais do YouTube.

Relatórios compatíveis

• Relatórios de canais (carregados automaticamente no BigQuery)

Atualmente, o serviço de transferência de dados do BigQuery para relatórios de canais do YouTube é compatível com a seguinte opção de relatório:

Opção de relatório	Suporte
Versão da API compatível	18 de junho de 2018
Repetir frequência	Diariamente, aproximadamente às 14h10 UTC Você pode configurar a hora do dia
Atualizar janela	Último dia Não configurável.
Duração máxima do preenchimento	30 dias Desde julho de 2018, os relatórios do YouTube que contêm dados históricos ficam disponíveis por 30 dias a partir do momento em que são gerados. Relatórios que contêm dados não históricos ficam acessíveis durante 60 dias. Para mais informações, consulte Dados históricos na documentação da API YouTube Reporting.

Para saber como os relatórios de canais do YouTube são transformados em tabelas e visualizações do BigQuery, consulte Transformações de relatório de canais do YouTube.

Ingestão de dados de transferências de canal do YouTube

Quando você transfere dados de um canal do YouTube para o BigQuery, eles são carregados em tabelas do BigQuery que são particionadas por data. A partição da tabela em que os dados são carregados corresponde à data da fonte de dados. Se você programar várias transferências para a mesma data, o serviço de transferência de dados do BigQuery substituirá a partição dessa data específica pelos dados mais recentes. Várias transferências no mesmo dia ou preenchimentos não resultam em dados duplicados, e as partições de outras datas não são afetadas.

Atualizar janelas

Uma janela de atualização é o número de dias que uma transferência de dados recupera dados quando ocorre uma transferência de dados. Por exemplo, se a janela de atualização for de três dias e uma transferência diária ocorrer, o serviço de transferência de dados do BigQuery vai extrair todos os dados da tabela de origem dos últimos três dias. Nesse exemplo, quando uma transferência diária ocorre, o serviço de transferência de dados do BigQuery cria uma nova partição de tabela de destino do BigQuery com uma cópia dos dados da tabela de origem do dia atual e, em seguida, aciona automaticamente as execuções de preenchimento para atualizar as partições de tabela de destino do BigQuery com os dados da tabela de origem dos últimos dois dias. As execuções de preenchimento automático acionadas automaticamente vão substituir ou atualizar de forma incremental a tabela de destino do BigQuery, dependendo de se as atualizações incrementais são aceitas ou não pelo conector do serviço de transferência de dados do BigQuery.

Quando você executa uma transferência de dados pela primeira vez, ela recupera todos os dados de origem disponíveis na janela de atualização. Por exemplo, se a janela de atualização for de três dias e você executar a transferência de dados pela primeira vez, o serviço de transferência de dados do BigQuery vai recuperar todos os dados de origem em três dias.

As janelas de atualização são mapeadas para o campo da APITransferConfig.data_refresh_window_days.

Para recuperar dados fora da janela de atualização, como dados históricos, ou para recuperar dados de interrupções ou lacunas de transferência, inicie ou programe uma execução de preenchimento.

Limitações

• O tamanho máximo permitido do arquivo para cada relatório é de 1.710 GB.
• A frequência mínima para programar uma transferência de dados é de uma vez a cada 24 horas. Por padrão, uma transferência de dados começa no momento em que você cria a transferência. No entanto, é possível configurar o horário de início da transferência de dados ao configurar sua transferência.
• O serviço de transferência de dados do BigQuery não é compatível com transferências de dados incrementais durante uma transferência do proprietário do conteúdo do YouTube. Ao especificar uma data para uma transferência de dados, todos os dados disponíveis para essa data são transferidos.
• Não será possível criar uma transferência de dados de canal do YouTube se você tiver feito login como uma identidade federada. Só é possível criar uma transferência de canal do YouTube ao fazer login com uma Conta do Google.

Antes de começar

Antes de criar uma transferência de dados de canal do YouTube, confira estas informações:

• Verifique se você realizou todas as ações necessárias para ativar o serviço de transferência de dados do BigQuery.
• Crie um conjunto de dados do BigQuery para armazenar os dados do YouTube.

Permissões necessárias

Veja a seguir os requisitos para criar uma transferência de dados de canal do YouTube:

• YouTube: propriedade do canal do YouTube

• BigQuery: as seguintes permissões de gerenciamento de identidade e acesso (IAM, na sigla em inglês) no BigQuery:

  • bigquery.transfers.update para criar a transferência.
  • bigquery.datasets.get e bigquery.datasets.update no conjunto de dados de destino.
  • Se você pretende configurar notificações de execução de transferência para o Pub/Sub, é preciso ter permissões pubsub.topics.setIamPolicy. As permissões do Pub/Sub não serão necessárias caso você configure notificações por e-mail. Para mais informações, consulte Notificações de execução do serviço de transferência de dados do BigQuery.

O papel predefinido do IAM bigquery.admin inclui todas as permissões do BigQuery necessárias para criar uma transferência de dados de canal do YouTube. Para mais informações sobre os papéis do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Configurar uma transferência de canal do YouTube

A configuração de uma transferência de dados de canal do YouTube requer estes itens:

• Sufixo de tabela: um nome fácil de usar para o canal, fornecido por você ao configurar a transferência de dados. O sufixo é anexado ao ID do job para criar o nome da tabela, por exemplo, reportTypeId_suffix. O sufixo é usado para evitar que transferências separadas gravem nas mesmas tabelas. O sufixo da tabela precisa ser único em todas as transferências que carregam dados para o mesmo conjunto de dados. Além disso, o sufixo precisa ser curto para reduzir o comprimento do nome de tabela resultante.

Se você usa a API Reporting do YouTube no momento e tem jobs de relatórios atuais, o serviço de transferência de dados do BigQuery carregará os dados de relatório. Se você não tiver jobs de relatório, configurar a transferência vai ativar automaticamente os jobs de relatório do YouTube.

Para criar uma transferência de dados de canal do YouTube, faça o seguinte:

Console

1. Acesse a página "Transferências de dados" no console do Google Cloud.

   Acesse Transferências de dados

2. Clique em Criar transferência.

3. Na página Criar transferência:

   • Na seção Tipo de origem, para Origem, escolha Canal do YouTube.

     

   • No campo Nome de exibição da seção Transferir nome da configuração, insira um nome para a transferência de dados, como My Transfer. O nome da transferência pode ser qualquer valor que permita identificá-la, caso você precise modificá-la mais tarde.

     

   • Na seção Opções de programação, faça o seguinte:

     • Em Frequência de repetição, escolha uma opção para a frequência de execução da transferência de dados: Se você selecionar Dias, forneça um horário válido em UTC.

       • Horas
       • Dias
       • Sob demanda

     • Se aplicável, selecione Começar agora ou Começar no horário definido e forneça uma data de início e um horário de execução.

   • Na seção Configurações de destino, em Conjunto de dados de destino, escolha o conjunto criado para armazenar seus dados.

     

   • Na seção Detalhes da origem de dados:

     • Em Sufixo de tabela, insira um sufixo como MT.

     • Marque a caixa Configurar jobs para permitir que o BigQuery gerencie seus jobs de relatórios do YouTube. Se houver relatórios do YouTube que ainda não existam na sua conta, novos jobs de relatório serão criados para ativá-los.

       

   • (Opcional) Na seção Opções de notificação:

     • Clique no botão para ativar as notificações por e-mail. Quando você ativa essa opção, o administrador de transferência recebe uma notificação por e-mail se uma execução de transferência falhar.
     • Em Selecionar um tópico do Pub/Sub, escolha o nome do tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub da sua transferência de dados.

4. Clique em Salvar.

bq

Insira o comando bq mk e forneça a sinalização de execução da transferência --transfer_config. As sinalizações a seguir também são obrigatórias:

• --data_source
• --target_dataset
• --display_name
• --params

bq mk \
--transfer_config \
--project_id=project_id \
--target_dataset=dataset \
--display_name=name \
--params='parameters' \
--data_source=data_source

Em que:

• project_id é o ID do projeto;
• dataset é o conjunto de dados de destino na configuração da transferência.
• name é o nome de exibição da configuração de transferência. O nome da transferência de dados pode ser qualquer valor que permita identificá-la, caso você precise modificá-la depois.
• parameters contém os parâmetros da configuração da transferência criada no formato JSON. Por exemplo, --params='{"param":"param_value"}'. Para transferências de dados de canal do YouTube, você precisa fornecer o parâmetro table_suffix. Opcionalmente, você pode definir o parâmetro configure_jobs como true para permitir que o serviço de transferência de dados do BigQuery gerencie jobs de relatórios do YouTube para você. Se houver relatórios do YouTube que atualmente não existem para seu canal, novos jobs de relatório são criados para ativá-los;
• data_source é a fonte de dados: youtube_channel.

Observação: no momento, não é possível configurar notificações usando a ferramenta de linha de comando.

Também é possível fornecer a sinalização --project_id para especificar um projeto específico. Se --project_id não for especificado, o projeto padrão será usado.

Por exemplo, o comando a seguir cria uma transferência de dados de canal do YouTube chamada My Transfer usando o sufixo de tabela MT e o conjunto de dados de destino mydataset. A transferência de dados é criada no projeto padrão:

bq mk \
--transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"table_suffix":"MT","configure_jobs":"true"}' \
--data_source=youtube_channel

Cuidado: quando você cria uma transferência de canal do YouTube usando a ferramenta de linha de comando, a configuração da transferência é definida usando o valor padrão da Programação.

API

Use o método projects.locations.transferConfigs.create e forneça uma instância do recurso TransferConfig.

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to create youtube channel transfer config.
public class CreateYoutubeChannelTransfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableSuffix = "_test";
    Map<String, Value> params = new HashMap<>();
    params.put("table_suffix", Value.newBuilder().setStringValue(tableSuffix).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Youtube Channel Config Name")
            .setDataSourceId("youtube_channel")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .build();
    createYoutubeChannelTransfer(projectId, transferConfig);
  }

  public static void createYoutubeChannelTransfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Youtube channel transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Youtube channel transfer was not created." + ex.toString());
    }
  }
}

Observação: se estiver configurando jobs de relatórios do YouTube pela primeira vez, você precisará aguardar um período de até 48 horas para que os primeiros relatórios fiquem prontos. Para mais informações, consulte Criar um job de relatórios na documentação da API YouTube Reporting.

Consultar dados

Quando os dados são transferidos para o BigQuery, eles são gravados em tabelas particionadas por tempo de processamento. Para mais informações, consulte Introdução às tabelas particionadas.

Use a pseudocoluna _PARTITIONTIME para consultar suas tabelas diretamente em vez de usar visualizações geradas automaticamente. Para mais informações, veja Como consultar tabelas particionadas.

Resolver problemas de configuração de transferência de canal do YouTube

Em caso de problemas ao configurar a transferência de dados, consulte Problemas na transferência do YouTube, em Solução de problemas de configurações de transferência.